マークダウンでメモを書いたりブログを書いたりしていたけど、kobito-cliでPDF化すると見た目もなかなか良いということもあって、そこそこしっかりしたドキュメントもKobitoでマークダウンするのが最近自分の中での流行りになってきた。
ただそこそこ量がある報告書っぽい文書となると見出し番号があったほうがわかりやすいというのが正直なところ。見出し番号はマークダウン自身の仕様ではカバーされていない（はず）なので、マークダウンを使うのであれば別の方法と組み合わせる必要がある。
- pandoc
- CSS
- 手動で番号をつける
- 自動で番号をつける
pandocを使っていたこともあったが、使い勝手がそんなに良くない（お手軽じゃない）し、見た目もいまいちになりがちなのでトータルでKobitoに劣る。
CSSを使うという手は十分にありえる。kobito-cliからブラウザで開いたときに指定されているCSSに追記するなり差し替えるなりして、見出しに番号を振るようにするのは有り。
手動/自動で番号をつける、というのは、## ◯◯についてとなっているところを## 2.1 ◯◯についてなどと数字を直接書いてしまう方法だけど、手動でこれをやるのはかなり辛いため現実的ではない。
今回は以上の4種類の方法の中から自動で番号を振るという方法を取ることにしてみた。もっといい方法があったら知りたい。
Gem
そのライブラリをRubyで書いてGemとして配布するようにした。
markdown_section_numbering | RubyGems.org | your community gem host
ちなみにGitHubはこちら。
xoyip/markdown_section_numbering
使い方
% gem install markdown_section_numberingでインストールできる。
require "markdown_section_numbering"
markdown = <<MD
# a
## b
foo bar
## c
- list
- list
- list
MD
puts MarkdownSectionNumbering.convert(markdown)
このコードを実行すると、↓のように変換されたマークダウンが得られる。
# 1 a
## 1.1 b
foo bar
## 1.2 c
- list
- list
- list
見出し番号の付け直しにも対応していて、すでに見出し番号がついているこのようなマークダウンを渡すと、
# foo
# 1 a
## 1.1 b
## bar
## 1.2 c
新しい見出し番号が付いたマークダウンが返ってくるようになっている。
# 1 foo
# 2 a
## 2.1 b
## 2.2 bar
## 2.3 c
これによって編集中でもとりあえずの見出し番号をつけて見やすくできるし、変更があれば再び見出し番号を付け直せばいいだけだから割と使い勝手も悪くないんじゃないかと個人的には思っている。
現実的な使い方
ライブラリ化をしたはいいが、毎回コマンドを叩くというもの現実的ではない。そんな面倒なプロセスであれば使わなくなってしまう。僕の場合はAutomatorで作ったサービスと連携して、ショートカット一発で呼び出せるようにしていて、流れとしてはこんな感じになっている。
- マークダウンの文書を全選択
- 指定したショートカットキーでサービス起動
- 選択中の文字列が結果で置き換わる
スクリプトを書く
Automatorからこのライブラリを呼び出すためのスクリプトを書いておく。
require "markdown_section_numbering"
input = $stdin.read
puts MarkdownSectionNumbering.convert(input)
標準出力を受け取ってライブラリに渡し、結果を出力するだけのコード。
サービスを作る
Automator.appを起動し、サービスを作る。
左側のアクション一覧のライブラリ→ユーティリティから「シェルスクリプトを実行」を右側にドラッグ&ドロップする。そしてシェルスクリプトのところにさっき作ったスクリプトを呼び出すように書いてあげればよい。
他の設定も含めると最終的にはこのような感じになる。
これで保存して終了すればOK。
テキストを選択した状態でメニューバーからサービスを起動すると、選択中のマークダウンを見出し番号つきのものに変換した上で元のテキストを置き換えてくれるというわけだ。
ショートカットをアサインする
システム環境設定→キーボード→ショートカットからサービスにショートカットを割り当てることができるようになる。メニューから選ぶよりかは楽になる。
Gemを書いたお話と、Automatorで便利に使う方法を紹介しました。