note入稿の崩れをMarkdown変換と図版レンダラで止めた
今回やったこと
外部プラットフォームへ記事を移す工程で、Markdownをそのまま貼り付ける方式を見直した。対象は、太字や表が崩れる問題と、記事内の図版を別途画像として用意する問題である。解決策は大きなCMS連携ではなく、正本のMarkdownから貼り付け用Markdown、HTML、PNGをそれぞれ生成する小さな変換パイプラインだった。
この記事の対象は、同じ本文を自サイトと外部サービスの両方へ載せたい個人開発者や小規模チームである。実装は運用中で、入力となる記事の正本を残したまま、貼り付け先の都合だけを派生物へ閉じ込めている。
Markdownをそのまま貼らない理由
note_paste_build.py は正本の frontmatter を取り除き、表を貼り付け先で扱える箇条書きへ置き換える。貼り付け先のエディタには表機能がなく、全角スペースが混じるとMarkdown変換全体が崩れるため、出力では全角スペースも使わない。チェックボックスもそのままの task list ではなく、☐ へ変換する。つまり、正本を壊して相手に合わせるのではなく、相手用の別ファイルを作る設計である。
python3 scripts/note_paste_build.py sites/zashstudio/drafts/note/<slug>.md
python3 scripts/note_md_to_html.py sites/zashstudio/drafts/note/<slug>.note.txt
生成物には、直接編集しないことと、どの差分が貼り付け先向けなのかをコメントとして残す。表の置換文が用意されていない場合は、変換を続けずエラーにする。変換できない表を黙って落とすより、入力側に不足を返す方が、公開前の確認点を減らせる。
さらに、貼り付け先のMarkdown変換器はCommonMarkのdelimiter run規則を完全には同じ形で扱わない。太字記号が残るケースがあるため、note_md_to_html.py でHTMLへ変換し、text/html として貼る手順を採用した。変換先に合わせた最後の表現だけをHTMLにし、記事の正本はMarkdownのまま保つ。
図版を本文と同じ工程に置く
図版は記事本文のHTMLに直接書くのではなく、<figure id="..."> を持つHTMLファイルからPNGを生成する。note_figure_render.py は図版を1枚ずつ抽出し、記事幅の約2倍にあたる1280pxを基準にレンダリングする。図版の配色、余白、見出し、補足文をCSSで定義しておけるため、画像編集ソフトで毎回手作業をする必要がない。
<slug>.figures.html
↓ <figure id="..."> を抽出
figures/<slug>--<id>.png
背景色を敷いたPNGにする処理もレンダラ側に置かれている。透過画像を貼り先の背景へ任せると、サービス側のテーマ変更で見え方が変わるためである。見出し画像も本文図版も同じ資産の考え方で管理し、貼り付け時にだけ必要なサイズへ落とす。
うまくいかなかったことと判断
最初に考えがちな方法は、正本Markdownをそのまま複数サービスへ貼ることだが、表・全角スペース・task list・太字の扱いが相手ごとに違う。ここを人の注意力で補うと、記事ごとに確認項目が増え、どこかで崩れが残る。そこで変換をスクリプトに固定し、足りない変換定義はエラーにする方針にした。
一方で、この方式は外部サービスの仕様差を永遠に消すものではない。変換器の仕様が変わればテストと出力の見直しが必要であり、貼り付け後の表示確認も残る。それでも、入力から出力までの再現可能な工程があれば、崩れが「どの段階で起きたか」を追える。自動化の価値は、手作業をゼロにすることではなく、手作業で確認すべき場所を狭くすることにある。
この記事について
この記事は、リポジトリ内の scripts/note_paste_build.py、scripts/note_md_to_html.py、scripts/note_figure_render.py と、候補キューに記録された運用概要をもとに整理した。変換の詳細は各スクリプトを正本とし、外部サービスの仕様を推測で補っていない。
更新履歴
- 2026-09-20: 初稿。
訂正履歴
なし。