HTMLをMarkdownに変換して表やリンクが崩れたときの直し方

HTMLをMarkdownへ変換して崩れたときは、元のHTML、変換されたテキスト、貼り付け先の表示を分けて確認します。HTMLで表現できる見た目のすべてを、Markdownへそのまま移せるわけではありません。

特に表のセル結合や相対リンクは、変換できたように見えても意味が変わりやすい部分です。全部を作り直す前に、一つの表やリンクだけを抜き出して、どの段階で変わったかを確認すると修正箇所を絞れます。

元HTMLと変換結果を並べて欠けた場所を探す

最初に、元のページと変換結果を残します。元ページのURLも一緒に記録してください。後で相対リンクを直す際の基準になります。コピーを編集し、変換前の原本は上書きしない方が良いです。

HTMLからMarkdown変換ツールの直接取得では、サーバーが受け取ったHTMLを変換します。通常のブラウザのようにページのJavaScriptを実行する処理ではありません。画面に本文が見えても、取得したHTMLにその本文が含まれていない場合があります。

同ツールにはJina経由の選択肢もありますが、入力URLを外部サービスへ送る方式です。社内限定URLや認証情報を含むURLには使わず、公開してよいページだけを対象にしてください。別方式を使えば必ず取得できるという意味でもありません。

表は貼り付け先の対応形式から確かめる

Markdownの表は、すべての処理系で同じように使えるわけではありません。CommonMarkの仕様には標準の表記法がなく、GitHub Flavored Markdownでは拡張として定義されています。変換結果が正しくても、貼り付け先が表に対応していなければ文字列のまま表示されます。

表対応の環境なら、まずヘッダー行の次に区切り行があるかを見ます。次は二列の小さな例です。表の前後は空行で区切ります。

| 項目 | 内容 |
|---|---|
| 連絡方法 | メール |
| 受付時間 | 平日 |

この例が表示できるのに元の表だけ崩れるなら、各行の列数を比べます。セル内に文字として使う縦棒は、GFMでは \| と書いて区切りと区別します。見た目を整えるためのスペースを増やす前に、列の区切りが正しいかを確認してください。

miniToolsの直接変換では、元HTMLの th を見つけたところへ区切り行を追加する実装です。td だけで作られた表は、そのままでは区切り行が入らない場合があります。内容を確認して見出し行を決め、必要な区切りを補います。すべての表で先頭行を機械的に見出しへ変えてよいわけではありません。

セル結合は内容を分けて書き直す

HTMLの rowspan や colspan は、通常のGFMの表にはそのまま対応しません。結合セルを無理に空欄へ置き換えると、どの行に条件がかかるのか分からなくなります。

たとえば「平日」という結合セルが三つの受付項目にかかるなら、各行に「平日」と繰り返して書く方法があります。同じ条件を省略しない方が、Markdownへ移した後も対応関係を保てます。長い注意事項は表の直後へ出し、どの項目に適用するかを本文で示します。

複雑なレイアウトを維持する必要がある場合は、貼り付け先がHTMLの表に対応するかを確認します。ただし、HTMLを削除・無効化するサービスもあります。内容を読める形に変えるのか、見た目を保存するのかを先に決めてください。見た目の保存が目的なら、Markdown以外の形式も検討できます。

相対リンクと画像には元ページの基準が必要

/guide/ や ../image.png は、どのページから読むかによって行き先が決まります。別サイトやローカルファイルへMarkdownを移しただけでは、元と同じ場所を指すとは限りません。MDNのURLコンストラクターの説明でも、相対URLは基準URLと組み合わせて解決することが示されています。

次は元ページが https://example.com/docs/start/ の場合の例です。base 要素などで別の基準が指定されていないことを前提としています。

miniToolsの直接変換は、リンクの href や画像の src を基本的にそのまま出力します。移した先でも同じページを参照したいなら、元ページのURLを基準に絶対URLへ直します。サイト全体の移転なら新しい配置先へ合わせる必要があるため、全部に元ドメインを付ける方法は適しません。

また、元ページ内の #見出しID は、Markdown側で生成されるIDと一致しない場合があります。miniToolsの直接変換では、その形式のリンクは文字だけになるため、必要な箇所は移した先の見出しへリンクし直してください。画像もURLの修正だけで転載可能になるわけではなく、利用許可と保存先を確認します。

表内のリンクや注記は変換結果でも確認する

文字が残っていても、リンク先や注記が失われている場合があります。miniToolsの直接変換は表のセルからテキストを取り出すため、セル内のリンク先や画像そのものは保持しません。比較表の「詳細はこちら」が文字だけになっていないか、元のHTMLと照合してください。

同じ理由で、注記の番号が残っていても、注記本文が抽出対象の外にあると意味が欠けます。本文抽出の際にはナビゲーションなどが省かれるため、元ページで見えていた内容のすべてが結果に含まれるとは限りません。

この確認は、レイアウトをきれいにする前に行います。料金や適用条件を含む表では、一つの注記が消えるだけで結論が変わるためです。欠けた文章を推測で補わず、元の内容へ戻って確かめます。

一つの箇所を直してから全体へ適用する

最初から全ページを再変換せず、問題のある表やリンクを一つ直し、実際の貼り付け先で確認します。全体へ進む前の確認は次の順番で行います。

1. 元ページの本文と注記が変換結果に揃っているか確認する。
2. 表の見出し・区切り・各行の列数を揃える。
3. セル結合の条件を各行や本文へ移し、意味が変わっていないか照合する。
4. リンクと画像を移転後の場所に合わせ、一つずつ行き先を確認する。
5. 貼り付け先の表示で問題がないことを確かめてから、残りの箇所へ進む。

Markdown自体の基本記法で迷う場合は、Markdownの書き方を参照してください。変換崩れへの対応では、まず一つの箇所について「元HTMLには何があり、どこで失われたか」を確かめることが先です。