From 422db49121efc660550874ec4381c5827fab0607 Mon Sep 17 00:00:00 2001 From: Takumi Sueda Date: Mon, 19 Oct 2020 13:49:48 +0900 Subject: [PATCH] =?UTF-8?q?Updated=20Wiki=E3=81=AE=E7=AE=A1=E7=90=86=20(ma?= =?UTF-8?q?rkdown)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Wikiの管理.md | 47 ------------------------------------ Wikiの編集方法.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+), 47 deletions(-) delete mode 100644 Wikiの管理.md create mode 100644 Wikiの編集方法.md diff --git a/Wikiの管理.md b/Wikiの管理.md deleted file mode 100644 index 5948ab0..0000000 --- a/Wikiの管理.md +++ /dev/null @@ -1,47 +0,0 @@ - - -### 目次 - -- [準備](#%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) - - - -# 準備 - -依存ライブラリをインストールする。 - -```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) を使う。 - diff --git a/Wikiの編集方法.md b/Wikiの編集方法.md new file mode 100644 index 0000000..33fda41 --- /dev/null +++ b/Wikiの編集方法.md @@ -0,0 +1,61 @@ + + +### 目次 + +- [準備](#%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) + + + + +# 準備 + +依存ライブラリをインストールする。 + +```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) を使ってください（左からコピペして使うと楽）。