受け取るMarkdownと、その整え方
最終確認
変換で得られるのはMarkdownファイルであって、完成した文書ではありません。ここでは、何が出てくるのか、どの部分が信頼できるのか、そしてファイルをリポジトリやWiki、ノート保管庫に入れる前に済ませる価値のある少数の編集を、手短にまとめます。
読了 6 分
出力の正体
本ツールが出力するのはGitHub Flavored Markdownです。GitHub、GitLab、Obsidian、Notionのインポート、そして大半の静的サイトジェネレータが用いる方言で、CommonMarkにいくつかの拡張を加えたものです。ここで効いてくる拡張はパイプ表です。
この選択は意図的です。素のCommonMarkには表の記法が存在しないため、それを目標にする変換器は表を捨てるか生のHTMLを吐くかしかありません。GFMの表は文字のままでも読め、Markdownが通じるほぼすべての場所で理解されます。
旅を生き延びるもの
| 見出し | 残る — 相対的なフォントサイズから #、##、### として |
|---|---|
| 段落 | 残る — 縦の間隔から |
| 太字と斜体 | 残る — フォント自身のウェイトと傾きから |
| 箇条書き | 残る — 行頭の記号から |
| 番号付きリスト | 残る — 行頭の数字から |
| 表 | 単純な矩形のものが、GFMのパイプ表として |
| インラインcode | 残る — 等幅の部分から |
| リンク | PDFに実際のリンク注釈がある場合は残る |
| 画像 | 残らない — 出力は文字と構造のみ |
| 脚注 | ページ末尾の本文として。リンクはされない |
| 数式 | 構成文字のまま。LaTeXにはならない |
| 色とフォント | 残らない — Markdownに表現手段がない |
毎回やる価値のある5つの編集
変換後のファイルの大半は、同じ少数の手順を必要とします。数分で済み、検索できるだけのファイルと、読めるファイルとを分けます。
- 見出しの階層を直す。サイズのしきい値が生む階層は、局所的には正しく全体としては不揃いです。H1が3つあってH2が1つもない文書もあり得ます。見出しだけを拾って、入れ子が文書の実際の構成に合うよう振り直してください。
- 分断された段落をつなぐ。行間の広い文書は、段落を行末で切ります。短い行の積み重ねのように読めるので、つなげて余分な空行を消してください。
- ハイフネーションを直す。右揃えでハイフン処理された文書は、単語を行またぎで割ります。ハイフンの直後に改行が来る箇所をファイル内で検索してください。
- 表をすべて確認する。Markdownの列数を原本と突き合わせ、最終行を見てください。末尾の行が最も多い犠牲者です。形を失った表は、直すより打ち直すほうが速いのが普通です。
- ページの調度品を消す。繰り返されるヘッダーとフッターは検出して取り除かれますが、ページごとに章題が変わるなど内容が変動する文書では断片が残ることがあります。
表についての注意
GFMのパイプ表は、どの行も同じセル数である必要があり、ヘッダー下の区切り行が表全体の列数を決めます。変換器がある行を数え損ねると、表は無効になり、パイプ記号を含む文字列としてそのまま表示されます。
これは目に見える失敗であり、その点は救いです。後から気づくのではなく、その場で分かります。次の表は壊れています。
| 地域 | Q1 | Q2 |
| --- | --- | --- |
| 北 | 120 | 140 |
| 南 | 95 |
| 東 | 88 | 102 |直し方
足りないセルを補ってください。元のセルが空だったなら空のままで構いません。どの行も、区切り行と同じ数のパイプを持つ必要があります。
| 地域 | Q1 | Q2 |
| --- | --- | --- |
| 北 | 120 | 140 |
| 南 | 95 | |
| 東 | 88 | 102 |エスケープと、出力に時折現れる円記号
Markdownは、普通の文章にも現れる文字に意味を与えます。アスタリスクは強調、アンダースコアも強調、行頭のハッシュは見出し、行頭の数字とピリオドはリスト項目です。
これらの文字が文書の中で文字そのものとして現れる場合 — 脚注記号、アンダースコアを含む変数名、実際に「1985.」で始まる行 — バックスラッシュでエスケープしなければ、文書の見え方が黙って変わってしまいます。出力中のバックスラッシュは、たいてい誤りではなく変換器の慎重さです。
邪魔なバックスラッシュは削除しても構いません。ただし削除後にその行の表示を確認してください。
ファイルの行き先
Markdownはプレーンテキストです。そもそも変換する理由がそこにあります。grepで検索でき、diffで差分が取れ、テキストファイルを開けるものなら50年後でも読めます。
リポジトリならツリーに置いてコードレビューに委ねてください。ノート保管庫なら、まず見出しの階層を確認してください。多くの保管庫はそこから構成を組み立てます。静的サイトなら、ジェネレータが必要とするfront matterを足してください。PDFに書かれていない以上、どの変換器にもそれは作れません。言語モデルに与えるなら、検索用にPDFを準備するガイドをご覧ください。優先順位の異なる別の作業です。