はじめに
初めまして、「ともにつくる、つぎをつくる。～いつでもどこでもお客様とともに～ グローバルトップのソリューションパートナー」東芝テック株式会社の加藤秀幸です。現在、リテール・ソリューション事業本部、ELERA™プラットフォーム開発部にてPOSシステムの開発を行っています。以前はMFP/複合機（コピー、プリンター、スキャナー、FAX）のデバイスおよびドキュメント・ソリューションの開発に長らく携わっていました。今回はそのドキュメント・ソリューションの話になります。
概要
複数ファイルで構成されたMarkdownファイル群をいい感じに連結し印刷可能なPDFにする。もちろん適切な章番号も振って表紙も目次も入れてしまおうという話です。
具体的なフローを下記図に示すと
- VSCode等のエディタでMarkdownを編集
- 静的ドキュメントサイト化
- そしてPDF化
になります。
紙文書から電子文書へ
昔は技術者の間でも各種技術文書は紙で配布することがほとんどでした。しかし、昨今は紙への印刷機会はめっきり減りました。特にコロナ禍や在宅勤務の普及による印刷ボリュームの減少は著しいです。この点、あくまでも印刷ソリューションを担当してきた者として少し寂しいところです（もちろんDX化により紙を減らすことはエコで素晴らしいことだとは思ってはいますが）。
そこで広く利用される電子文書の配布形式がご存知の通りPDFです。Microsoft Office製品なども標準でPDFへの出力が用意されていると思います。一方、技術文書はどうでしょう。一般的にソフトウェアのREADMEやWeb上のドキュメントサイトとしては軽量マークアップ言語としてMarkdownを利用することがほとんどだと思います（AsciiDocやreStructuredTextなどもありますが）。もちろん今記述しているQiitaの記事もMarkdownです。このMarkdown形式のものをPDFに変換できるとドキュメントの配布等で利便性が出てくるかと思っています。
Markdownで記述する意味
いや、私はWordでも良いし。マークアップならAsciiDocだと色々できていいじゃん。という声もあるかと思います。
Microsoft Office
前述のようにMicrosoft Officeで書いてPDFに変換しても良いのです。過去の多くのプロジェクトでは私の知る限りWord/Excel/PowerPointで書かれています（少なくとも他社様からいただく納品物等の大半はそうです）。しかし、大規模な文書を複数人で編集する場合の競合やGit等でのバージョン管理などはなかなか難しいものがあります。
他のマークアップ言語
こちらも前述の通りAsciiDocやreSTなど他のマークアップ言語の選択肢もあります。Pro Git bookがAsciiDocで書かれている通り、大規模なドキュメントはAsciiDocなどの方が適しているかもしれません。
やっぱりMarkdownが好き
しかし、開発者が日常で一番利用している記法はなんでしょうか？GitHub/GitLabなどのIssueの書式もMarkdownです。やっぱりMarkdownなんです。異論はあるかと思いますが、ほとんど開発者が日常利用して簡単に書けることを重視するとこれになります。
とは言ってもMarkdownは方言や実装の差がありすぎてツライ面も否めないですが…。ここはプロジェクトで統一した書式を守ることで目を瞑りましょう。
MarkdownからPDFへの変換
一枚ペラのドキュメント
単純な一枚ペラのドキュメントならば、Markdown専用エディタや多くの人がコーディングで使っているVS Codeで簡単にPDFは作れると思います。
例えば、VS Codeの場合、次の機能拡張です。
また、単体ツールや汎用ツールなら、
など、他にも色々あると思います。このやり方はQiitaにもいくつか記事があるかと思います。
複数のファイルから構成されるドキュメント
しかし、複数のファイルから構成される場合、各章を別な担当が書き一つの文章としてまとめる場合はどうしましょう？一枚一枚PDF化しPDF編集ツールで連結しますか？ページ番号やリンクの扱いなどはどうしましょう？これはちょっとツライです。
複数Markdownから単一PDFへ
実装例
私の知る限り、
- MkDocs + mkdocs-to-pdf plugin
- Vivliostyle
- Hugo + hugo-theme-vivliocli theme + Vivliostyle
があります（他にありましたらお教えください）。Vivliostyleは名前の通り電子書籍の出版を行うための組版に特化したツールです。大変美しいドキュメントが生成できます。それは別記事やドキュメントの充実した公式サイト等を参照いただくとして、今回は私が普段使いしているMkDocsでの方法について触れたいと思います。製本（プロダクションプリント）まではいかない印刷物・配布物として丁度よいドキュメントができると思います。
MkDocs
MkDocsは広く使われる静的ドキュメントサイトを構築するためのツールひとつなので知らず知らずのうちに見ていることが多いかと思います。FastAPI、Pydantic、PolarsなどPythonで書かれた製品で多く使われています。Python以外の有名どころでは、Trivy、OkHttp、Traefik proxy、AWS Copilot CLIなどでしょうか。k8s/CNCF系のツールでもよく利用されている様です。
MkDocsの使い方
PDFを生成するには、まずMkDocsでMarkdownをまとめた静的ドキュメントサイトを作ることが必要です。
今回その内容に触れると長くなるので他の記事の紹介に留めます。下記の記事などを参考に静的Webサイトを構築してください。
ちなみに弊社Webサイトのデザインに沿ったテーマにカスタマイズすると下記の様な感じになります。
mkdocs-to-pdfプラグイン
これまでMkDocsで作られたサイトをPDFに変換するにはmkdocs-with-pdfを使うことが多かったと思います。Qiitaにも記事がいくつかある様です。しかしここ数年メンテナンスされておらず、あちこち不具合があります。ここで、mkdocs-with-pdfからフォークしたmkdocs-to-pdfを使ってみます（とは言っても、こちらもまだまだ不具合は多いですが）。
使い方
最低限の使い方は既存のMkDocsプロジェクトに次のパッケージをインストールし、
pip install mkdocs-to-pdf
mkdocs.ymlに次の様にプラグインの設定を追加するだけです。mkdocs-materialも一緒に導入することを推奨します。
site_name: My Docs
theme:
name: material
plugins:
- to-pdf
これで、
mkdocs build
を実行するとサイト全体を一枚のPDFに変換したものがsite/pdf/document.pdfに生成されます（ファイル名・パスはカスタマイズできます）。
公式サイトでの生成例はこちらになります。
例えば、次の3ファイルのMarkdownを用意した場合、
# さいしょ
本文です。
# つぎ
## ほげ
### ふが
本文2です。
# そのつぎ
本文3です。
PDF化された際に次の様に章番号でが割り当てられ、全体の目次も作成されます（下記は上記にサンプルの本文を加えました）。
カスタマイズ
詳細はmkdocs-to-pdfのドキュメントサイトをご覧ください（残念ながら、いまいちドキュメント化されていない部分が多いです。コードやサンプルを追ってみてください…）。
なお、印刷レイアウトのカスタマイズはCSSの @media print 等で行います。
これで冒頭で紹介した様な表紙やヘッダーロゴなどを含めたPDF文書が作成できます。
画像・ダイアグラム・数式の挿入
一般的な画像はMarkdownの形式で挿入できます。
また、ダイアグラム（PlantUMLやMermaid）, 数式（KaTeX）もプラグインの導入でPDFに埋め込むことが可能です。
次のPython-Markdown機能拡張も用途に合わせてご利用ください。
ざっくり
今回は概要を紹介しただけで、例えば自社デザインに沿ったカスタマイズ方法などについては書いていません。いいねをいただける様でしたら別記事にて続きを投稿をしたいと思います。
まとめ
複数ファイル・複数人で編集したMarkdownファイルを一つの技術文書ファイルとしてPDFにまとめることができる様になりました。これで成果物としての仕様書、技術レポート、発表資料、外部への納品物、などに利用できることが実現できます。ぜひみなさんの組織でも活用して見てください。