HTML to Markdown

Co je převod HTML do Markdown?

Převod HTML do Markdown transformuje HTML značky na Markdown — odlehčenou syntaxi pro formátování prostého textu, kterou v roce 2004 vytvořil John Gruber. Markdown byl navržen tak, aby byl čitelný i bez vykreslování. Tam, kde HTML vyžaduje otevírací a uzavírací značky jako <strong> nebo <a href="">, Markdown používá zkratkové znaky: **tučné**, [odkaz](url) a # nadpisy. Převod HTML do Markdown produkuje soubory, které se snáze čtou, upravují a verzují než surové HTML.

Při převodu se HTML elementy mapují na jejich Markdown ekvivalenty. <h2> se stane ##, <ul><li> se stane - položka a <a> značka se přemění na [text](url). Některé HTML elementy nemají přímý Markdown ekvivalent, například <div>, <span> nebo vlastní datové atributy. Převodníky tyto značky obvykle odstraní nebo je ponechají jako surové HTML, záleží na konfiguraci.

Markdown se stal standardním formátem pro vývojářskou dokumentaci (GitHub, GitLab, Bitbucket), generátory statických stránek (Hugo, Jekyll, Astro), aplikace pro psaní poznámek (Obsidian, Notion) a technické blogy. Převod stávajícího HTML obsahu do Markdown je obvyklý krok při migraci webů, importu obsahu z CMS nebo archivaci webových stránek v přenosném formátu. Na rozdíl od HTML produkují Markdown soubory čisté diffy ve správě verzí, což usnadňuje revize změn dokumentace.

Proč použít převodník HTML do Markdown?

Ruční přepisování HTML na Markdown je pomalé a náchylné k chybám, zejména u stránek s vnořenými seznamy, tabulkami nebo desítkami odkazů. Automatizovaný převodník zvládne strukturní mapování okamžitě a konzistentně.

Případy použití převodníku HTML do Markdown

Přehled mapování HTML elementů na Markdown

Tabulka níže ukazuje, jak se běžné HTML elementy mapují na jejich Markdown ekvivalenty. Toto mapování se řídí konvencemi GitHub-Flavored Markdown (GFM), které rozšiřují specifikaci CommonMark o tabulky, přeškrtnutí a seznamy úkolů. Elementy neuvedené v tabulce (například <div>, <form> nebo vlastní webové komponenty) nemají Markdown ekvivalent a jsou buď odstraněny, nebo ponechány jako surové HTML.

Varianty Markdown: GFM vs. CommonMark vs. originál

Ne všechny Markdown jsou stejné. Výstupní formát je důležitý, protože různé platformy parsují Markdown odlišně. Tři nejrozšířenější varianty jsou GitHub-Flavored Markdown (GFM), CommonMark a Gruberův originální Markdown.

Ukázky kódu

Funkční příklady v JavaScriptu (Turndown), Pythonu (markdownify a html2text), Go a Pandocu na příkazovém řádku.

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

Nejčastější dotazy