Skip to content

Latest commit

 

History

History
770 lines (575 loc) · 30 KB

File metadata and controls

770 lines (575 loc) · 30 KB

Markdown PDF

この拡張機能は Markdown ファイルを pdf、html、png、jpeg ファイルに変換します。

目次

仕様変更

バージョン 2.0.0 では、既存の動作に影響する可能性がある変更が含まれます。詳細は FAQ セクションを参照してください。

機能

機能 説明 記法例
Syntax highlighting highlight.js によるコードブロックのハイライト ```js
Emoji 絵文字ショートコード :smile:
Checkbox GitHub 形式のタスクリスト - [ ] / - [x]
Heading IDs GitHub 互換の見出しアンカー生成 # 見出し#見出し
Container 注記ブロック ::: warning
Include Markdown フラグメントの埋め込み :[label](path.md)
PlantUML コードブロックから UML 図を生成 @startuml@enduml
Mermaid フェンスドコードブロックから図を生成 ```mermaid

サンプルファイル

Heading IDs

見出しには GitHub 互換のアンカー ID が自動的に付与されます。例:

見出し 生成される ID
# My Heading #my-heading
# API リファレンス #api-リファレンス
# 日本語見出し #日本語見出し

詳細は FAQ の 見出しのアンカーが変わったのはなぜ? を参照してください。

Checkbox

INPUT

- [ ] タスク A
- [x] タスク B

OUTPUT

<ul>
  <li><input type="checkbox" disabled> タスク A</li>
  <li><input type="checkbox" disabled checked> タスク B</li>
</ul>

Container

markdown-it-container を使った注記ブロックです。

INPUT

::: warning
*here be dragons*
:::

OUTPUT

<div class="warning">
<p><em>here be dragons</em></p>
</div>

PlantUML

markdown-it-plantuml を使って PlantUML の UML 図を生成します。

INPUT

@startuml
Bob -[#red]> Alice : hello
Alice -[#0000FF]->Bob : ok
@enduml

OUTPUT

PlantUML

Include

Include markdown fragment files: :[alternate-text](relative-path-to-file.md).

├── [plugins]
│  └── README.md
├── CHANGELOG.md
└── README.md

INPUT

README Content

:[Plugins](./plugins/README.md)

:[Changelog](CHANGELOG.md)

OUTPUT

Content of README.md

Content of plugins/README.md

Content of CHANGELOG.md

Mermaid

Mermaid のフェンスドコードブロックから図を生成します。

INPUT

```mermaid
stateDiagram
    [*] --> First
    state First {
        [*] --> second
        second --> [*]
    }
```

OUTPUT

mermaid

Chromium

Markdown PDF は PDF/PNG/JPEG エクスポートに Chromium ベースのブラウザを使用します。以下の順番で解決を試みます:

  1. markdown-pdf.executablePath で指定されたパス
  2. システムにインストール済みの Google Chrome / Microsoft Edge / Chromium
  3. 初回使用時に自動ダウンロードされる管理済み Chromium

詳細は FAQ の How is the Chromium browser selected? および Where is Chromium downloaded? を参照してください。

プロキシ経由で接続している場合は、settings.json に http.proxy オプションを設定し、Visual Studio Code を再起動してください。

使い方

コマンド パレット

  1. Markdown ファイルを開きます
  2. F1 キーを押すか、Ctrl+Shift+P キーを入力します
  3. export と入力し以下を選択します
    • markdown-pdf: Export (settings.json)
    • markdown-pdf: Export (pdf)
    • markdown-pdf: Export (html)
    • markdown-pdf: Export (png)
    • markdown-pdf: Export (jpeg)
    • markdown-pdf: Export (all: pdf, html, png, jpeg)

usage1

メニュー

  1. Markdown ファイルを開きます
  2. 右クリックして以下を選択します
    • markdown-pdf: Export (settings.json)
    • markdown-pdf: Export (pdf)
    • markdown-pdf: Export (html)
    • markdown-pdf: Export (png)
    • markdown-pdf: Export (jpeg)
    • markdown-pdf: Export (all: pdf, html, png, jpeg)

usage2

自動変換

  1. settings.json"markdown-pdf.convertOnSave": true オプションを追加します
  2. Visual Studio Code を再起動します
  3. Markdown ファイルを開きます
  4. 保存すると自動で変換されます

拡張機能 設定

Visual Studio Code User and Workspace Settings

  1. メニューから ファイル > 基本設定 > ユーザー設定 か ワークスペース設定 を選択します
  2. 既定の設定 から markdown-pdf の設定を探します
  3. markdown-pdf.* の設定をコピーします
  4. settings.json に貼り付け、値を変更します

demo

オプション

List

Category Option name Configuration scope
Save options markdown-pdf.type
markdown-pdf.convertOnSave
markdown-pdf.convertOnSaveExclude
markdown-pdf.outputDirectory
markdown-pdf.outputDirectoryRelativePathFile
Styles options markdown-pdf.styles
markdown-pdf.stylesRelativePathFile
markdown-pdf.includeDefaultStyles
Syntax highlight options markdown-pdf.highlight
markdown-pdf.highlightStyle
Markdown options markdown-pdf.breaks
Emoji options markdown-pdf.emoji
Configuration options markdown-pdf.executablePath
Common Options markdown-pdf.scale
PDF options markdown-pdf.displayHeaderFooter resource
markdown-pdf.headerTemplate resource
markdown-pdf.footerTemplate resource
markdown-pdf.printBackground resource
markdown-pdf.orientation resource
markdown-pdf.pageRanges resource
markdown-pdf.format resource
markdown-pdf.width resource
markdown-pdf.height resource
markdown-pdf.margin.top resource
markdown-pdf.margin.bottom resource
markdown-pdf.margin.right resource
markdown-pdf.margin.left resource
PNG JPEG options markdown-pdf.quality
markdown-pdf.clip.x
markdown-pdf.clip.y
markdown-pdf.clip.width
markdown-pdf.clip.height
markdown-pdf.omitBackground
PlantUML options markdown-pdf.plantumlOpenMarker
markdown-pdf.plantumlCloseMarker
markdown-pdf.plantumlServer
markdown-it-include options markdown-pdf.markdown-it-include.enable
mermaid options markdown-pdf.mermaidServer

Save options

markdown-pdf.type

  • 出力フォーマット: pdf, html, png, jpeg
  • 複数の出力フォーマットをサポート
  • Default: pdf
"markdown-pdf.type": [
  "pdf",
  "html",
  "png",
  "jpeg"
],

markdown-pdf.convertOnSave

  • 保存時の自動変換を有効にします
  • boolean. Default: false
  • 設定の反映には、Visual Studio Code の再起動が必要です

markdown-pdf.convertOnSaveExclude

  • convertOnSave オプションの除外ファイル名を指定します
"markdown-pdf.convertOnSaveExclude": [
  "^work",
  "work.md$",
  "work|test",
  "[0-9][0-9][0-9][0-9]-work",
  "work\\test"  // 全ての \ は \\ と記述する必要があります。(Windows)
],

markdown-pdf.outputDirectory

  • 出力ディレクトリを指定します
  • 全ての \\\ と記述する必要があります (Windows)
"markdown-pdf.outputDirectory": "C:\\work\\output",
  • 相対パス
    • Markdownファイル を開いた場合、ファイルからの相対パスとして解釈されます
    • フォルダ を開いた場合、ルートフォルダからの相対パスとして解釈されます
    • ワークスペース を開いた場合、それぞれのルートフォルダからの相対パスとして解釈されます
"markdown-pdf.outputDirectory": "output",
  • 相対パス (ホームディレクトリ)
    • パスが ~ で始まっている場合、ホームディレクトリからの相対パスとして解釈されます
"markdown-pdf.outputDirectory": "~/output",
  • 相対パスでディレクトリを設定した場合、ディレクトリが存在しなければ作成されます
  • 絶対パスでディレクトリを設定した場合、ディレクトリが存在しなければエラーになります

markdown-pdf.outputDirectoryRelativePathFile

  • markdown-pdf.outputDirectoryRelativePathFile オプションが true に設定されている場合、markdown-pdf.outputDirectory で設定した相対パスは、ファイルからの相対パスとして解釈されます
  • フォルダやワークスペースからの相対パスを避けたい場合に使うことが出来ます
  • boolean. Default: false

Styles options

markdown-pdf.styles

  • markdown-pdf で使用するスタイルシートのパスを指定します
  • ファイルが存在しない場合、スキップされます
  • 全ての \\\ と記述する必要があります (Windows)
"markdown-pdf.styles": [
  "C:\\Users\\<USERNAME>\\Documents\\markdown-pdf.css",
  "/home/<USERNAME>/settings/markdown-pdf.css",
],
  • 相対パス
    • Markdownファイル を開いた場合、ファイルからの相対パスとして解釈されます
    • フォルダ を開いた場合、ルートフォルダからの相対パスとして解釈されます
    • ワークスペース を開いた場合、それぞれのルートフォルダからの相対パスとして解釈されます
"markdown-pdf.styles": [
  "markdown-pdf.css",
],
  • 相対パス (ホームディレクトリ)
    • パスが ~ で始まっている場合、ホームディレクトリからの相対パスとして解釈されます
"markdown-pdf.styles": [
  "~/.config/Code/User/markdown-pdf.css"
],
  • オンラインCSS (https://xxx/xxx.css) は JPG と PNG では正しく適用されますが、PDF では問題が発生します #67
"markdown-pdf.styles": [
  "https://xxx/markdown-pdf.css"
],

markdown-pdf.stylesRelativePathFile

  • markdown-pdf.stylesRelativePathFile オプションが true に設定されている場合、markdown-pdf.styles で設定した相対パスは、ファイルからの相対パスとして解釈されます
  • フォルダやワークスペースからの相対パスを避けたい場合に使うことが出来ます
  • boolean. Default: false

markdown-pdf.includeDefaultStyles

  • デフォルトのスタイルシート(VSCode, markdown-pdf)を有効にします
  • boolean. Default: true

Syntax highlight options

markdown-pdf.highlight

  • Syntax highlighting を有効にします
  • boolean. Default: true

markdown-pdf.highlightStyle

"markdown-pdf.highlightStyle": "github.css",

Markdown options

markdown-pdf.breaks

  • 改行を有効にします
  • boolean. Default: false

Emoji options

markdown-pdf.emoji

Configuration options

markdown-pdf.executablePath

  • バンドルされた Chromium の代わりに実行する Google Chrome / Microsoft Edge / Chromium のパスを指定します
  • この設定がインストール済みブラウザの検出や管理済み Chromium のダウンロードとどう連携するかは、FAQ の How is the Chromium browser selected? を参照してください
  • 全ての \\\ と記述する必要があります (Windows)
  • 設定の反映には、Visual Studio Code の再起動が必要です
"markdown-pdf.executablePath": "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe"

Common Options

markdown-pdf.scale

  • ページレンダリングのスケール
  • number. Default: 1
"markdown-pdf.scale": 1

PDF options

markdown-pdf.displayHeaderFooter

  • ヘッダーとフッター表示を有効にします
  • boolean. Default: true
  • このオプションを有効にすると、ヘッダーとフッターが両方表示されます
  • 片方を表示したくない場合は、もう片方の値を削除します
  • ヘッダー非表示
    "markdown-pdf.headerTemplate": "",
  • フッター非表示
    "markdown-pdf.footerTemplate": "",

markdown-pdf.headerTemplate

  • ヘッダーを出力する為のHTMLテンプレートを指定します
  • このオプションを使用するには、markdown-pdf.displayHeaderFootertrue に設定する必要があります。
  • <span class='date'></span> : 日付。フォーマットは環境に依存します
  • <span class='title'></span> : Markdown ファイル名
  • <span class='url'></span> : Markdown フルパスファイル名
  • <span class='pageNumber'></span> : 現在のページ番号
  • <span class='totalPages'></span> : ドキュメントの総ページ数
  • %%ISO-DATETIME%% : 現在の日付と時刻。ISOベース フォーマット (YYYY-MM-DD hh:mm:ss)
  • %%ISO-DATE%% : 現在の日付。ISOベース フォーマット (YYYY-MM-DD)
  • %%ISO-TIME%% : 現在の時刻。ISOベース フォーマット (hh:mm:ss)
  • Default (version1.5.0以降): Markdown ファイル名 と 日付を %%ISO-DATE%% で表示します
    "markdown-pdf.headerTemplate": "<div style=\"font-size: 9px; margin-left: 1cm;\"> <span class='title'></span></div> <div style=\"font-size: 9px; margin-left: auto; margin-right: 1cm; \">%%ISO-DATE%%</div>",
  • Default (version1.4.4以前): Markdown ファイル名 と 日付を <span class='date'></span> で表示します
    "markdown-pdf.headerTemplate": "<div style=\"font-size: 9px; margin-left: 1cm;\"> <span class='title'></span></div> <div style=\"font-size: 9px; margin-left: auto; margin-right: 1cm; \"> <span class='date'></span></div>",

markdown-pdf.footerTemplate

  • フッターを出力する為のHTMLテンプレートを指定します
  • 詳細は、markdown-pdf.headerTemplate を参照してください
  • Default: {現在のページ番号} / {ドキュメントの総ページ数} を表示します
    "markdown-pdf.footerTemplate": "<div style=\"font-size: 9px; margin: 0 auto;\"> <span class='pageNumber'></span> / <span class='totalPages'></span></div>",

markdown-pdf.printBackground

  • 背景のグラフィックを出力
  • boolean. Default: true

markdown-pdf.orientation

  • ページの向き
  • portrait(縦向き) or landscape(横向き)
  • Default: portrait

markdown-pdf.pageRanges

  • 出力するページ範囲 例) '1-5, 8, 11-13'
  • Default: 全ページ
"markdown-pdf.pageRanges": "1,4-",

markdown-pdf.format

  • 用紙のフォーマット
  • Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5, A6
  • Default: A4
"markdown-pdf.format": "A4",

markdown-pdf.width

markdown-pdf.height

  • 用紙の幅/高さ、 単位(mm, cm, in, px)
  • このオプションが指定されている場合、markdown-pdf.format オプションより優先されます
"markdown-pdf.width": "10cm",
"markdown-pdf.height": "20cm",

markdown-pdf.margin.top

markdown-pdf.margin.bottom

markdown-pdf.margin.right

markdown-pdf.margin.left

  • 用紙の余白、単位(mm, cm, in, px)
"markdown-pdf.margin.top": "1.5cm",
"markdown-pdf.margin.bottom": "1cm",
"markdown-pdf.margin.right": "1cm",
"markdown-pdf.margin.left": "1cm",

PNG, JPEG options

markdown-pdf.quality

  • jpeg only. イメージの品質を 0-100 の範囲で指定します。 png では無効です。
"markdown-pdf.quality": 100,

markdown-pdf.clip.x

markdown-pdf.clip.y

markdown-pdf.clip.width

markdown-pdf.clip.height

  • ページの切り抜き領域を指定します
  • number
// 切り抜き領域のX軸の基点を指定します。ページの左上が原点です。
"markdown-pdf.clip.x": 0,

// 切り抜き領域のY軸の基点を指定します。ページの左上が原点です。
"markdown-pdf.clip.y": 0,

// 切り抜き領域の幅を指定します
"markdown-pdf.clip.width": 1000,

// 切り抜き領域の高さを指定します
"markdown-pdf.clip.height": 1000,

markdown-pdf.omitBackground

  • デフォルトの白い背景ではなく、透過によるスクリーンショットのキャプチャーを有効にします
  • boolean. Default: false

PlantUML options

markdown-pdf.plantumlOpenMarker

  • plantuml パーサーの開始区切り文字
  • Default: @startuml

markdown-pdf.plantumlCloseMarker

  • plantuml パーサーの終了区切り文字
  • Default: @enduml

markdown-pdf.plantumlServer

markdown-it-include options

markdown-pdf.markdown-it-include.enable

  • markdown-it-include を有効にします
  • boolean. Default: true

mermaid options

markdown-pdf.mermaidServer

FAQ

絵文字 サイズの変更方法は?

  1. 以下の設定を markdown-pdf.styles で指定したスタイルシートに追加します。
.emoji {
  height: 2em;
}

文字コードの自動判定

Visual Studio Code の files.autoGuessEncoding オプションを使うと、文字コードが自動判定されるので便利です。

"files.autoGuessEncoding": true,

出力ディレクトリ

常に Markdown ファイルからの相対パスのディレクトリに出力したい場合。

例えば、Markdown ファイルと同じディレクトリの "output"ディレクトリに出力する場合、次のように設定してください。

"markdown-pdf.outputDirectory" : "output",
"markdown-pdf.outputDirectoryRelativePathFile": true,

改ページ

改ページを挿入するには、以下のいずれかを使用してください。

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

見出しのアンカーが変わったのはなぜ?

バージョン 2.0.0 から、Markdown PDF は GitHub 互換の VS Code slug 生成に準拠したカスタム実装の markdown-it-named-headers で見出し ID を生成します。従来の実装と比較して、新しい slug ジェネレータは CJK 文字とアンダースコアを保持する一方でサポートされない記号を除去するため、既存の内部アンカー (例: #some-heading) の解決結果が変わる可能性があります。

目次や相互参照など特定のアンカー文字列に依存している Markdown を使っている場合は、エクスポート後にアンカーを確認し、リンクを必要に応じて更新してください。

シンタックスハイライトのスタイルが効かなくなったのはなぜ?

バージョン 2.0.0 から、Markdown PDF は highlight.js v11 を使用するようになりました (以前は v9)。v9 のスタイル名の一部は名称変更または削除されています。Markdown PDF は古いスタイル名を可能な範囲で現在の名前にマッピングし、見つからないときは警告メッセージを表示します。マッピング不能な場合は tomorrow.css にフォールバックします。

利用可能なスタイルを確認し、markdown-pdf.highlightStyle の設定を現行のスタイル名に更新してください。

フロントマターが解析されなくなったのはなぜ?

バージョン 2.0.0 から、Markdown PDF は gray-matter ではなくカスタム実装で YAML フロントマターを解析します。新しいパーサーはより厳格で、以前のパーサーが受け入れていた以下のケースを拒否します:

  • トップレベルが YAML シーケンス (配列) のフロントマター
  • プレーンオブジェクトに解析されないフロントマター
  • 不正な YAML 構造

有効なフロントマターはトップレベルが YAML マッピング (オブジェクト) である必要があります。例:

---
title: My Document
"markdown-pdf":
  displayHeaderFooter: true
---

BOM 付きファイルは引き続きサポートされます。

Chromium ブラウザはどのように選択されますか?

Markdown PDF は以下の順番で Chromium ベースのブラウザを解決します:

  1. markdown-pdf.executablePath で指定されたパス (ファイルが存在する場合)
  2. システムにインストール済みのブラウザ。Google Chrome (stable) は @puppeteer/browsers 経由で OS 標準のインストール場所から検出されます。Microsoft Edge と Chromium は下記の固定パスを順にスキャンします。
  3. Markdown PDF が初回使用時に自動ダウンロードする管理済み Chromium

最初にマッチしたものが使用されます。OS ごとの検出順序は以下のとおりです。

Windows

  1. Google Chrome (stable インストール、@puppeteer/browsers で検出)
  2. %LOCALAPPDATA%\Microsoft\Edge\Application\msedge.exe
  3. %LOCALAPPDATA%\Chromium\Application\chrome.exe
  4. %PROGRAMFILES%\Microsoft\Edge\Application\msedge.exe
  5. %PROGRAMFILES%\Chromium\Application\chrome.exe
  6. %PROGRAMFILES(X86)%\Microsoft\Edge\Application\msedge.exe
  7. %PROGRAMFILES(X86)%\Chromium\Application\chrome.exe

macOS

  1. Google Chrome (stable インストール、@puppeteer/browsers で検出)
  2. /Applications/Chromium.app/Contents/MacOS/Chromium
  3. /Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge

Linux

  1. Google Chrome (stable インストール、@puppeteer/browsers で検出)
  2. /usr/bin/chromium-browser
  3. /usr/bin/chromium
  4. /usr/bin/microsoft-edge
  5. /usr/bin/microsoft-edge-stable

Chromium はどこにダウンロードされますか?

インストール済みブラウザが見つからない場合、Markdown PDF は初回使用時に管理済み Chromium をダウンロードします。ダウンロード先は拡張機能の VS Code global storage ディレクトリです:

OS ダウンロードパス
Windows %APPDATA%\Code\User\globalStorage\yzane.markdown-pdf\
macOS ~/Library/Application Support/Code/User/globalStorage/yzane.markdown-pdf/
Linux ~/.config/Code/User/globalStorage/yzane.markdown-pdf/

VS Code Insiders や VSCodium を使用している場合は、ベースパスが Code - InsidersVSCodium などに変わります。

ダウンロード中はステータスバーに Installing Chromium が表示されます。

既知の問題

markdown-pdf.styles option

  • オンラインCSS (https://xxx/xxx.css) は JPG と PNG では正しく適用されますが、PDF では問題が発生します #67

2.0.1 (2026/04/14)

  • Fix: 自己閉じタグ <div class="page" /> で改ページが正しく動作するよう修正 #428

2.0.0 (2026/04/13)

  • Breaking: 見出し ID の slug 生成、フロントマター解析、Chromium 解決ロジックが変更されました。詳細は FAQ を参照してください。
  • Change: ソースコードを TypeScript に移行し、esbuild でバンドルするよう変更
  • Change: puppeteer-core をバンドルし、内製の chromium-resolver で Chromium を管理 (インストール済み Chrome/Edge を優先し、見つからなければ自動ダウンロード)
  • Change: markdown-it-include / markdown-it-named-headers / markdown-it-checkbox を内製実装に置換
  • Change: cheerio / mustache / gray-matter 依存を削除
  • Add: ユニットテストと統合テスト (vscode-test-cli)

詳細は Change Log を参照してください。

License

MIT

Special thanks