Я переношу контент, чтобы зарабатывать на жизнь, в том смысле, что любой, кто в течение десятилетия запускал сайт WordPress, в конце концов это делает. когда я переместил партию старых сообщений из конструктора страниц в систему документов на основе Markdown, я обнаружил, что & quot;чистый HTML& quot; действительно означает в дикой природе: <p> теги со встроенными стилями, пустые <span>s завертывая отдельные слова, <div>s три уровня глубоко вокруг абзаца и случайный тег, который просто никогда не закрывался. Вставка этого в поле Markdown дала мне стену буквальных угловых скобок. Копирование - вставление визуализированный текст потерял каждую ссылку, заголовок и список. Ни один ярлык не сработал, и в итоге я на полдень очистил статьи вручную, прежде чем стал относиться к этому разумно.
Получить разумное означало относиться к HTML-to-Markdown как к тому, что это такое: структурированное преобразование с четким набором правил, а не копипаст. Элемент заголовка становится а # линия. Жирный становится **. Ссылка становится [text](url).Таблица становится таблицей трубок. как только у вас есть эти сопоставления и синтаксический анализатор, достаточно толерантный, чтобы пережить реальную разметку, преобразование скучно и надежно - это именно то, что вы хотите. Я создаю [Toolz.dev](/и ставлю браузер на основе Конвертер HTML в Markdown там применяются эти правила, но это руководство посвящено самим правилам, поэтому вы понимаете, как должен выглядеть результат и почему.
TL;DR: Чтобы преобразовать HTML в Markdown, сопоставьте элементы блоков с их эквивалентами Markdown (
<h2>→##,<ul><li>→-,<blockquote>→>,<pre><code>→ огороженный блок), отобразить встроенные элементы (<strong>→**,<em>→*,<a>→[text](href),<img>→), поворот<table>в таблицу каналов GitHub Flavored Markdown декодируйте объекты HTML обратно на реальные символы и переходите<script>/<style>. Используйте анализатор, устойчивый к незакрытым тегам, и делайте это в браузере, чтобы ваш контент никогда не загружался.
Зачем вообще конвертировать HTML в Markdown?
Markdown - портативный формат современной сети разработчиков. Файлы README, сайты документации, статические блоги (контент Хьюго, Джекила, Астро, Next.js), заметьте такие приложения, как Obsidian и Bear, проблемы GitHub, а также все чаще подсказки и контекст, которые мы передаем моделям искусственного интеллекта - все они говорят на Markdown. It' простой текст, он четко различается в Git и выживает, перемещаясь из одной системы в другую, не перетаскивая за собой кучу презентационной разметки.
HTML, напротив, - это то, что вы в итоге с всякий раз, когда контент проходит через браузер или редактор WYSIWYG Копируйте раздел с веб-страницы, экспортируйте из CMS, вытащите тело статьи из API или захватите форматированный текст из поля с богатым текстом, и вы получите HTML - обычно загроможденный HTML, полный элементов оболочки и встроенных стилей, которые вы не хотите ' не хотите в чистом документе. Конверсия - это мост из & quot;content, попавший в разметку и цитирование презентации; в & quot;content Я могу версию, редактирование и повторную публикацию в любом месте. & quot;
Сценарии повторяются постоянно, как только вы их замечаете. Миграция блога с WordPress или Medium. извлечение документации из устаревшей справочной системы HTML. Превращение очищенной статьи в примечание к разметке. Преобразование информационного бюллетеня по электронной почте и HTML #39;s в черновик разметки. Подача веб-страницы и контента #39;s в LLM как чистый контекст вместо необработанного HTML, который тратит токены <div> суп. В каждом случае альтернативы вручную - перепечатывание или копирование визуализированного текста и восстановление форматирования вручную - медленны и потеряны. Преобразователь, основанный на правилах, не является ни тем, ни другим.
Как HTML сопоставляется с Markdown?
Сопоставление естественным образом разделяется на два уровня: структуру на уровне блока и встроенное форматирование.
Блочные элементы определите скелет документа & #39;s, и каждый из них имеет прямой аналог Markdown:
<h1>-<h6>стать#через######заголовки.<p>становится абзацем, разделенным пустыми строками.<ul>/<li>стать-бульонные списки;<ol>/<li>стать1.пронумерованные списки и вложенные списки отступают на две пробелы.<blockquote>префиксы каждой строки с>, йо-<hr>становиться---, йо-<pre><code>становится огороженным кодовым блоком с тройными обратными тиками.<table>становится таблицей трубок GitHub Flavored Markdown.
Встроенные элементы украсить текст внутри этих блоков:
<strong>а<b>стать**bold**, йо-<em>а<i>стать*italic*, йо-<code>становиться`inline code`, йо-<a href="...">становиться[link text](href), сохраняяtitleатрибут, если он присутствует.<img>становиться, йо-<del>а<s>стать~~strikethrough~~(расширение Markdown со вкусом GitHub).<br>становится разрывом жесткой линии - два конечных пространства перед новой линией.
Запустите эти правила через реальный блок HTML, и структура сохранится в целости и сохранности. Учитывая этот вход:
<article>
<h1>Getting Started</h1>
<p>Convert <strong>HTML</strong> into clean <em>Markdown</em>.</p>
<ul>
<li>Paste from a CMS</li>
<li>Get portable output</li>
</ul>
<pre><code class="language-js">const md = convert(html)</code></pre>
</article>
вы получаете:
# Getting Started
Convert **HTML** into clean *Markdown*.
- Paste from a CMS
- Get portable output
```js
const md = convert(html)
```
Стоит отметить две детали этого результата. Во-первых, <article> обертка ничего не внесла - конструкционные контейнеры типа <article>, <section>, и <div> прозрачны; конвертер рекурсирует в них и делает их детей блоками. Во-вторых, кодовое ограждение поднялось js как его язык. Это & #39;s потому что <code> элемент перенесен class="language-js", синтаксические хайлайтеры конвенции используют, и хороший конвертер читает этот класс, чтобы обозначить забор. It's маленькая вещь, которая делает разницу между кодовым блоком, который выделяет на вашем сайте документов, и тем, который делает 't.
Что заставляет конвертер выживать в реальном HTML?
Приведенные выше правила - это легкая часть Причина, по которой ручные конвертеры регекса терпят неудачу - и I'выписал и выбросил пару - заключается в том, что настоящий HTML постоянно нарушает предположения Три проблемы возникают снова и снова.
Незакрытые теги. Браузеры, как известно, прощают: <p>one<p>two отображается как два абзаца, потому что а <p> неявно закрывается, когда открывается другой элемент блока, и <li>a<li>b является двумя элементами списка по одной и той же причине. наивный синтаксический анализатор, который закрывает элементы только на явном </p> вложит второй абзац в первый и исказит все ниже по потоку. Надежный конвертер применяет те же правила подразумеваемого конца тега, которые определяет спецификация HTML: открытие элемента уровня блока закрывает открытый абзац; открытие а <li> закрывает предыдущий Мой конвертер делает это, поэтому вставка неаккуратного CMS выхода обычно просто работает.
<script> а <style> блоки. Они содержат код и CSS, а не контент, и их содержание должно быть дословно (а < внутри JavaScript не тег), а затем полностью отброшен. Забудьте специально оформить их, и вы получите источник JavaScript, истекающий в вашу Markdown.
сущности HTML. Веб-контент усеян &, ©, —, и числовые ссылки, например ’. В Markdown - обычном тексте - вам нужны настоящие символы: &, ©, —, и настоящий апостроф. расшифровка именованных и числовых объектов не является необязательной; пропустите его, и ваша чистая разметка будет читаться как view-source.
Вот почему я перестал пытаться конвертировать HTML с помощью find-and-replace и вместо этого построил правильный терпимый синтаксический анализатор. Он токенизирует HTML в дерево - обрабатывает комментарии, пустотные элементы, такие как <br> а <img>, имена тегов заглавных букв, и нецитируемые атрибуты - а затем ходит по этому дереву, излучая Markdown. Примечательно, что он делает 't полагается на браузер's DOM, что означает, что та же логика работает и на сервере, но практическая выгода для вас проста: это не 't бросает на беспорядочную разметку, из которой состоят настоящие веб-сайты.
Как использовать конвертер?
На Toolz.dev/tools/html-to-markdown, вставить свой HTML в левую панель и Markdown появляется справа, как вы вводите - там's нет загрузки и нет кнопки Конвертировать для поиска Загрузить образец, если вы хотите видеть каждую поддерживаемую конструкцию сразу.
Несколько вариантов охватывают общие предпочтения. Выберите своего персонажа-пулю (-, *, или +) для неупорядоченных списков, соответствующих вашему проекту и стилю #39;s. Сохраняйте разметку со вкусом GitHub для таблиц и зачеркивания или выключите, если ваша цель принимает только CommonMark. Переключить " поддерживать ссылки и котировки; выключить, когда вам нужна проза, но не URL-адреса - удобно для превращения статьи с большим количеством ссылок в текст для чистого чтения - и & quot; сохранять изображения и котировки; выключить, чтобы полностью удалить изображения. В строке статистики показаны слова, заголовки, ссылки, изображения, блоки кода и расчетное время чтения, что является быстрой проверкой здравомыслия, что структура наткнулась перед тем, как вы где-то вставите результат.
Как и во всем на сайте, конвертация на 100% клиентская. парсер является простым JavaScript, работающим в вашем браузере, поэтому вставленные страницы, внутренняя документация и неопубликованные черновики никогда никуда не отправляются. That's по умолчанию для работы с контентом - вам не следует 's сервер просто для его переформатирования - и это означает, что инструмент продолжает работать в автономном режиме. Я углубляюсь в вопрос, почему обработка на стороне браузера имеет значение в сервере stranger's Руководство по инструментам конфиденциальности данных, йо-
HTML vs Markdown: когда и что использовать
Превращаться между ними легко; знать, чего вы хотите, - это настоящее решение.
| Аспект | HTML | Уценка |
|---|---|---|
| Первичная цель | Рендеринг в браузере | Написание и хранение текста |
| Читаемость как источник | Бедный (тяжелый) | Отлично (читается простым текстом) |
| Git diffs | Шумный | Чистый |
| Переносимость между системами | Низкий | Высокий |
| Точный контроль компоновки | Полный | Ограничено по конструкции |
| Где живет | Веб-страницы, вывод WYSIWYG | README, документы, заметки, статические сайты |
| Кривая обучения | Крутой | минуты |
Markdown намеренно меняет управление компоновкой для простоты, поэтому он выигрывает для контента, который вы пишете, просматриваете и перемещаетесь, и проигрывает, когда вам нужно представление на уровне пикселей. Преобразуйте HTML в Markdown, когда вы ' захватываете или переносите содержащийся; сохраните HTML, когда вы 'создаете а страница. А когда вам нужно пойти другим путем - Уменьшение в HTML для поля CMS или шаблона электронной почты - Markdown в HTML-конвертер является зеркальным отражением этого инструмента и имеет одни и те же соглашения, поэтому два варианта туда и обратно чисто подходят для общих структур.
Где это вписывается в рабочий процесс контента
Преобразование формата редко представляет собой всю работу; it's один шаг. После того, как я преобразую статью в Markdown I' обычно запускаю текст через a счетчик слов чтобы проверить длину по цели и если в источнике были объекты HTML, которым необходимо кодировать обратно для какого-либо другого пункта назначения, Кодер/декодер сущностей HTML обрабатывает обратное. Когда I'm очищает рукописный HTML перед преобразованием, a Минификатор HTML сначала снимает шум. Эти небольшие инструменты объединяются в повторяемый конвейер, и в этом вся идея того, как я думаю о наборе инструментов на основе браузера - я изложил эту философию в Руководство по набору инструментов для разработчиков веб-разработчика И более широкая Руководство по инструментам кодирования, йо-
Распространенные ошибки при преобразовании HTML в Markdown
Копирование вставленного визуализированного текста вместо преобразования HTML. Вы теряете ссылки, заголовки, и списки - всю структуру Преобразуйте фактическую разметку.
Игнорирование класса кодового языка. Если ваши огороженные блоки выходят без языка и выделяют don't, конвертер отбрасывает class="language-x" подсказка. Хороший читает это.
Предполагая, что CommonMark и GFM одинаковы. Таблицы и зачеркивания являются расширениями Markdown со вкусом GitHub, а не основной CommonMark. Если ваш пункт назначения строгий CommonMark, таблица выиграна и #39;t рендеринг - конвертируйте с выключенным GFM и обрабатывайте таблицы другим способом.
Доверие конвертеру, который загружает ваш контент. Множество "free" онлайн конвертеры POST ваш HTML на сервер. Для чего-либо неопубликованного или внутреннего, что 's утечка. использовать клиентский инструмент.
часто задаваемые вопросы
Как преобразовать html в markdown?
Вставьте свой HTML в редактор, и Markdown появится немедленно - нет файла для загрузки и нет кнопки преобразования для нажатия. Если хотите, отрегулируйте стиль пули или обработку ссылок, затем скопируйте Markdown или загрузите его в виде файла.md.
конвертер обрабатывает таблицы?
Да. С включенной разметкой со вкусом GitHub, HTML превращается в таблицу трубок Markdown: первая строка становится заголовком, вставляется разделительная строка, а остальные строки становятся телом. Символы трубок внутри ячеек экранируются, чтобы они не разбивали таблицу.
Что происходит со ссылками и изображениями?
Якоря становятся [текст ссылки](href) и образы становятся , сохраняя атрибут title, когда присутствует. если вы выключили & quot;держите ссылки& quot; текст привязки сохраняется, но URL-адрес отбрасывается, и выключить & quot;держать изображения& quot; удаляет изображения полностью - полезно, когда вам нужна только проза.
Сохраняются ли блоки кода и встроенный код?
Да. А block becomes a fenced code block, and if the code element carries a class like "language-js" that language is added to the fence. Inline spans are wrapped in backticks, and the code text itself is never escaped or reformatted, so snippets stay exactly as written.
Will it work on messy HTML copied from a website?
That is what it is built for. The parser is tolerant of unclosed tags, uppercase element names, unquoted attributes and stray comments, and it strips