md-to-pdf で Markdown から PDF に変換: 見出しに独自の ID を指定する
業務では、社内で扱う情報や外部へ提出する文書など、PDF 形式で情報を共有する必要に迫られることがある。しかし、エンジニアにとっては、プログラムのソースコードやドキュメントなどは普段から Markdown や plain text で取り扱い、そのまま共有することに慣れているため、PDF 形式での情報共有に苦手意識を抱く人も多いのではないだろうか。
一方で、世の中を見渡してみると、非エンジニアな人々には Markdown アレルギーな体質の人が多いらしい。ここは譲り合いの精神で、Markdown を PDF に変換してあげるべきだろう（彼らだって、本当は Word ドキュメントでほしいのを我慢しているのかもしれないし...）。
md-to-pdf の紹介
VSCode エディタには、Markdown ファイルを PDF にエクスポートするための多くの拡張機能が存在する。たとえば、Markdown Preview Enhanced や Markdown PDF を使用することで、ひとつのMarkdown ファイルを簡単に PDF に変換することができる。
しかし、今回は別の手段として md-to-pdf [1] を紹介したい。md-to-pdf を使用することで、複数のMarkdown ファイルをひとつの PDF 文書にまとめることができる。それだけでなく、コマンドラインで操作できるため、CI/CDパイプラインに組み込むことができる（今後もアップデートがありうる文書では重要）。
また、npm で簡単にインストールできるし、md-to-pdf のコマンド一発で PDF を出力できるので、普段使いのツールとしても気軽に使うことができる。
md-to-pdf の基本的な使用方法に関しては公式のページや他の記事に譲るとして、この記事では、Markdown の見出しに独自の ID を割り当てる方法を紹介したい。
md-to-pdf で見出しに独自の ID を指定したい
md-to-pdf のデフォルト設定では、見出しの ID が見出しのタイトルから自動で振られる。
しかし、これではタイトルを変更すると ID も変わってしまい、他の箇所から参照しているリンクが壊れてしまう。やってみると分かるのだが、マニュアルのように目次が必須の文書だと、この仕様はけっこうつらい。
そこで、この記事では、md-to-pdf を使って独自の ID を指定する方法を紹介したい。これによって、見出しに必要な ID を指定することができ、タイトルの変更にも柔軟に対応できるようになる。
Markdown の拡張構文: 見出しに独自 ID
まずは、Markdown の拡張構文で見出しに独自の ID を指定する構文を確認しよう。
### My Great Heading {#custom-id}
この Markdown は、次の HTML に変換される。
<h3 id="custom-id">My Great Heading</h3>
md-to-pdf での設定方法
md-to-pdf が Markdown の変換に利用している Marked では、デフォルトでは自動的に ID が割り振られるだけだが、拡張機能をインストールすることでさまざまな拡張が可能になる。ここでは、marked-custom-heading-id 拡張機能を使って、独自の ID 指定を可能にする。
まず、marked-custom-heading-idをインストールしよう。
$ npm i -D marked-custom-heading-id
次に、md-to-pdfの設定ファイル（md-to-pdf.config.js）に、Marked のオプションと拡張機能を追加する。
// md-to-pdf configuration
const customHeadingId = require("marked-custom-heading-id");
module.exports = {
marked_options: {
headerIds: false,
smartypants: true,
},
marked_extensions: [customHeadingId({})],
pdf_options: {
format: "A5",
margin: "30mm 20mm",
printBackground: true,
},
};
このように設定ファイルを作成し、md-to-pdfコマンドを実行する際に、--config-fileオプションを指定して、設定ファイルを渡すことができる。
$ md-to-pdf --config-file md-to-pdf.config.js
これで、md-to-pdf で見出しに独自の ID を使えるようになった。
md-to-pdf には他にもタイトルページの設定やカスタムスタイルシートによる調整など、痒いところに手が届く設定が用意されている。オプションについては README に書かれているので、使う前に一度確認してみてほしい。
また、Markdown には多くの拡張構文があり、Markdown プロセッサによってはオプションでサポートされているものも多い。たとえば、今回紹介した Marked では拡張機能によって構文を拡張することができる。何かドキュメントを書くときに Markdown の表現力では物足りなくなってきたらこれらの拡張に目を通してみるのもいいだろう。
Discussion