AH Formatter を用いた Markdown-PDF 変換事例紹介

概要

AH Formatter を用いた Markdown-PDF 変換事例紹介（PDF）
この文書は、次のような方に向けた事例紹介です。

• Visual Studio Code で、ソフトウェア開発に付随する報告書などの作成も行いたい
• 文書は Markdown で執筆し、PDF で提出したい
• コマンドライン操作のみで PDF ビルドが完了するようにしたい
• GitHub における Markdown 表示のようなスタイリングにしたい
• PDF には表紙や目次、ノンブル（ページ番号）を付けたい
• 目次には、項目タイトルとページ番号、ドキュメント内リンクが自動的に生成されてほしい
• ノンブルは、表紙や目次を除いた本文ページのみに振りたい
• PDF には余計なプロパティを含めたくない

上記の要件を全て満たす PDF を得るために筆者が用いたフローを紹介します。（上記の要件の一部が不要であれば、また違ったフローがあり得るでしょう。）

なお、この PDF の作成に用いたソースファイル一式は GitHub で公開していますので、実際に Markdown 原稿から PDF へのビルドを体験いただけます。

• https://github.com/2SC1815J/md2pdf
• https://github.com/2SC1815J/md2pdf/tree/en (English Version, README)

AH Formatter を選定した理由

Markdown を PDF に変換するフローとしては、ブラウザのレンダリング機能を利用する手法や、Pandoc を利用し LaTeX を経由して PDF を得る手法がよく知られています。しかし、前者は組版機能が十分ではないケースや、グラフィカルユーザインターフェイスでの操作を必要とするケースもあり、後者は見た目の調整に TeX の知識が必要です。一方で、『AH CSS Formatter』は、これらの点を次のとおり解決していることから導入となりました。

• 表紙や目次を除いてノンブルを振るなどの組版処理が可能
• コマンドライン操作のみで完結し、繰り返しビルドが容易
• TeX の知識がなくても PDF の見た目を調整可能