HTML to Markdown

Що таке конвертація HTML у Markdown?

Конвертація HTML у Markdown перетворює HTML-розмітку на Markdown — легку синтаксичну систему форматування простого тексту, створену Джоном Грубером у 2004 році. Markdown був розроблений так, щоб бути зрозумілим без рендерингу. Там, де HTML потребує відкривальних і закривальних тегів на кшталт <strong> та <a href="">, Markdown використовує скорочені символи: **жирний**, [посилання](url) та # заголовки. Конвертація HTML у Markdown дає файли, які легше читати, редагувати та керувати версіями, ніж сирий HTML.

Процес конвертації відображає HTML-елементи на їхні еквіваленти в Markdown. Тег <h2> стає ##, <ul><li> стає - елемент, а тег <a> — [текст](url). Деякі HTML-елементи не мають прямого еквівалента в Markdown, наприклад <div>, <span> або власні атрибути даних. Конвертери зазвичай видаляють ці теги або передають їх як сирий HTML — залежно від налаштувань.

Markdown став стандартним форматом для документації розробників (GitHub, GitLab, Bitbucket), генераторів статичних сайтів (Hugo, Jekyll, Astro), застосунків для нотаток (Obsidian, Notion) та технічних блогів. Конвертація наявного HTML-вмісту в Markdown — поширений крок під час міграції вебсайтів, імпорту контенту з CMS або архівування вебсторінок у портативному форматі. На відміну від HTML, файли Markdown дають чіткі diff-и в системі контролю версій, що робить рецензування документації в pull request-ах практичним.

Навіщо використовувати конвертер HTML у Markdown?

Переписувати HTML як Markdown вручну — це повільно й ненадійно, особливо для сторінок з вкладеними списками, таблицями або десятками посилань. Автоматизований конвертер виконує структурне відображення миттєво та послідовно.

Випадки використання HTML to Markdown

Довідник елементів HTML → Markdown

Таблиця нижче показує, як поширені HTML-елементи відображаються на їхні еквіваленти в Markdown. Це відображення відповідає конвенціям GitHub-Flavored Markdown (GFM), що розширює специфікацію CommonMark таблицями, закресленням і списками завдань. Елементи, не зазначені тут (такі як <div>, <form> або власні вебкомпоненти), не мають еквівалента в Markdown і або видаляються, або передаються як сирий HTML.

Варіанти Markdown: GFM vs CommonMark vs оригінальний

Не весь Markdown однаковий. Формат виводу важливий, оскільки різні платформи по-різному аналізують Markdown. Три найпоширеніших варіанти — це GitHub-Flavored Markdown (GFM), CommonMark та оригінальний 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

Поширені запитання