- 数ページくらいの規模で手順書を作る時には、基本的にはMarkdownで書いていたのだけど、やっぱりMarkdownのまま相手に読んでもらうのは、慣れてないとちょっと難しいだろうなと思って、最低でもHTML、可能ならPDFの方が見栄えばいいかなと考えて、MarkdownからPDFにする方法を探していた。
- HTMLで出力していれば、その後も修正が可能だし、正直PDFの方が良いかどうかは議論の余地はありそう。最終的に印刷するっていう用途があるなら、初めからPDFにしておくくらいかな。
- PDF出力する場合に何か簡単な方法が無いか調べてたら、VS Codeの拡張機能Markdown PDFが良さそうと思ったので、試してみた。
- やってみた結論としては、表紙など体裁を重視しない手順書を書くような軽い用途であれば、VSCodeを使ってMarkdown PDF＋CSS方式で作るのが楽そう。どういう風な物が作れるかは、本エントリの最後に今回遊んでみて出来たPDFのサンプルを載せたので。
- 表紙をつけたり、図表番号、本文中で章や節を参照するなどの本格的な見栄えの良いPDFを出力したいのであれば、LatexやRe:VIEWを使ったほうが良さそう、と思った。Re:VIEWは使ったことがないので軽くググった程度ではあるけど、結構本格的なドキュメントが作れる様子。
- Markdown+CSS方式で表紙や奥付は、それぞれdivタグでスタイルを定義してしまえば作れるのはわかったけど、表紙とかにヘッダーやフッターがついてしまい、それらを付けないようにする設定は出来なさそうなので、イマイチ。表紙にページ番号とかがあっても気にしないのであれば、問題ナシ。
- あと困ったこととしては、疑似要素
::beforeを使って章、節、図表番号をそれぞれのタグに付与しようとしてみたが（例えば、「1.2 ○○」「図2-2」とか）、counter-incrementのカウントアップが上手く動作せず、それとcounter-resetも上手く動かず、諦めた。文書を通して連番の図表番号をつけるのであれば、途中でリセットせず単純にずっとカウントアップしていけば良いので問題はないと思う。
- 今回、VSCode使っているので、その拡張機能のMarkdown PDFを利用したけど、このやり方にかぎらず、例えばMarkdown+ Pandocという組み合わせでも、文書スタイルをCSSで設定出来るようだし似たようなことが出来そう。
- このやり方で色々文書を作ってみてナレッジが溜まって気が向いたら具体的なやり方とか書き起こすかも。
参考にしたサイト
- ▼ VS CodeとMarkdownで書いた技術同人誌に導入したCSS組版 - Qiita
- まず初めに参照したのがここ。このQiitaはCSSの参考になった。環境の準備などは、本文中にもリンクがあるサイト（【Visual Studio Code】Markdown PDF のスタイル(CSS)を変える方法 - Nekonote）が参考になった。
- ▼ vscode-markdown-pdf/README.ja.md at master · yzane/vscode-markdown-pdf · GitHub
- 今回はあまり細かく読んでないけど、公式の説明はここ。
出力したPDFサンプル
