メインコンテンツへスキップ

🧾 VS Code「Markdown PDF」で改ページを制御する方法（BookStack向け）

🧭 はじめに

この記事では、VS Code拡張機能「Markdown PDF」 を使ってMarkdown文書をPDF化する際に、意図した位置で改ページを入れる方法を整理する。 Markdown自体には改ページの概念がないため、Markdown → HTML → PDF（Chromium印刷） という変換経路を前提に、実務で安定して使える方法に絞って解説する。

🧩 Markdown PDFの内部構造を理解する

Markdown PDF拡張は、内部的に次の処理を行っている。

  1. Markdown → HTML に変換
  2. HTMLを Chromium（Chrome系）で印刷
  3. 印刷結果をPDFとして出力

このため、改ページはMarkdownではなくHTML/CSS側で制御するのが基本方針になる。

🧱 改ページの基本戦略（結論）

✔ 採用すべき方法

  • Markdown内に HTMLタグ を直接書く
  • CSSで page-break-before / break-before を指定する

✖ 採用すべきでない方法

  • 改行や空行を大量に入れる
  • \newpage などのLaTeX命令を使う（この環境では無効）

HTML＋CSSによる改ページ指定は、Markdown PDFだけでなく将来Pandoc等に移行しても再利用しやすい。

📄 明示的に改ページを入れる方法

🧩 Markdown側の書き方

改ページしたい位置に、以下のHTMLをそのまま書く。

ここまで本文

<div class="page-break"></div>

次のページから本文

コードブロックではなく、生HTMLとして書く必要がある。 インラインコードや fenced code block に入れると機能しない。

🎨 CSS側の設定（必須）

🧱 改ページ用CSS

以下のCSSを用意し、Markdown PDFの設定で読み込ませる。

.page-break {
  page-break-before: always;
  break-before: page;
}

`page-break-before` は旧仕様、`break-before` は新仕様。 両方書くことで互換性が最大化される。

⚙ VS Code 側の設定方法

settings.json に CSS ファイルを指定する。

"markdown-pdf.styles": [
  "file:///C:/path/to/markdown-pdf.css"
]

パスは file:// 付きの絶対パス を指定すること。 相対パスだと環境によって失敗しやすい。

📚 見出し単位で自動改ページしたい場合

🧩 章（h1）ごとに改ページ

h1 {
  page-break-before: always;
  break-before: page;
}

h1:first-of-type {
  page-break-before: auto;
  break-before: auto;
}

BookStack記事や技術資料では「章＝ページ」構成が読みやすく、この設定は相性が良い。

🚫 よくあるハマりどころ

❌ 改ページされない原因

  • display: none の要素に改ページ指定している
  • <br> を並べてページ送りしようとしている
  • page-break-after だけを使っている

改ページは視覚的な空白ではなく「印刷レイアウト制御」。 HTML的に「存在しない要素」ではページは切れない。

🧠 実務での推奨パターン（まとめ）

  • Markdown内に <div class="page-break"></div> を明示的に書く
  • CSSで page-break-before: always を指定
  • Markdown PDF の設定でCSSを読み込ませる
  • LaTeX的発想は捨てる（この環境では不要）

この方法は BookStack用記事・技術仕様書・配布PDF いずれでも安定して使える。

🧩 補足：なぜMarkdownに改ページがないのか

Markdownは「構造と意味」を書く言語であり、「紙面レイアウト」は想定していない。 そのため、改ページは常に出力先（HTML/CSSやPDFエンジン）の責務になる。

この分離思想を理解しておくと、Markdown運用全体が一段クリアになる。

上に戻る