GitHubに作った自作プロジェクトのドキュメントをMarkdownで書いたら長くなったのでTable of Contents(TOC)すなわち目次を付けたくなった。2023年5月末時点のGitHubで何ができるかを調べた。いとも簡単にできた。

READMEにTOCを付けたい

プロジェクトのルート・ディレクトリ直下に置いたREADME.mdファイルに２つ以上のheaderつまり先頭が#で始まる行があれば、それだけでOK。何もしなくても、GitHubの画面上でTOCが表示されました。

サンプルを示そう。たとえば

https://github.com/kazurayam/adoc2md/

をブラウザで開くとファイル名の左隣にボタンが表示されている。

そのボタンをクリックするとTOCが表示された。

このTOCはGitHubのアプリが自動的に生成したもの。README.mdファイルの中にはこのTOCに相当する行はない。GitHubのサーバーアプリがREADME.mdファイルを読み込み#で始まるheader行を選択して、それに基づきリンクメニューとしてのTOCを動的に生成してくれる。

GitHub Pagesを使って作ったドキュメントにTOCを付けたい

プロジェクトのルートディレクトリの下に docs ディレクトリを作り、その中に　 index.md ファイルを作った。最初作った index.md ファイルは次のようなもの:

# Lorem ipsum

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

## Ut enim ad minim veriam

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

...

みての通り、行頭が#で始まるheader行と平文があるだけで、TOCを生成するための呪文は書いていない。このままでTOCは生成できない。そこで"GitHub Pages Markdown TOC"とキーワードを指定してGoogle検索した。そうしたら次のページに遭遇した。

http://www.seanbuscay.com/blog/jekyll-toc-markdown/

このページの教えに従って docs/index.md ファイルを次のように修正した。ファイルの先頭に呪文を2行だけ追記した。

- Table of Content
{:toc}

# Lorem ipsum

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

## Ut enim ad minim veriam

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

...

修正したMarkdownファイルをaddしてcommitしてpushした。

https://kazurayam.github.io/adoc2md/

ご覧のとおり、GitHub Pagesの応答画面上でTOCが付加されて表示されている。

TOCの各行がlinkになっている。TOCのlinkをマウスでクリックすればドキュメントの中のheaderへジャンプする。link切れがないかどうか調べようと全部試した。headerの文中に&、-、_などの特殊記号を含む場合もリンク切れしていない。headerの文が英数字ではなく日本語の漢字ひらがなカタカナ文字を含む場合もリンク切れしていない。完璧だ。

はてな？　いつから？

2022年4月にわたしはGitHub Pagesに作ったMarkdownドキュメントにTOCを付けたいと思って実現方法を調べた。その時点ではGitHubがTOCを組み込みで提供してくれていないと了解した。そこで外付けのツールを使ってHTML要素<a href="#target">から成るTOCを生成し.mdファイルに挿入する方法を試した。この方法で書き換えた.mdをブラウザで開くと、GitHubが.mdをHTMLに変換したものをブラウザ上で見ることになる。ところが残念ながらTOCから本文へのリンクが切れてしまっているケースがあった。見出しの中に:や&などの特殊文字が含まれているとダメだった。今回、2023年5月、GitHubを調べ直した。そしたらなんと、TOCが組み込みでサポートされていることに気づいた次第。

いつからTOCがGitHubに組み込まれたんでしょう？　もともとOKだったのか？不覚にも小生、今まで気づきませんでした。