表は、技術ドキュメントで読者が最初に探す要素のひとつです。同時に、MarkdownをPDFにしたときに最初に崩れる要素でもあります。広いブラウザウィンドウでは問題なく見える列も、A4では窮屈になります。長いセルテキストは表をマージンの外へ押し出し、行はページをまたいで分割されて、ヘッダーの意味が失われます。
md2pdfはGitHub Flavored Markdownの表をレンダリングし、その結果を印刷用スタイルシート、または書籍書き出しの場合はA4 PDFレンダラーへ渡します。ツールは妥当な表を読みやすく保つことはできますが、スペースを新たに生み出すことはできません。作業の大半はMarkdownソース側で行われます。適切な列を選び、セルを短く保ち、そもそも表に入れるべき情報かどうかを見極めることです。
本ガイドでは、まずこのソースレベルでの作業を扱い、そのうえで残りの問題を見つけるための印刷時の確認項目を説明します。変換の一連の流れについては、GitHubのREADMEをPDFに変換する方法をご覧ください。
印刷時に表が崩れる理由
ブラウザ上の表は柔軟です。コンテナからはみ出すことも、テキストを縮小することも、読者に横スクロールさせることもできます。印刷されたページには固定の幅があり、スクロールバーもありません。コンテンツがページより広い場合、何かを犠牲にする必要があります。レンダラーは表を切り取るか、読めるサイズを下回るまで縮小するか、プレビューとは似ても似つかないレイアウトに押し込むかのいずれかを選びます。
次の3つの習慣が事態を悪化させます。
- 列が多すぎる。 データが技術的に完全であっても、幅の狭い8列は、幅の広い4列より読みにくくなります。
- セルの中の段落。 3つの文を含むセルは、ざっと見渡せる表をテキストの壁に変えてしまいます。
- 長さの制限がないコードやURL。 長いトークンが1つあるだけで、列全体の最小幅が決まってしまいます。
解決策はフォントを小さくすることではありません。役割を減らした表にすることです。
収まる表から始める
役に立つ表には、目的が1つだけあり、列の数も少なくて済みます。次の例は、すべてのCSSプロパティを説明しようとせずに、印刷テーマを比較しています。
| Setting | Clean | Business | Academic |
| --- | :--- | :--- | ---: |
| Body type | Sans | Serif | Justified serif |
| Best for | Specs | Reports | Course readers |
| Tone | Neutral | Formal | Editorial |この表はA4とLetterに余裕をもって収まります。セルが短いため、翻訳しても崩れません。配置マーカーは省略可能ですが、ソースをざっと読みやすくします。左揃えは:---、中央揃えは:---:、数値の右揃えは---:です。
配置は装飾ではなく意味のために使います。数値は右揃え、短いラベルは左揃えが読みやすくなります。中央揃えが必要になることはほとんどなく、列をかえって読みにくくすることがあります。
データではなく問いで列を選ぶ
列を追加する前に、その表がどんな問いに答えるのかを自問してください。移行作業の表なら、「何が変わり、それに対して何をすればよいか」に答えるはずです。そこから、項目、変更内容、対応の3列が生まれます。12個のフィールドを持つデータベースのエクスポートは、PDF向けの表ではなくデータのダンプです。
よいテストは、ヘッダー行を声に出して読むことです。ヘッダーが一貫した文や比較になっていなければ、その表はおそらく情報を詰め込みすぎています。分割するか、詳細を本文へ移してください。
幅の広い参照データには、代わりに2列の定義リストを検討してください。
| Field | Meaning |
| --- | --- |
| `owner` | GitHub user or organization |
| `repo` | Repository name without the host |
| `ref` | Branch, tag, or commit SHA |この形式は、ロケールごとに1列、エッジケースごとに1列といったグリッドよりも、印刷しやすく翻訳もしやすいです。
セルは短く、走査しやすく保つ
表は説明ではなく比較のためのものです。セルに短い文が3つ以上必要な場合は、説明を表の下へ移し、セルには要約だけを残してください。
実践的なルールを挙げます。
- 文の断片を使う。 「公開リポジトリが必要」で十分であり、段落全文は不要です。
- 単位はヘッダーに置く。 各行で「MB」を繰り返すのではなく、
Size (MB)と一度だけ書きます。 - セル内の改行は避ける。 GFMは
<br>をサポートしますが、強制改行を含むセルはページ分割がうまくいかないことがほとんどです。 - リンクは短く保つ。 URL全体ではなく短いラベルにリンクしてください。長いURLは分割できないトークンになります。
- 色に頼らない。 PDFは白黒で印刷されることがあり、テーマによって配色も変わります。
セルに長いコマンドやパスを入れなければならない場合は、表の下のフェンス付きコードブロックに置き、名前で参照してください。グリッドを狭く保てます。
書き出し前に幅の広いデータを扱う
なかには本当に幅の広い表もあります。列を削除できない場合は、ページと格闘するのではなく、ドキュメントの形を変えてください。
読者で分割する。 運用担当者向けの表と開発者向けの表では、必要な列が異なります。
時間で分割する。 20件のリリースを含む変更履歴の表は、メジャーバージョンごとに1つの表にできます。
データを転置する。 属性が多く項目が少ない場合は、属性を行に、項目を列にします。表は横長ではなく縦長になり、ページ分割がよくなります。
リストに移す。 ほとんどのセルが空、または繰り返しなら、その表はリストを隠しています。小見出し付きの本文のほうが明確なことがよくあります。
再構成したら、幅を押し広げるよくある2つの原因をもう一度ソースで確認してください。長い分割不能なURLと、スペースを含まないコードスパンです。どちらも列をページより広くしてしまいます。
ページ分割とヘッダーの繰り返しを確認する
1ページに収まる表でも、2ページにまたがると失敗することがあります。ヘッダー行は繰り返され、行はセルの途中で分割されず、表がページの最下部から始まって1行しか見えない、といった状態にならないようにする必要があります。
ブラウザの印刷エンジンと書籍PDFレンダラーではページ分割の扱いが異なるため、推測せず実際の出力を確認してください。単一文書の印刷では、<thead>が繰り返されているかを確認し、表の直前に改ページが入らないようにします。書籍書き出しでは、A4レンダラーが行を順番にレイアウトしますが、非常に高い行は依然として不自然なページを生むことがあります。
表がページをまたぐ場合は、列名を示す短いキャプションを表の上に追加してください。ヘッダーが前のページにあるとき、キャプションが読者の手がかりになります。キャプションは表の中ではなく、通常の本文として書きます。
書き出し前のチェックリスト
印刷や書き出しの前に、次のリストを確認してください。
- 表の目的は1つだけで、列は5～6個以内に収まっている。
- すべてのヘッダーが短く、必要に応じて単位を含んでいる。
- セルには段落ではなく断片が入っている。
- URL全体や、ページより長い分割不能なトークンを含むセルがない。
- 配置は数値と短いラベルに適用され、全体には適用されていない。
- 複数ページにまたがる場合はキャプションがある。
- ブラウザのプレビューだけでなく、実際のPDFを確認した。
テーマ固有の挙動については、Clean vs Business vs Academic vs Darkをご覧ください。マージンの狭いセリフテーマでは、既定のCleanテーマより1列少なくする必要があるかもしれません。
表は美しい必要はありません。ブラウザを離れたあとも読めることが必要です。キャプションが明確で、より狭く短い表は、読者が理解するためにズームしなければならない完全なグリッドに、ほとんど常に勝ります。
自分だけのREADME PDFを作る
無料、ログイン不要、そしてすべてクライアントサイド。