Markdown против HTML: Что использовать для контента?
Быстрый ответ
Используйте Markdown для прозы (README, docs, блогпосты, chat), где важна читаемость исходника. Используйте HTML когда нужен точный layout, интерактивные элементы или семантические теги, которых нет в Markdown. Используйте наш Markdown Preview для live-рендеринга.
Введение
Markdown — лёгкий язык разметки, маппящий в малый subset HTML. HTML — полнофункциональный язык разметки web. Markdown фаворит человеко-читаемый исходник, конвертируемый в HTML; HTML фаворит точный контроль над рендерингом. Это не столько конкуренты, сколько инструменты на разных уровнях абстракции —а большинство Markdown-рендереров выводят HTML.
Шаг за шагом
-
Сравните читаемость источника
Источник Markdown близок к обычному тексту: **жирный**, *курсив*, # заголовок, — элемент списка. HTML источник подробный: <strong>жирный</strong>, <em>курсив</em>, <h1>заголовок</h1>, <ul><li>...</li></ul>. Что касается прозы, Markdown гораздо проще читать и редактировать в обычном текстовом редакторе.
-
Сравните выразительность
Markdown покрывает ~20% HTML: заголовки, абзацы, списки, выделения, ссылки, изображения, блоки кода, цитаты. HTML покрывает 100%: формы, таблицы с rowspan/colspan, семантические теги (<article>, <nav>, <aside>), атрибуты данных, встроенный SVG, скрипты. Когда вам нужно то, чего не хватает Markdown, вы либо переходите на встроенный HTML, либо полностью переключаетесь на HTML.
-
Сравните кривую обучения
Синтаксис Markdown умещается на одной странице и его можно изучить за 10 минут. HTML имеет около 140 элементов, атрибутов и модель DOM — более крутую, но все же доступную кривую. Для нетехнических писателей (руководителей проектов, маркетологов, сотрудников службы поддержки) Markdown — явный выигрыш.
-
Сравните рендеринг и переносимость
Markdown должен быть преобразован в HTML (или другой формат), чтобы его можно было отобразить в браузере. Отображение выполняется с помощью таких библиотек, как Marked, Comment или CommonMark. HTML отображается непосредственно в любом браузере без этапа сборки. Markdown переносим на несколько форматов вывода (HTML, PDF, EPUB, docx); HTML доступен только в Интернете без конвертации.
-
Решите, исходя из вашего варианта использования
Документация, файлы README, чат, комментарии, сообщения в блогах: Markdown. Маркетинговые страницы, интерактивный интерфейс, шаблоны электронной почты, сложные таблицы, семантическая структура: HTML. Многие системы (GitHub, Notion, генераторы статических сайтов) принимают Markdown со встроенным HTML, что дает лучшее из обоих.
Примеры
Жирный и курсив
Вход: Markdown: **bold** and *italic* | HTML: <strong>bold</strong> and <em>italic</em>
Выход: Оба отображаются как: жирный и курсив.
Заголовок со ссылкой
Вход: Markdown: ## [FreeOnlineTools](https://freeonlinetoolsgo.com) | HTML: <h2><a href="https://freeonlinetoolsgo.com">FreeOnlineTools</a></h2>
Выход: Both render as an <h2> containing a clickable link to freeonlinetoolsgo.com
Таблица — Markdown против HTML
Вход: Markdown: | A | B |\n|---|---|\n| 1 | 2 | | HTML: <table><tr><th>A</th><th>B</th></tr><tr><td>1</td><td>2</td></tr></table>
Выход: Оба отображают таблицу 2x2. HTML требуется для ячеек colspan, rowspan или стилизованных ячеек.
То, что Markdown не может сделать — ввод формы.
Вход: HTML: <input type="email" placeholder="you@example.com">
Выход: В Markdown нет синтаксиса для элементов управления форм — вы должны использовать встроенный HTML или полностью переключиться на HTML.
Распространенные проблемы
- Фрагментация диалекта Markdown: CommonMark, GFM, MultiMarkdown и MDX различаются таблицами, сносками, списками задач и математическими вычислениями. Выберите диалект и средство рендеринга, которое явно его поддерживает, чтобы избежать неожиданных различий в рендеринге.
- XSS через встроенный HTML в Markdown: большинство средств визуализации по умолчанию допускают необработанный HTML, поэтому предоставленный пользователем Markdown может внедрить <script>. Настройте средство рендеринга на очистку (например, DOMPurify) или отключите необработанный HTML для ненадежного ввода.
- Чувствительность к пробелам: Markdown сжимает соседние строки в один абзац, если они не разделены пустой строкой, и отступы блоков кода на 4 пробела. При копировании из богатого редактора часто теряются пустые строки и нарушается структура.
- Нет семантической структуры: ## в Markdown представляет собой <h2>, но не передает никакой семантики за пределами уровня. Для доступной навигации (<nav>), статей (<article>) и боковых статей (<aside>) вам нужны оболочки HTML вокруг вывода Markdown.
Советы
- Используйте Markdown для тела документов и HTML для оболочки страницы — большинство генераторов статических сайтов (Astro, Eleventy, Next) поддерживают это разделение изначально.
- Разрешая пользовательский ввод Markdown, всегда очищайте визуализируемый HTML с помощью DOMPurify, чтобы удалить атрибуты <script>, on* и javascript: URLs — никогда не доверяйте экранированию по умолчанию средства визуализации.
- Воспользуйтесь нашим предварительным просмотром Markdown, чтобы увидеть, как именно средство рендеринга преобразует ваш Markdown в HTML, прежде чем зафиксировать его в README или документе.
- Для сложных таблиц (colspan, caption, стилизованные заголовки) напишите их в HTML и встройте в Markdown — большинство средств визуализации передают встроенный HTML без изменений.