HTML to Markdown

HTMLからMarkdownへの変換とは？

HTMLからMarkdownへの変換は、HTMLマークアップをMarkdownに変換します。MarkdownはJohn Gruberが2004年に作成した軽量なプレーンテキスト形式の構文です。Markdownはレンダリングなしでも読みやすいように設計されました。HTMLでは<strong>や<a href="">のような開始タグと終了タグが必要ですが、Markdownは省略記号を使います：**太字**、[リンク](url)、# 見出しのように。HTMLをMarkdownに変換すると、生のHTMLよりも読みやすく、編集しやすく、バージョン管理に適したファイルが生成されます。

変換処理はHTML要素をMarkdownの対応要素にマッピングします。<h2>は##に、<ul><li>は- 項目に、<a>タグは[テキスト](url)になります。<div>、<span>、カスタムデータ属性など、直接対応するMarkdown要素が存在しないHTML要素もあります。コンバーターは通常、設定に応じてこれらのタグを削除するか、生のHTMLとしてそのまま出力します。

Markdownは開発者向けドキュメント（GitHub、GitLab、Bitbucket）、静的サイトジェネレーター（Hugo、Jekyll、Astro）、ノートアプリ（Obsidian、Notion）、技術ブログの標準的な記述形式となっています。既存のHTMLコンテンツをMarkdownに変換することは、ウェブサイトの移行、CMSコンテンツのインポート、またはウェブページをポータブルな形式でアーカイブする際の一般的な手順です。HTMLとは異なり、Markdownファイルはバージョン管理で差分が明確に表示されるため、ドキュメント変更のコードレビューが実用的になります。

HTML to Markdownコンバーターを使う理由

HTMLを手動でMarkdownに書き直すのは時間がかかり、特にネストされたリスト、表、多数のリンクを含むページでは誤りが生じやすいです。自動化されたコンバーターは構造のマッピングを即座かつ一貫して処理します。

HTML to Markdownの活用例

HTML→Markdown要素対応表

以下の表は一般的なHTML要素がMarkdownの対応要素にどのようにマッピングされるかを示しています。このマッピングはGitHub-Flavored Markdown（GFM）の規則に従っており、CommonMarkの仕様を表、取り消し線、タスクリストで拡張しています。ここに記載されていない要素（<div>、<form>、カスタムWebコンポーネントなど）にはMarkdownの対応要素がなく、削除されるか生のHTMLとしてそのまま出力されます。

Markdownのフレーバー：GFM vs CommonMark vs オリジナル

すべてのMarkdownが同じというわけではありません。出力形式はプラットフォームによってMarkdownの解析方法が異なるため重要です。最も一般的な3つのフレーバーはGitHub-Flavored Markdown（GFM）、CommonMark、GruberのオリジナルのMarkdownです。

コード例

JavaScript（Turndown）、Python（markdownifyおよびhtml2text）、Go、コマンドラインのPandocでの実際の使用例。

import TurndownService from 'turndown'

const turndown = new TurndownService({ headingStyle: 'atx' })
const html = '<h1>Title</h1><p>A <strong>bold</strong> paragraph.</p>'
const md = turndown.turndown(html)
console.log(md)
// → "# Title\n\nA **bold** paragraph."

from markdownify import markdownify

html = '<h2>Section</h2><ul><li>First</li><li>Second</li></ul>'
md = markdownify(html, heading_style='ATX')
print(md)
# → "## Section\n\n- First\n- Second"

import html2text

converter = html2text.HTML2Text()
converter.body_width = 0  # disable line wrapping

html = '<p>Visit <a href="https://example.com">Example</a> for details.</p>'
md = converter.handle(html)
print(md)
# → "Visit [Example](https://example.com) for details."

package main

import (
	"fmt"
	md "github.com/JohannesKaufmann/html-to-markdown"
)

func main() {
	converter := md.NewConverter("", true, nil)
	html := `<h3>Go Example</h3><p>Code: <code>fmt.Println()</code></p>`
	markdown, _ := converter.ConvertString(html)
	fmt.Println(markdown)
	// → "### Go Example\n\nCode: `fmt.Println()`"
}

# Convert an HTML file to Markdown
pandoc input.html -f html -t markdown -o output.md

# Pipe HTML from stdin
echo '<p>Hello <em>world</em></p>' | pandoc -f html -t markdown
# → Hello *world*

# Use GitHub-Flavored Markdown output
pandoc input.html -f html -t gfm -o output.md

よくある質問