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> — элементом списка - item, а тег <a> — конструкцией [текст](url). Некоторые HTML-элементы не имеют прямого эквивалента в Markdown: например, <div>, <span> или пользовательские атрибуты данных. Как правило, конвертеры удаляют эти теги или передают их как исходный HTML — в зависимости от настроек.

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

Зачем использовать конвертер HTML в Markdown?

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

Сценарии использования HTML to Markdown

Справочник по сопоставлению элементов HTML и Markdown

В таблице ниже показано, как распространённые HTML-элементы сопоставляются с эквивалентами Markdown. Сопоставление следует соглашениям GitHub-Flavored Markdown (GFM), который расширяет спецификацию CommonMark таблицами, зачёркиванием и списками задач. Элементы, не перечисленные здесь (например, <div>, <form> или пользовательские веб-компоненты), не имеют эквивалента в Markdown и либо удаляются, либо передаются как исходный HTML.

Разновидности Markdown: GFM, CommonMark и оригинал

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

Часто задаваемые вопросы