MarkdownとHTMLをブラウザ内で変換する
入力をサーバーへ送信せず、変換結果のSourceと安全化されたPreviewを分けて確認できます。
HTMLをMarkdownへ変換する結論：HTMLをDOMとして解析し、意味のある要素をMarkdown記法へ対応付ける
h1～h6、p、strong/em、ul/ol、blockquote、pre/code、a、img、table等はMarkdownへ対応できます。
class、style、data属性、Layout用div、複雑なTable等はMarkdownに同等表現がなく、簡略化や損失が発生します。
変換が成功したことと、利用先で意味・見た目・安全性が保たれることは別に確認してください。
Tag置換ではなくDOMと変換Ruleで処理する
文字列置換では入れ子、属性、Entity、空白を壊しやすいため、DOMParserでTreeを作り、Node種別ごとに変換します。
現行ツールはURLからHTMLを取得しません。HTML SourceまたはFileを利用し、認証Cookieや個人情報を含む内容は共有前に除去します。
| 確認対象 | 確認内容 | 判断 |
|---|---|---|
| Heading | h1～h6 | #の数 |
| List | ul/ol/li | 入れ子Indent |
| Code | pre/code | Fence長と言語Class |
| Link/Image | href/src | Base URL |
Markdown・HTML相互変換ツールで確認する手順
- HTML→Markdownを選び、HTMLを貼るかFileを開きます。
- 未対応要素を保持・Text化・削除から選びます。
- 相対URLを解決する必要があればBase URLを入力します。
- 変換し、Markdown SourceとPreviewを確認します。
Base URLへCredentialやTokenを含めないでください。ToolはURL先をFetchしません。
HTML要素とMarkdownの対応
| HTML | Markdown | 失われ得る情報 |
|---|---|---|
| <h2> | ## | id・class |
| <strong> | ** ** | style |
| <a href> | [text](url) | data属性 |
| <table> | Pipe Table | rowspan・colspan |
変換・表示・安全化を別工程として確認する
| 工程 | 主な役割 | ここでは保証しないこと |
|---|---|---|
| Parse・変換 | Markdown構文をHTML要素へ、またはHTML DOMをMarkdown記法へ対応付ける | CSSの見た目、利用先独自拡張 |
| Sanitize | script、iframe、form、event属性、危険URL等を除外する | 元HTMLの完全保持、すべての業務要件への適合 |
| Preview | 安全化済み結果をアプリ本体と分離したiframeで確認する | 本番CMSと同一CSS、外部Resourceの永続性 |
| 保存・貼り付け | 確認済みSourceをFileまたはClipboardへ出す | 変換先での再Sanitizeや自動整形 |
MarkdownのRaw HTMLを許可する設定はSanitizeを無効にする設定ではありません。Raw HTMLを構文として受け入れるかどうかと、生成HTMLから危険要素を除くかどうかは独立した判断です。信頼できない入力を無加工でinnerHTMLへ入れず、変換後もSanitizeし、実行可能なPreviewから隔離します。
変換後に確認する回帰テスト
- 見出し、段落、太字、斜体、順序付き・順序なし・入れ子List、引用、水平線を確認する
- Inline Code、Fenced Code、Fence内のBacktick、言語指定、HTMLのpre/codeを確認する
- Link、Reference Link、Image、相対URL、URLを含む括弧、Title属性を確認する
- GFMのTable、Task List、取り消し線、Autolinkを変換先と同じ方言で確認する
- Raw HTML、HTML Entity、&・<・>、2 Space改行、空行、Whitespaceを確認する
- script、onclick、javascript:、iframe、form等がPreviewや保存結果で実行可能にならないか確認する
- Markdown→HTML→MarkdownのRound Trip差分を取り、意味・属性・空白・表現形式の損失を確認する
現行のMarkdown・HTML相互変換ツールで確認できる範囲
DevelopToolsの現行ツールは、Markdown→HTMLとHTML→Markdownをブラウザ内だけで処理します。Markdown→HTMLはMarkedをGFMモードで使用し、見出し、段落、強調、リスト、引用、表、タスクリスト、取り消し線、コード、リンク、画像を変換します。HTML→MarkdownはDOMParserで解析したDOMを独自のタグ別ルールで直列化し、見出し、段落、強調、リスト、引用、表、pre/code、リンク、画像などを変換します。
| 機能 | 現行ツールの動作 |
|---|---|
| 入力 | Text貼り付け、Markdown・HTML File読込、Drag & Drop |
| Markdown方言 | MarkedのGFMモード。改行をbrへ変換するOptionを切替可能 |
| HTML出力 | HTML断片または完全Document、整形または1行圧縮 |
| HTML→Markdown | 独自Converter。未対応要素を保持・Text化・削除から選択 |
| 安全化 | DOMPurifyで変換結果をSanitizeし、CSP付きsandbox iframeでPreview |
| 外部通信 | 変換自体は送信なし。外部画像Previewを明示的に有効化した場合だけ画像HostへRequest |
| 未対応 | URLからのWeb Page取得、CSS再現、JavaScript実行後DOM取得、完全な往復復元、Front Matter専用解析 |
変換結果のSourceとPreviewは別物です。保存・貼り付け用Sourceを確認し、次に安全化されたPreviewで構造を確認します。CSSによる最終Appearance、CMS固有Sanitizer、相対URLの基準、変換先が採用するMarkdown方言は利用先でも再確認してください。
仕様とライブラリの公式資料で確認する
Markdownには実装差があるため、構文の期待値はCommonMark、GFM拡張はGitHub Flavored Markdown、利用中ParserのOptionはその公式Documentを確認します。Markedは出力HTMLをSanitizeしないと公式に明記しているため、変換後のSanitizeを別工程として扱います。TurndownはHTML→Markdown実装の代表例としてRule・Keep・Remove・GFM Pluginの考え方を確認する資料であり、現行ツール自体はTurndownを使用していません。
具体例：CMS本文HTMLをMarkdown原稿へ戻す
本文のh2、p、ul、pre/code、aを含むHTML断片を入力します。
再編集しやすいMarkdownへ変換できますが、CMS固有classは別途記録が必要です。
- HTML抽出
- 未対応要素設定
- 変換
- Source差分確認
現行ツールは独自Converterであり、Turndownを使用していません。
よくある質問
- Markdown→HTML→Markdownで元の文章へ完全に戻せますか？
- 完全には戻せません。同じ意味を複数のMarkdown記法で表せるうえ、HTMLのclass・style・data属性・複雑な表・空白にはMarkdown側の対応表現がないためです。往復後の差分を必ず確認してください。
- Raw HTMLを許可すればscriptも保存できますか？
- 現行ツールでは保存できません。Raw HTMLの解釈設定とは別にDOMPurifyでscript、iframe、form、event属性等を除去し、PreviewにもCSPを設定します。
- 入力内容はサーバーへ送信されますか？
- 変換、File読込、Copy、Downloadはブラウザ内で完結します。ただし外部画像Previewを有効にすると、ブラウザが画像URLのHostへRequestします。