Hatena::ブログ(Diary)

shouhの日記

2016-09-26

Markdown ファイルから目次(TOC)ファイルをつくる Python スクリプトを書いた

GitHub で書く Markdown は非常に便利で、リポジトリをドキュメントサイトや小説公開場として使うこともできるほどですが、一つだけ不便な点があります。

それは目次をつくるのがしんどいことです。手作業でちまちまつくらないといけないですし、ファイルの中身やフォルダ構造を変えたらその都度更新しないといけません。面倒くさすぎです。

これに耐えられなかったので、目次ファイルをつくるスクリプトを書いてみました(元は個人用でしたが対外向けに整備して公開してみました)。

md2toc

リポジトリはこちらです。

shouh/md2toc: Generate a TOC(Table Of Contents) from markdown files in the current directory for GitHubber.
https://github.com/shouh/md2toc

どんな感じが知りたい方はこちらのデモはご覧ください。

md2toc/demo at master ・ shouh/md2toc
https://github.com/shouh/md2toc/tree/master/demo

煩雑なコマンドラインと拙い英語はご容赦いただくとして(苦笑)、md2toc を使うと、配置してる Markdown ファイルたちをサブフォルダ含めて辿り、目次にしてくれます。ファイルが十個以上あっても、フォルダ階層が深くても、全部辿ってくれて、一つの目次ファイルにしてくれます。各見出しへのリンクも張れるので GitHub 上で閲覧するのに便利です。

Python スクリプトなのでちょっとハードルが高いところはごめんなさい。が、バッチファイルでくるんでやればダブルクリックだけで目次ファイルをつくれるようになったりもします。

コンセプト(技術的な話)

目次をつくるスクリプトは他にも存在しますが、ここでは md2toc の強みというかポイントを、コンセプトの紹介を以て説明したいと思います


『コンセプト1: リンク先のアンカー名(a nameタグ)を明示的に指定する』

これはmd2toc の面倒くさい仕様です。いちいち見出しに「a name タグ」を書かないと、目次ファイルからその見出しにリンクされないからです。ですが、これのおかげで、a name タグをちゃんと指定さえすれば確実にリンクを張ることができます。

多くの目次生成スクリプトGitHub のアンカー名生成アルゴリズムに頼った実装となっているため、日本語や記号を含む見出しへのリンクが正しく行われなかったりします。たとえば「# 『見出し』」という見出しのアンカー名は「『見出し』」ではなく「見出し」です(『』が取れます)。見出しの本文をそのまま使ってるわけじゃないので、そのまま使ってると思い込んでるスクリプト達は「見出し」というアンカー名でリンクを張ってしまい、結果としてリンク先にジャンプできない事態が起きます。

この md2toc の仕様は、特に日本語を多用するドキュメントや小説で有用だと思います。まあそんなテキストを書いて運用している人は現状ほとんどいないわけですが(苦笑)


『コンセプト2: 指定ディレクトリ配下の全ファイルに対する目次をつくるということ』
目次生成スクリプトとしてよくあるのが「今編集中の Markdown ファイルに対する目次を挿入する」というものです。あるファイルの目次を挿入したい用途ならそれでいいのでしょうが、多数のファイルの目次をつくることはできません。それが行えるスクリプトが見当たらなかったので、md2toc を作った次第です。


『コンセプト3: ヘッダ、フッタ、絵文字など』
md2toc では生成した目次ファイルの見易さをカスタマイズできます。具体的には目次ファイルの前後に固定文字列(ヘッダとフッタ)を指定したり、目次の各項目を表すアイコンとして Emoji を使うこともできます。これらを工夫すれば、目次ファイルはだいぶ見やすく使いやすいものになると思います。

おわりに: 小言

コードばかり謳われる GitHub ですが、テキスト保管庫やテキスト公開場としても優れていると思うんですよね。それこそテキストサイトを運用したり小説を書いたりできるポテンシャルも十分にあります。

私はそんなところを追求したいと思っています。md2toc も、そんな用途を助長する一手段としてつくりました(英語や配布形態などまだまだ未熟ですが)。