Created on September 10, 2023
Updated on September 11, 2023
Copyright (c) 2023 led-mirage
この資料では Markdown ファイルを PDF ファイルに変換する方法について説明します。
Visual Studio Code の拡張機能 Markdown PDF(z) で Markdown ファイルを PDF ファイルに変換できます。
以下の動作環境で動作確認をしました。
- Windows 11 Pro 22H2
- Raspberry Pi 4B 4GB
- Visual Studio Code 1.82.0
- Markdown PDF(z) v2.0.3
Visual Studio Code の Marketplace で markdown pdf と検索すると、先頭に Markdown PDF が見つかり、その他同じアイコンの拡張機能があと２つほど表示されると思います（2023年9月現在）。
- Markdown PDF
- Markdown PDF(z)
- Markdown PDF(m)
この中でインストールすべきは、２番めの Markdown PDF(z) です。本家は１番目の Markdown PDF で、あとの２つは本家から分岐した Fork なのですが、本家と３番目のプログラムは後述する康煕（こうき）部首の問題の問題を含んでいます。また、本家は Windows なら動いたのですが、ラズパイで PDF を生成しようとするとエラーが発生しました。これについても Markdown PDF(z) では問題なく生成できました。
以上のことから、インストールすべきなのは Markdown PDF(z) と言う結論に至りました。ただ、本家のほうが安心できる、康煕（こうき）部首の問題なんて気にならない、という方は本家を使ってもいいと思います。
エディタ上の Markdown ファイルを右クリックして Markdown PDF: Export(pdf) を選択すると PDF ファイルが生成されます。簡単ですね。
Markdown PDF(z) は PDF 化のほか、HTML や画像データへの変換もサポートしています。
ヘッダー、フッターなどのスタイルの設定は拡張機能の設定画面から行えます。拡張機能の設定は、各拡張機能の右下の歯車アイコンをクリックし、「拡張機能の設定」を選択することで表示できます。
より詳細なスタイルは CSS ファイルを追加することで調整可能です。例えばGitHub風のスタイルにしたい場合、次の手順を実行します。
- ここ※1から CSS をダウンロードし、github-markdown.css ファイルに保存する（ファイル名は任意）
- ファイル中の ".markdown-" という文字列をすべて削除する（空文字で置換）
- "white-space: pre;" を "white-space: pre-wrap;" に変更する（変更しないとプログラムコードが途中で途切れる）
- 拡張機能の設定画面で、
Include Default Stylesのチェックを外す - 拡張機能の設定画面で、
Stylesに作成した CSS ファイルのパスを追加するする
※1 https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.2.0/github-markdown.css
拡張機能の設定はグローバルかワークスペース内に保存でき、ワークスペースの場合は .vscode/settings.json に次のような設定が保存されます。
{
"markdown-pdf.includeDefaultStyles": false,
"markdown-pdf.styles": [
"./github-markdown.css"
],
}また、本リポジトリ内にも編集済みの github-markdown.css を用意しましたので、よかったらご利用ください。
改ページしたい個所で以下のタグを挿入します。
<div class="page"/>本家および３番めの拡張機能だと、特定の文字が康煕（こうき）部首に変換されてしまいます。康煕部首とは部首を表す特殊な漢字コードで、普通の漢字が誤って康煕部首に変換されてしまうと、アプリケーションによっては文字化けを引き起こしてしまいます。
Word や Excel などの表示では普通の漢字と見分けがつかないこともあるため、一見無害の様にも思えますが、これが２次利用された場合（たとえばデータベースのマスタデータとして登録してしまうなど）、気づかないうちに被害が拡大してしまします。
例えば「自分用」という単語を本家で PDF に変換すると "自" と "分" が康煕部首になってしまいます。PDF になった「自分用」をエディタなどに貼り付けて、その下に手入力で「自分用」と書いてみれば違いがわかると思います。見た目ではわからない場合、手書きの文字をコピーして文書内を検索してみてください。PDF から貼り付けた文字とは一致しないはずです。
※ 検証に使用した本家 Markdown PDF は v1.5.0 です。
このように康煕部首の問題は根深いものがあるため、個人的には可能な限り排除したほうがいいと考えています。ネットで「康煕部首」で検索すると色々な情報が出てくるので、興味がある方は調べてみてください。
Node.js の md-to-pdf パッケージでも Markdown ファイルを PDF ファイルに変換できます。
実行にはあらかじめ Node.js をインストールしておく必要があります。Node.js のインストールは、Windows であれば公式サイトからダウンロードしてインストールすればＯＫです。ラズパイなど、Linux系のOSであれば、コマンドでインストールできると思います。
また、Node.js を直接インストールするのではなく、nvm などのバージョン管理ツールを先にインストールし、nvm 経由で Node.js をインストールしてもいいでしょう。バージョン管理ツールを使うと、Node.js 複数のバージョンを簡単に切り替えることができて便利です。
以下の動作環境で動作確認をしました。
- Windows 11 Pro 22H2
- node.js v18.17.1
- md-to-pdf 5.2.4
※ラズパイでも試しましたが、エラーが出てうまく動きませんでした。
次のコマンドで md-to-pdf パッケージをグローバルにインストールします。
npm i -g md-to-pdfターミナル（コマンドライン）から次のコマンドを入力します。
md-to-pdf "ファイル名"ドキュメントの先頭に次のようなブロックを挿入することでスタイルを制御できます。詳しくは資料末の公式サイトを参考にしてください。
---
pdf_options:
format: a4
margin: 20mm 20mm
printBackground: true
headerTemplate: |-
<style>
section {
margin: 5mm 15mm;
font-family: system-ui;
font-size: 10px;
color: silver;
}
</style>
<section>
<span class="title"></span>
<span class="date"></span>
</section>
footerTemplate: |-
<section style="margin: 0 auto;">
<div>
Page <span class="pageNumber"></span>
of <span class="totalPages"></span>
</div>
</section>
stylesheet: https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.2.0/github-markdown.min.css
body_class: markdown-body
css: |-
.page-break { page-break-after: always; }
.markdown-body { font-size: 16px; }
.markdown-body pre > code { white-space: pre-wrap; }
.markdown-body pre { background: #eee; }
.markdown-body pre { padding: 5px; }
---改ページしたい個所で以下のタグを挿入します。
<div class="page-break"></div>康煕部首の問題があったため Markdown PDF の使用は避けてきましたが、Markdown PDF(z) ではこの問題が解消されているので、これを使うのが一番手軽でいいかもしれません。
md-to-pdf にも大変お世話になりましたが、ひとつ難点を上げるとすると文章の先頭にヘッダー、フッターやスタイルを記述する形式のため、文章が汚れる点があげられるでしょうか。
どちらも便利なツールなので好みに合わせて使い分ければいいと思います。
本資料では以下のリポジトリの github-markdown.css を改変して使用しています。