Конвертировать Markdown в HTML

Фрагмент или страница — и что из этого нужно вам

Полезных вариантов результата два, и они не взаимозаменяемы. Фрагмент — это только сконвертированная разметка: заголовки, абзацы, списки, ссылки — без обёртки документа. Он нужен, когда результат пойдёт в шаблон, в поле CMS или на другую страницу. Полная страница добавляет doctype, head, объявление кодировки и таблицу стилей, поэтому открывается сама по себе и выглядит достойно. Если вставить полную страницу в CMS, получится документ внутри документа; если открыть фрагмент в браузере — текст без оформления.

Конвертация охватывает общепринятый расширенный набор Markdown: заголовки, выделение, списки, ссылки, изображения, цитаты, таблицы, блоки кода с подсветкой синтаксиса, списки задач, зачёркивание и сноски. Заголовки получают идентификаторы на основе своего текста, поэтому на них можно ссылаться напрямую — именно такие якорные ссылки делают длинную документацию удобной.

Сырой HTML внутри Markdown передаётся как есть — так предписывает спецификация, и к этому стоит относиться осознанно: Markdown-файл из ненадёжного источника может содержать тег script, и после конвертации страница будет нести этот скрипт. Никогда не отображайте Markdown от посторонних, не очистив потом HTML: конвертация — не барьер безопасности и никогда им не задумывалась.

Две вещи намеренно выводятся блоками кода, а не отрисовываются. Математическим формулам в нотации LaTeX нужна библиотека вёрстки, а диаграммам Mermaid — отрисовщик диаграмм; каждая из них — серьёзная зависимость, а неверно отрисованная формула хуже, чем просто видимый исходный код. Полная страница использует обычные системные шрифты, ничего не загружая, поэтому работает офлайн и немного по-разному выглядит в Windows, macOS и Linux.

Если нужно другое

Pandoc умеет то, что здесь не реализовано, и многое другое: pandoc in.md -o out.html --mathjax --standalone --toc правильно отрисовывает формулы, создаёт оглавление и принимает шаблон, чтобы результат совпадал с оформлением вашего сайта. Он также конвертирует в сорок с лишним других форматов и обратно — поэтому его стоит один раз установить.

Если нужен сайт, а не файл, используйте генератор, а не конвертируйте страницы по одной. Hugo, Eleventy, Jekyll и MkDocs превращают папку с Markdown в сайт с навигацией, поиском и единым оформлением и пересобирают его при каждом изменении исходников — а это и есть настоящая задача, как только документов больше одного.