md2pdf-natural

Markdownを読みやすいPDFに変換するCLIです。日本語文書で起きやすい不自然な改行、見出しだけがページ末尾に残る問題、表やコードブロックの途中分割をできるだけ抑えることを重視しています。

Features

• MarkdownからPDFを生成
• PDF生成前に一時PDFで仕上がりを確認できる --preview
• A4 / Letterなどの用紙サイズ指定
• 日本語向けの行間、禁則、余白を考慮したデフォルトテーマ
• 見出し、表、コードブロック、画像の改ページ制御
• 目次、ページ番号、ヘッダー/フッター
• frontmatterとJSON設定ファイル
• default / report / minimal テーマ
• watchモード

Install

GitHubからcloneして使う場合:

git clone https://github.com/Kakeru-Ishii/md2pdf.git
cd md2pdf
npm install
npm run md2pdf -- examples/simple.md --preview -o examples/simple.pdf

npm install は依存関係のインストール、Playwright Chromiumの準備、TypeScriptのビルドを行います。Chromiumの自動インストールをスキップしたい場合:

MD2PDF_SKIP_BROWSER_INSTALL=1 npm install
npm run setup:browser

npmパッケージとして使う場合:

npm install -g md2pdf-natural

PlaywrightのChromiumが未導入の場合は、次も実行してください。WindowsではEdge/Chromeが入っていればフォールバックしますが、安定運用ではChromiumの導入を推奨します。

npx playwright install chromium

開発中のローカル実行:

npm install
npm run build
npm run md2pdf -- examples/simple.md

Usage

基本:

md2pdf input.md
md2pdf input.md -o output.pdf
md2pdf docs/*.md --out-dir dist/pdf

テーマや用紙設定:

md2pdf input.md --theme report --paper A4 --margin 18mm
md2pdf input.md --theme minimal --no-toc --no-page-numbers

PDF生成前にプレビュー:

md2pdf input.md --preview

--preview は一時PDFを先に生成し、ターミナルで確認待ちになります。そのPDFを開いて最終的なページ分割や余白を確認し、問題なければ y を入力すると指定した出力先へ保存します。Enterまたは n ならキャンセルします。

Preview PDF: C:\Users\you\AppData\Local\Temp\md2pdf-preview-abc123\output.preview.pdf
Open this PDF, check the final layout, then return here.
Save final PDF at output.pdf? [y/N]

変更監視:

md2pdf docs/*.md --out-dir dist/pdf --watch

設定ファイルを作る場合:

md2pdf init

CLI Options

Option	Description
-o, --output <path>	単一入力時のPDF出力先
--out-dir <dir>	複数入力時のPDF出力ディレクトリ
-c, --config <path>	設定JSONのパス
--theme <nameOrPath>	組み込みテーマ名、またはテーマディレクトリ
--paper <size>	A3, A4, A5, Legal, Letter, Tabloid
--margin <value>	18mm などの余白指定
--toc / --no-toc	目次の有効・無効
--page-numbers / --no-page-numbers	ページ番号の有効・無効
--output-html	中間HTMLも出力
--preview	PDF生成前に一時PDFを作成して確認
-w, --watch	Markdown変更時に再生成

Config

md2pdf.config.json、.md2pdfrc、.md2pdfrc.json を読み込みます。

{
  "paper": "A4",
  "margin": "18mm",
  "theme": "default",
  "toc": true,
  "pageNumbers": true,
  "highlight": true,
  "font": {
    "body": "Noto Sans JP",
    "mono": "JetBrains Mono"
  },
  "layout": {
    "avoidHeadingOrphans": true,
    "avoidTableSplit": true,
    "avoidCodeBlockSplit": true,
    "compact": false
  }
}

Markdown frontmatterでも指定できます。

---
title: サンプルレポート
subtitle: PDF生成テスト
author: Ishii Kakeru
date: 2026-04-27
md2pdf:
  theme: report
  toc: true
  pageNumbers: true
---

# はじめに

優先順位は、CLIオプション、frontmatter、設定ファイル、デフォルト設定の順です。

Themes

組み込みテーマ:

• default: 日本語文書向けの標準テーマ
• report: レポート向けに見出しを強調
• minimal: 装飾を抑えた本文中心のテーマ

カスタムテーマは、theme.css と template.html を含むディレクトリとして指定できます。

md2pdf input.md --theme ./my-theme

テンプレートで使えるプレースホルダ:

• {{baseHref}}
• {{title}}
• {{subtitle}}
• {{metadata}}
• {{toc}}
• {{content}}
• {{css}}

Test Fixtures

PDF化で崩れやすい内容を確認するfixtureを用意しています。

node dist/cli/index.js "test/fixtures/content/*.md" --out-dir test/output --output-html

含まれるケース:

• 日本語長文
• 改ページストレス
• 表と長いURL
• コードブロックと引用
• リンク、画像、HTML混在
• minimalテーマ

Development

npm install
npm run build
npm test

まとめて確認:

npm run ci
npm run smoke

公開パッケージ内容の確認:

npm_config_cache=.npm-cache npm pack --dry-run

GitHub

このリポジトリはGitHub ActionsでNode 20/22、Ubuntu/Windowsのビルド、テスト、PDF変換スモークテストを実行します。

GitHubにpushすると、GitHub ActionsでNode 20/22、Ubuntu/Windowsのビルド、テスト、PDF変換スモークテストが実行されます。

License

MIT