Markdown のいくつかの方言ではタグを記述することで目次を自動挿入することが出来るみたいですが、GitHub ではその機能は実装されていません。でもテキストが長くなってくると、目次欲しいなあと思うんですよね。自力で作ることももちろん出来ますが、面倒くさいし漏れが出がち。多くの先人も同じこと考えていたみたいで、環境に合わせていろいろなツールがあります。
僕の場合Atomエディタを使っているので、このAtomパッケージを使えば目次を挿入できるらしいってことがわかりました。
markdown-toc
これをインストールして、実行すれば動くはずなのですが……僕の環境では次の様な問題が。
- 日本語見出しへのリンクが正しくない
- プロジェクト毎に1ページしか目次を作ってくれない
見出しに日本語が含まれていると、次の様な感じになって正しくリンクしてくれません。
- [PHP 7.2 のインストール](#php-72-)またページ1で目次を作ったあとページ2を編集してそこで目次を追加しようとしても、ページ1に追加されてしまいます。
日本語見出し対応版をインストールする
日本語見出しについては、こちらに情報がありました。Atomのmarkdown-tocでタイトルが日本語の場合に動かない場合の対処 – 山ｐの楽しいお勉強生活
結論
markdown-tocをforkして対応してくれてる人がいるので↓のコマンドでインストールしてAtom再起動。
というわけで、一旦 markdown-toc を削除した上で次のコマンドで対応版をインストール。
apm install https://github.com/Sorix/markdown-toc/Atom を再起動して試してみたところ、きちんと日本語対応の目次が作成されました。
- [PHP 7.2 のインストール](#php-72-のインストール)またなぜか、2番目の問題も解決。これも日本語に由来する問題だったのかな？
（ファイル名が日本語だったし）
対応版を作ってくれた Sorix さんと情報をくれた id:yamap55 に感謝。
オマケ：markdown-toc の設定
パッケージ自体には設定はありませんが、目次と一緒に挿入されるコメントを編集することで設定が出来ます。<!-- TOC depthFrom:1 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 -->- depthFrom → 目次をどこから始めるか。「2」に設定するとh1を無視します。
- withLinks → リンクを貼るかどうか。「1」でリンク付き「0」でテキストのみ
- updateOnSave → ファイル保管時に目次を更新するかどうか。「1」で更新する「0」で更新しない
- orderedList → 数字付きリストにするかどうか。「1」で数字付きリスト「0」で普通のリスト
