brain-hackers_pepepper-mirror/README
1
0
Fork 0
mirror of https://github.com/brain-hackers/README synced 2024-12-22 12:10:04 +09:00
Code Issues Projects Releases Wiki Activity

Updated Wikiの管理 (markdown)

Takumi Sueda 2020-10-19 13:49:48 +09:00
parent 96a3b47ac7
commit 422db49121
2 changed files with 61 additions and 47 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
Wikiの管理.md

@ -1,47 +0,0 @@
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
### 目次
- [準備](#%E6%BA%96%E5%82%99)
- [各文章内の目次生成](#%E5%90%84%E6%96%87%E7%AB%A0%E5%86%85%E3%81%AE%E7%9B%AE%E6%AC%A1%E7%94%9F%E6%88%90)
- [ファイル名とサイドバーの関係](#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E5%90%8D%E3%81%A8%E3%82%B5%E3%82%A4%E3%83%89%E3%83%90%E3%83%BC%E3%81%AE%E9%96%A2%E4%BF%82)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
# 準備
依存ライブラリをインストールする。
```sh
$ npm install -g doctoc
$ pip3 install markdown
```
WikiをCloneする。
```sh
$ git clone https://github.com/brain-hackers/README.wiki.git
```
# 各文章内の目次生成
各文章内の目次は、[doctoc](https://github.com/thlorenz/doctoc)で生成している。 `make doctoc` で呼ぶことが出来る。
本来は `_Sidebar.md` は目次生成の対象外とすべきだが、 doctoc はファイル名にスペースが入ると正しくエスケープできないバグを抱えていて `_Sidebar.md` だけ除外するということができない（PRも出ているが、2020年10月現在Mergeされていない）。よって、目次生成を走らせた後は `_Sidebar.md` をコミットしないよう注意する必要がある。
# ファイル名とサイドバーの関係
サイドバーの目次は、Wikiに含まれるMarkdown文書のファイル名から `gen.py` で自動生成している。 `make generate` で呼ぶことが出来る。Wiki に文書を追加する度に実行してコミットする。
ファイル名に ` > `（前後にスペース必須）が含まれていると、その左側はセクション名と解釈される。
例えば、ページ `あ > か.md` は大見出し `あ` の下に箇条書きで `か` として描画される。
`あ > い.md` と `あ > い > う.md` は同時に存在できない。 `い` が単一のページなのかセクション名なのか区別できないからである。
` > ` はファイル名の中で2回まで使える。 `あ.md` や `あ > い > う.md` は valid だが、 `あ > い > う > え.md` は invalid となる。
ページ名にハイフン `-` (Hyphen-Minus, U+002D) を使いたい場合、そのままファイル名に入れるとページ名ではスペース扱いになってしまう。これを回避するために、よく似た別なUnicode文字 `‐` (Hyphen, U+2010) を使う。

61
Wikiの編集方法.md Normal file

@ -0,0 +1,61 @@
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
### 目次
- [準備](#%E6%BA%96%E5%82%99)
- [各文章内の目次生成](#%E5%90%84%E6%96%87%E7%AB%A0%E5%86%85%E3%81%AE%E7%9B%AE%E6%AC%A1%E7%94%9F%E6%88%90)
- [ファイル名とサイドバーの関係](#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E5%90%8D%E3%81%A8%E3%82%B5%E3%82%A4%E3%83%89%E3%83%90%E3%83%BC%E3%81%AE%E9%96%A2%E4%BF%82)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
# 準備
依存ライブラリをインストールする。
```sh
$ npm install -g doctoc
$ pip3 install markdown
```
WikiをCloneする。
```sh
$ git clone https://github.com/brain-hackers/README.wiki.git
```
# 各種操作
注意: ページの編集後はサイドバーと各ページの目次の更新が必要です。ページの追加や編集をWebで行うことも可能（プレビューもあって便利）ですが、編集後は必ずWikiをCloneして `make finalize` してください。
## ページを追加・削除する
- [ファイル名とサイドバーの関係](#ファイル名とサイドバーの関係)のルールに従ったファイル名でmdファイルを追加
- 例: `大見出し ＞ 小見出し ＞ 項目.md`
- 記事内容を記述する
- ひととおり追加と削除が終わったら pull, `make finalize`, commit, push
## ページを編集する
- 記事内容を記述する
- ひととおり編集が終わったら pull, `make finalize`, commit, push
# 各文章内の目次生成
各文章内の目次は、[doctoc](https://github.com/thlorenz/doctoc)で生成しています。 `make finalize` もしくは `make doctoc` で呼ぶことができます。
`_Sidebar.md` はページではないため目次生成の対象外ですが、「指定されたファイル名にスペースが入ると正しくエスケープできない」という doctoc のバグにより、 `_Sidebar.md` 以外だけ指定するということができません（PRも出ているが、2020年10月現在Mergeされていない）。よって、目次生成を走らせた後は `_Sidebar.md` をコミットしないよう注意する必要があります。
# ファイル名とサイドバーの関係
サイドバーの目次は、Wikiに含まれるMarkdown文書のファイル名から `gen.py` で自動生成しています。 `make finalize` もしくは `make generate` で呼ぶことができます。Wiki に文書を追加するか、ファイル名を変更するたびに実行する必要があります。
ファイル名に ` ＞ ` **（不等号は全角・前後にスペース必須）** が含まれていると、その左側はセクション名と解釈されます。
例えば、ページ `あ ＞ い.md` は大見出し `あ` の中の `い` というページとして認識されます。
`あ ＞ い.md` と `あ ＞ い ＞ う.md` は同時に存在できません。 `い` が単一のページなのかセクション名なのか区別できないからです。
サイドバーの制約から、 ` ＞ ` はファイル名の中で2回まで使えます。 `あ.md` や `あ ＞ い ＞ う.md` は valid ですが、 `あ ＞ い ＞ う ＞ え.md` は invalid です。
ページ名にハイフン `-` (Hyphen-Minus, U+002D) を使いたい場合、GitHub Wiki はハイフンを空白文字と同等に扱うため、そのままファイル名に入れると空白に置き換わって表示されてしまいます。これを回避するために、よく似た別なUnicode文字 `‐` (Hyphen, U+2010) を使ってください（左からコピペして使うと楽）。