複数ファイルのMarkdownブック作成とPDF書き出しガイド

単一のREADMEは入門口として優れていますが、本格的なマニュアルには向きません。ドキュメントがインストール、設定、運用、トラブルシューティングと増えていくと、長大なREADMEは読むのも印刷するのも困難になります。

md2pdfには、そうした構成に特化したドキュメントブックワークフローが用意されています。公開リポジトリを指定し、必要なMarkdownファイルを選んで並べ替え、表紙と目次を付けて、製本印刷または章ごとの個別PDF ZIPダウンロードを実行できます。すべてブラウザ上で処理され、サーバーに文書は送信されません。

本ガイドではブック機能の使い方とリポジトリ構成のコツを説明します。単一ファイルのみ必要な場合は、まずGitHubのREADMEをPDFに変換する方法をご覧ください。

単一READMEではなくブックを選ぶべき場面

ドキュメントに複数の自然な章があり、章間を移動する必要がある場合にブック機能が適しています：

• 初期設定、概念説明、APIリファレンスが分かれている製品ドキュメント。
• 週ごとの講義ノートやモジュールを束ねた教材パック。
• サービスやインシデント種別ごとにファイルが独立している運用手順書（ランブック）。
• 変更履歴、アップグレード手順、移行手引きを統合したリリース文書。

内容がごく短い場合や頻繁に変更される場合は、単一文書のほうが適しています。

本ワークフローは公開リポジトリを前提としています。ブラウザから認証が必要なプライベートリポジトリはサポート外です。

スキャナーが行う処理と制限事項

リポジトリURLを入力すると、ブックエクスプローラーがGitHub API経由でGitツリーを読み取り、階層チェックボックス付きの検索可能なファイルツリーを構築します。

ブラウザの応答性を保つため、スキャナーには明確な安全上限が設けられています：

• 1冊あたり最大30ファイルまで。
• 1ファイルあたり750 KBまで。
• 合計6 MBまでのMarkdown。
• コンテンツ取得の20秒タイムアウト。
• メインスキャンで消費するGitHub APIの上限は60リクエスト。

docs/
├── 00-introduction.md
├── 01-installation.md
├── 02-configuration.md
├── 03-operations.md
└── 04-troubleshooting.md

おすすめのディレクトリ構造例：

数字プレフィックスは必須ではありませんが、リポジトリ内での意図した読書順が明確になり、並べ替えの手間が省けます。

章の選択と並べ替え

ツリーからファイルを選択し、章リストを確認します。新しく選択したファイルは末尾に追加されます。上へ移動・下へ移動・削除ボタンを使って順序を整えてください。

並べ替えのヒント：

1. 最小限の構成を選ぶ。 30章の上限がありますが、10〜15章程度のほうが校正も印刷も容易です。
2. 導入を先頭に置く。 概要や前提条件はインストールの前に配置します。
3. リファレンスは末尾に。 付録やAPI一覧は最後に置くのが自然です。
4. READMEの重複を避ける。 READMEも含める場合は、それが概要なのか目次なのか役割を決めます。
5. 自動生成ファイルを除外する。 雑多なログは除外してください。

エディタ上での順序が、印刷されたPDFおよびZIP内のファイル順序となります。

ソースファイルの事前準備

レンダラーは選択された各ファイルをひとつの章として扱い、ファイル名やパスから章見出しを挿入したうえで本文を展開します。

章ファイルの記述例：

# Installation

This chapter assumes a supported Node.js version and a local clone.

各ファイルがH1から始まっていれば、製本時に章の区切りが明確になります。

その他の確認事項：

• 相対リンク。 章間のリンクは選択されたファイル群を指している必要があります。
• 画像パス。 相対画像はGitHubリポジトリを基準に解決されます。
• 横長テーブル。 Markdownの表をPDFに変換するを参考に幅を調整してください。
• 見出しの重複。 目次での判別が難しくなるため、章固有の語句を付加してください。

表紙と目次の作成

タイトル、サブタイトル、表紙説明文を設定できます。何についての文書で、誰に向けたもので、どのバージョンかを明記しましょう。

目次は選択された章と見出しから自動合成されます。表紙や目次設定を変更すると再構築が必要とマークされ、内容の不一致を防ぎます。

ブックの印刷とZIPエクスポート

出力には2種類の方法があります：

• 製本印刷。 表紙・目次・全章をまとめてブラウザ印刷ダイアログへ送ります。
• ZIPエクスポート。 選択した章ごとに1つのPDFを生成し、ZIP形式で一括ダウンロードします。

ZIPファイル名は md2pdf-{owner}-{repo}-{sha8}.zip となり、ファイル名はUnicode正規化されます。

制限・エラー・トラブル復旧

GitHubのAPIレート制限に達した場合は、制限解除を待つか特定フォルダのURLを直接指定してください。画像が取得できない場合もプレースホルダーに置き換わり処理は継続します。

デザインの調整については印刷テーマの比較をご覧ください。