Konwerter HTML do Markdown

Czym jest konwersja HTML do Markdown?

Konwersja HTML do Markdown przekształca znaczniki HTML w Markdown — lekką składnię formatowania zwykłego tekstu stworzoną przez Johna Grubera w 2004 roku. Markdown został zaprojektowany tak, by był czytelny bez renderowania. Tam gdzie HTML wymaga otwierających i zamykających tagów, takich jak <strong> czy <a href="">, Markdown używa skrótowych znaków: **pogrubienie**, [linki](url) i # nagłówki. Konwersja HTML do Markdown tworzy pliki łatwiejsze do odczytu, edycji i kontroli wersji niż surowe HTML.

Proces konwersji odwzorowuje elementy HTML na ich odpowiedniki w Markdown. <h2> staje się ##, <ul><li> staje się - element, a tag <a> staje się [tekst](url). Niektóre elementy HTML nie mają bezpośredniego odpowiednika w Markdown, np. <div>, <span> czy własne atrybuty danych. Konwertery zazwyczaj usuwają te tagi lub przekazują je jako surowe HTML, zależnie od konfiguracji.

Markdown stał się standardowym formatem pisania dokumentacji deweloperskiej (GitHub, GitLab, Bitbucket), generatorów stron statycznych (Hugo, Jekyll, Astro), aplikacji do notatek (Obsidian, Notion) i blogów technicznych. Konwersja istniejącej zawartości HTML do Markdown to częsty krok przy migracji stron, imporcie treści z CMS lub archiwizowaniu stron w przenośnym formacie. W odróżnieniu od HTML, pliki Markdown generują czytelne diff-y w systemach kontroli wersji, co czyni przegląd zmian dokumentacji praktycznym zadaniem.

Dlaczego warto używać konwertera HTML do Markdown?

Ręczne przepisywanie HTML jako Markdown jest powolne i podatne na błędy, szczególnie w przypadku stron z zagnieżdżonymi listami, tabelami lub dziesiątkami linków. Zautomatyzowany konwerter obsługuje całe strukturalne odwzorowanie natychmiastowo i spójnie.

Zastosowania konwertera HTML do Markdown

Tabela odwzorowania elementów HTML na Markdown

Poniższa tabela pokazuje, jak typowe elementy HTML są odwzorowywane na odpowiedniki w Markdown. Odwzorowanie jest zgodne z konwencjami GitHub-Flavored Markdown (GFM), które rozszerzają specyfikację CommonMark o tabele, przekreślenie i listy zadań. Elementy nieuwzględnione w tabeli (takie jak <div>, <form> czy własne komponenty webowe) nie mają odpowiednika w Markdown i są usuwane lub przekazywane jako surowe HTML.

Warianty Markdown: GFM kontra CommonMark kontra oryginalny

Nie wszystkie odmiany Markdown są takie same. Format wyjściowy ma znaczenie, ponieważ różne platformy inaczej przetwarzają Markdown. Trzy najpopularniejsze warianty to GitHub-Flavored Markdown (GFM), CommonMark i oryginalny Markdown Grubera.

Przykłady kodu

Działające przykłady w JavaScript (Turndown), Python (markdownify i html2text), Go oraz Pandoc w wierszu poleceń.

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

Często zadawane pytania