Markdown と PDF の往復：形式変換が残すもの
Markdown と PDF の往復は、画素より見出し、リスト、簡単な表をよく保つ。ただし正確なフォント、改ページ、レイアウトは無損失の往復としては残らない。
Markdown と PDF は異なる契約に最適化されている。Markdown はバージョン管理と相性のよい構造だ。PDF は固定のページ記述である。片方向への変換は有用だが、無損失のアーカイブ循環ではない。
Markdown から PDF：構造がページになる
Markdown から PDF（POST /api/v1/convert/markdown/pdf）は .md ファイル、または Markdown を含む ZIP を受け付ける。Markdown でも ZIP でもないアップロードは拒否される。素の .md 入力には UTF-8 が必要だ。パイプラインは表、取り消し線、タスクリストを有効にして Markdown を HTML に描画し、その HTML を印刷向けの CSS（多文字種のフォントスタック、アラビア語を検出したときの RTL を含む）で包み、WeasyPrint で PDF に印刷する。
前向きの変換で残りやすいもの：
- 見出し、段落、リスト、簡単な Markdown の表
- HTML の経路がレイアウトできる多文字種のテキスト（印刷 CSS が覆う CJK、ラテン文字、その他の文字体系）
- docs-as-code のワークフロー向けの、印刷・共有できる PDF
残らないもの：
- エディタのテーマフォントがすべてのビューアで一致するという保証
.mdファイルの画面上の改行そのまま- PDF に対応物の無い対話的な Markdown 機能（ライブのチェックボックス、折りたたみ、wiki リンク）
ZIP 入力は、HTML の経路が文書の隣で解決できる資産と Markdown をまとめるためのものだ。パッケージの便宜として扱い、すべての相対画像や CSS 参照がどのビューアでも同じに見える保証とは考えないこと。
PDF から Markdown：テキスト層が入り、Markdown が出る
PDF から Markdown（POST /api/v1/convert/pdf/markdown）は pdf-inspector を通してテキスト内容を Markdown に抽出する。応答は text/markdown で、.md ファイルとしてダウンロードされる。きれいなテキスト層を持つボーンデジタル PDF が最もよく変換できる。テキスト層の無いスキャンページは、先に OCR するまで空か役に立たない Markdown しか出さない。本サイトの OCR も Markdown を返し、検索可能な PDF 層ではない。
期待できること：
- フォントサイズのヒューリスティックが正しく働いたときの見出しと段落（
#のレベルは手で振り直すこともある） - 認識がうまくいけば Markdown の表になるが、多段のレイアウトは別の読み順に線形化されることがある
- ページごとに繰り返されるヘッダとフッタ（後処理で削る）
- 画像や絵としての数式が自動でローカル資産や LaTeX になることはない
見出しのヒューリスティック無しの素の散文が必要なら、PDF からテキスト の方が平坦な抽出だ。HTTP 204 を返す表形式のエクスポートは、列状のブロックが検出されなかったことを意味する。空の表エクスポート（204） を参照してほしい。
往復が実際に証明すること
| 妥当に残る | 通常は残らない |
|---|---|
| 語、見出しの階層、リスト構造 | 画素単位で完全なページの幾何 |
| テキストとしての簡単な表 | 正確なフォントとカーニング |
| Git やエージェント向けの使える下書き | 印刷と同一の改ページ |
二度往復させればずれていく。Markdown→PDF は WeasyPrint を通してリフローし、PDF→Markdown は抽出のヒューリスティックから構造を組み直す。どちらの工程も、相手形式のレイアウト模型の無損失な中間物を保存しない。
正準の方向を一つ選ぶ
印刷レイアウトをシステムの記録としたいなら、PDF を保持し、Markdown をエクスポートやエージェント向けの供給とみなす。差分、コードレビュー、エージェントへの取り込みが必要なら、Markdown を優先し、PDF を公開の工程とみなす。両方を対等な「唯一の真実」として保管し、編集後も同一のままだと期待してはいけない。
実務的な docs-as-code のループは、Git で Markdown を編集 → 共有物に Markdown から PDF → PDF→Markdown→PDF を日課にしない、という形だ。引き継いだボーンデジタル PDF からエージェント向けのテキストが必要なときに PDF→Markdown を使い、その Markdown は新しい下書きとして扱う。元の改ページの保証とは考えない。
暗号化されたファイルは、どちらの変換の前にも正当な パスワードの解除 が必要だ。パースできない破損ファイルは、先に 情報取得／修復 を通す。同じエンドポイントを HTTP から使う方法は 開発者向け にある。