Я обожаю Markdown. Это мощный, но вместе с тем лаконичный язык разметки. В его основе лежит концепция разделения данных и представления, что делает его очень удобным в ряде применений, например в системах контроля версий. Поэтому, например, Markdown является стандартом для документации на GitHub. Markdown широко распространен в вебе как язык разметки для текстовых редакторов: на сайтах для ведения блогов, в вики проектах и т. д. Я сам ежедневно использую Markdown, и не только в разработке ПО, но и для ведения заметок. Я использую программу Obsidian: ide-подобный текстовый редактор Markdown для управления базой знаний. Вообще говоря, Obsidian - одна из лучших программ для ведения заметок. Если вы еще не слышали о ней или о принципе zettelkasten, то, возможно, вам стоит заглянуть сюда и сюда. Недавно я решил создать свой сайт, и мне понадобилось выбрать язык для разметки статей. Разумеется, я выбрал Markdown. Оставалось только определиться со всем остальным стеком. Поискав готовые решения, я наткнулся на jekyll - генератор статических сайтов на основе Markdown. Он выглядел неплохим решением для минималистов, но, на мой взгляд, имел слишком много ограничений. В итоге я решил остаться на своем любимом фреймворке vue.js, а для конвертации Markdown в HTML использовать библиотеку. И вот тут началось самое интересное... Благодаря открытости, сравнительной простоте и популярности Markdown среди разработчиков, существует несколько десятков его реализаций на различных языках программирования. Далеко не полный список реализаций можно посмотреть здесь. Когда я увидел это множество вариантов, первой мыслью было написать все самому с нуля и пальцы сами потянулись к клавиатуре, но я мужественно пересилил себя. Вместо этого я решил сравнить парсеры и выбрать лучший. Конечно, для рендеринга статических страниц можно было бы использовать реализацию на любом языке, но я решил остановиться на pure-JavaScript решениях для большей гибкости.Так у меня осталось 9 кандидатов: commonmark.js markdown-js markdown-it MarkdownDeep - GitHub и сайт Marked remark remarkable Showdown texts.js Для сравнения парсеров я составил такой список параметров: лицензия инфраструктура документация наличие демо живое коммьюнити поддержка определенного подмножества синтаксиса Markdown возможность модифицировать логику работы парсера производительность Итак, приступим! Начнем с лицензии.Здесь все просто: Лицензия commonmark.js - 2-clause BSD, две зависимости, обе под MIT Лицензия markdown-js - MIT Лицензия markdown-it - MIT Лицензия MarkdownDeep - Apache 2.0 Лицензия Marked - MIT, ссылается на Джона Грубера, создателя языка Markdown, распространяющего его под лицензией 3-clause BSD, что довольно мило Лицензия remark - MIT Лицензия remarkable - MIT Лицензия Showdown - MIT Лицензия texts.js - Apache 2.0 Другими словами, все проекты распространяются под свободными лицензиями, чего и следовало ожидать. На документации останавливаться не будем: у всех проектов она имеется. С демо дела чуть хуже: Демо commonmark.js Демо markdown-js - отсутствует Демо markdown-it Демо MarkdownDeep Демо Marked Демо remark - отсутствует Демо remarkable Демо Showdown Демо texts.js - отсутствует Поддержку коммьюнити оценить сложно, не погрузившись в проект и не столкнувшись с трудностями. Косвенно проект можно оценить по числу звездочек на GitHub, но по этическим соображениям я не буду этого делать. Что касается активности, то: проект markdown-js в данный момент не поддерживается, последний коммит в 2019 году texts.js - последний коммит в 2013 году remarkable - последний коммит в сентябре 2021 (в целом не так уж давно) остальные проекты имеют коммиты в этом году, так что можно считать их активными. Пожалуй, это самая важная часть. Для начала я составил список необходимой мне разметки: заголовки (h1 - h6) текстовые блоки перевод строки цитаты (>) вложенные цитаты блоки кода (a = b) эскейпинг спецсимволов подсветка синтаксиса списки нумерованный (1.) маркированный (-) смешанный выделение текста курсив (*text*) жирный (**text**) жирный курсив (***text***) подчеркнутый (text) зачеркнутый (~~) выделение цветом (==) однострочный код (code) подстрочный регистр (a) надстрочный регистр (a) ссылки внешние (в интернет) внутренние (к заголовкам) медиа изображения эмодзи таблицы другое эскейпинг спецсимволов разделительная полоса (---) html отрисовка html сохранение html "как есть"  Для тестирования парсеров я составил текст с примерами всей необходимой разметки:  Под спойлером ниже показано, как примерно должен рендериться в HTML описанный выше Markdown. Редактор статей на Хабре - это WYSIWIG, а не на Markdown, так что мне не удалось вставить в превью вложенную цитату и выделение текста цветом, однако остальная верстка должна быть в порядке. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Text before line breakText after line break quote quote nested quote - list in quote item-1 item-1 item-1 item-1 item item item item-1 item-2 italic bold bold italic underscored strikethrough highlighted one line code Asubscript Asuperscript External link: example.com Internal link: link to h1 image: emoji: ⛺ 😂 title title2 data data2 more data more data2 even more data even more data2 \`*_{ }< >( )#+-.!| # This Markdown inside "p" tag should stay intact html image inside text block like that The first YouTube video "Me at the zoo". Embedded as an iframe  Разбираться с установкой всех парсеров мне не хотелось, поэтому я тестировал только те, у которых было демо. При желании вы можете протестировать остальные самостоятельно, используя тестовый текст выше (или любой другой). Итак, перейдем к результатам. Но сначала: Как верно заметили в коментариях, стандарт Markdown поддерживает функцию переноса строки в текстовом блоке (аналог тега <br> в HTML). Для переноса нужно добавить два пробела в конце предыдущей строки, а новую начать на следующей строке. Все из исследованных парсеров поддерживают эту функцию. На момент написания этой статьи я не знал об этом, и проверял в парсерах работоспособность переноса строки без отбивки из двух пробелов. Мне отбивка пробелами кажется громоздкой и неудобной, а также не наглядной, ведь пробелы не отображаются в окне текстового редактора. Поэтому, я решил оставить проверку поддержки "переносов без отбивки" в статье, однако стоит воспринимать ее не как критичную фичу, а как приятный бонус.  Что не работает: перевод строки в текстовых блоках без отбивки подсветка синтаксиса выделение текста зачеркнутый текст (приходится использовать <del>) выделение цветом (приходится использовать <mark>) подстрочный регистр надстрочный регистр таблицы Немного неудобно, что в демо не работают переходы по ссылкам и не отрисовывается видео с YouTube, но сырой код HTML вроде верный Все работает! Можно включить по желанию: перевод строки в текстовых блоках без отбивки парсинг HTML Пожалуй, это самый косячный парсер Markdown из проверенных. Что не работает: перевод строки в текстовых блоках без отбивки вложенная цитата интерферирует со списком блоки кода перевод строки в коде подсветка синтаксиса экранирование спец. символов код почему-то дублируется: один раз как код и еще раз как текст выделение текста зачеркнутый текст выделение цветом подстрочный регистр надстрочный регистр iframe не работает Баги с цитатами и блоками кода наглядно: Что не так: Текст - list in quote должен быть на следующей строке. Весь текст из кодового блока идет в одну линию значки ``` вылезли из кодового блока текст из последнего блока повторяется - но уже как Markdown Что не работает: выделение текста зачеркнутый текст выделение цветом подстрочный регистр надстрочный регистр таблицы Можно включить по желанию: перевод строки в текстовых блоках без отбивки В демо синтаксис не подсвечивается. Однако, в конфиге есть поля "highlight": null и "langPrefix": "language-", указывающие на то, что как-то можно подключить подсветку синтаксиса. Правда, как это сделать, я не разбирался. Не отрисовывается iframe с видео с YouTube, но сырой код HTML вроде верный. Все работает! Можно включить по желанию: перевод строки в текстовых блоках без отбивки парсинг HTML Проект очень сильно напоминает markdown-it, и неспроста (см. далее). Что не работает Заголовки h5 и h6 перевод строки в текстовых блоках без отбивки подсветка синтаксиса выделение текста выделение цветом подстрочный регистр надстрочный регистр iframe не работает С заголовками творится что-то странное: # транслируется в <h3>, ## в <h4> и т. д., а на заголовки 5 и 6 уровней тегов в HTML не остается, и они вставляются как простой текст. Это мешает их нормальной стилизации через CSS, а также приводит к багу с переносом на следующую строчку: В интерфейсе демо есть галочки для включения опций, но они не работают. При попытке нажать галочку страница перезагружается, а галочка не проставляется. Судя по названию одной из галочек (simpleLineBreaks) перевод строки без отбивки должен работать, но у меня заставить его работать не получилось. В конце концов мне захотелось проверить и свой заметочник Obsidian, так как именно в нем я буду набирать статьи, которые затем пойдут на сайт. (Сами понимаете, где я набирал эту статью). К моей радости, он без труда справился со всем за исключением subscript-а и superscript-а. Но это простительно. Так как код сайта я пишу в PyCharm Community Edition, а у него есть встроенный просмотрщик Markdown, то... ну вы поняли! Что не работает: перевод строки в текстовых блоках без отбивки выделение текста выделение цветом подстрочный регистр надстрочный регистр внутренние ссылки не работают внутри ide Эскейпинг символов почему-то отображает слэши перед символами, хотя должен скрывать iframe не работает Работает выборочно: подсветка синтаксиса доступна только для Python. Возможно, все дело в Community Edition, а в Enterprise Edition поддерживаются и другие языки, но я не проверял. На самом деле в ряде случаев отсутствие поддержки части синтаксиса (к примеру, выделения текста и таблиц) - это не баг, а фича, так как часть парсеров Markdown придерживается спецификации CommonMark. Другие парсеры, такие как remarkable, позволяют включать опцию "CommonMark" по желанию. Спецификация CommonMark нацелена на унификацию языка Markdown. Это может быть полезно, например, при необходимости переноса текста в Markdown между различными системами. Однако, мне для сайта требовался расширенный функционал, так что эти парсеры мне не подошли. Также в ряде парсеров теги HTML, признанные небезопасными (как <iframe>), не рендерятся намеренно. Это называется "санитайзинг HTML". Он полезен, например, если парсер Markdown используется для рендеринга пользовательского контента. Но, так как на моем сайте все статьи буду писать я, эта функция мне будет только мешать. В основном парсеры работают по следущему алгоритму: Markdown -> парсинг -> внутреннее представление -> рендеринг -> HTML Часть парсеров позволяет изменять логику своей работы. Парсер может давать доступ к функциям парсинга и рендеринга, либо позволять модифицировать внутреннее представление. Это дает возможность добавлять дополнительный функционал, либо модифицировать существующий. Такая расширяемость парсера открывает путь для создания плагинов сообществом. Я не смог найти упоминаний о расширяемости в документации следующих парсеров: commonmark.js MarkdownDeep Остальные рассмотрены ниже: markdown-js позволяет получить доступ к внутренним представлениям. Логика работы парсера такая: Markdown -> парсинг -> дерево Markdown -> конвертация -> дерево HTML -> рендеринг -> HTML Промежуточные представления хранятся в виде деревьев в формате JsonML и к ним можно получить доступ, вызывая функции парсинга, конвертации и рендеринга по очереди. Пайплайн markdown-it состоит из парсера и рендерера. Логика работы парсера описывается правилами, разбитыми на 3 группы: core, block и inline, что бы это ни значило. К существующим правилам можно дописывать свои. Результатом работы парсера, вместо синтаксического дерева, является список токенов. Разработчики утверждают, что это сделано в целях упрощения алгоритма. И, хотя я не вижу ничего сложного в синтаксическом дереве, у плоской структуры должны быть свои преимущества. Список токенов также можно модифицировать самостоятельно. Список токенов передается в рендерер, который также можно расширять, добавляя свои правила. Список доступных плагинов можно посмотреть здесь. Логика работы Marked выглядит во многом похоже на остальные парсеры: Markdown -> парсер -> синтаксическое дерево -> рендерер -> HTML Правда, документация весьма вольно использует термины. Парсер, который называется lexer, управляет набором правил, которые называются tokenizers. Можно как добавлять свои токенайзеры, так и модифицировать встроенные при помощи способа, напоминающего наследование, от встроенного объекта, содержащего функции-токенайзеры. При этом если функция в классе-наследнике вернет false, то будет выполнена функция из класса-родителя. Можно определить функцию walkTokens, которая получает на вход синтаксическое дерево и его же должна отдать на выходе. Внутри можно провести любые модификации дерева. Дерево отдается рендереру, который здесь parser, и он вызывает набор правил renderers. Как и в случае с парсером, можно и добавить свои функции, и отнаследоваться от существующих. Проект remark разработан с горячей любовью к декомпозиции. Remark использует парсер mdast-util-from-markdown, основанный на micromark, синтаксическое дерево mdast, являющееся реализацией unist для Markdown, рендерер mdast-util-to-markdown, а также обертку unified, чтобы склеить все это воедино. Фуууф! В общем, разбираться во всем этом мне не очень хочется, тем более что логика работы особо не отличается от других парсеров. С другой стороны, список плагинов у проекта весьма внушительный, так что, возможно, подход с микрорепозиториями имеет свои плюсы. Так как remarkable имеет общие корни с markdown-it (см. далее), то и логика работы у них схожая. Я не вдавался в подробности, так что за тонкостями реализации обращайтесь сюда. Список плагинов можно посмотреть здесь. Похоже на то, что плагины Showdown представляют собой набор регулярных выражений и функций, последовательно модифицирующих весь текст. Логику работы можно описать так: Markdown -> regex/function 1 -> modified text -> regex/function 2 -> ... -> regex/function n -> HTML Это довольно топорное решение, позволяющее очень просто создавать плагины. Однако, существенный минус такого подхода заключается в низкой производительности, поскольку каждая функция выполняется независимо и вынуждена заново парсить весь текст. Насколько я понял из документации, существует возможность получить доступ к внутреннему представлению texts.js, которое является кастомной реализацией JsonML под названием TextJSON. Интересно, что, хотя все рассмотренные парсеры имеют общие принципы работы, они сильно различаются в деталях реализаций. Мне нравится логика реализации markdown-js - она не слишком замороченная и удобная с точки зрения написания плагинов. К сожалению, markdown-js на данный момент не поддерживается, и поэтому я не буду его использовать. Логика реализаций markdown-it, remarkable и Marked неплоха, но документация смущает своей терминологией. Remark выглядит как самый хорошо документированный проект, но вместе с тем степень его декомпозиции кажется излишней. Плагины в Showdown устроены очень просто, но это достигается путем значительного снижения производительности. Про texts.js вообще трудно что-либо сказать по причине неполной документации. Итого, с точки зрения плагинов можно смело брать: markdown-it Marked remark remarkable Можно было бы провести бенчмаркинг самостоятельно, но гораздо проще найти существующие бенчмарки и сравнить их. Я нашел 4 бенчмарка: сommonmark.js benchmark - 2015 commonmark.js markdown-it Marked Showdown markdown-it benchmark - 2015 markdown-it Marked commonmark remarkable benchmark - 2014 remarkable Marked commonmark markdown-benchmark - 2015 markdown-js Marked showdown Я не нашел бенчмарков для: MarkdownDeep texts.js remark Все бенчмарки сделаны примерно в одно время, так что будем считать их примерно сопоставимыми. Исследования датируются 2014-2015 годами, но будем считать их действительными, так как если бы с тех пор разработчики сильно подняли производительность, это было бы отражено в readme проекта. Итого, имея эти бенчмарки, мы можем построить такой граф зависимостей: Цвета стрелок здесь совпадают с цветом автора бенчмарка. Производительность измеряется в операциях в секунду, то есть чем больше, тем лучше. Я посчитал относительную производительность по каждому из бенчмарков в отдельности: commonmark showdown = 1 commonmark.js ~ Marked ~ markdown-it = 3 markdown-it commonmark.js = 1 markdown-it = 0.6 (1.28 в режиме CommonMark) Marked = 1.3 (версия 0.3.5) remarkable commonmark.js = 1 remarkable = 1.88 (2.34 в режиме CommonMark) Marked = 0.573 (тут старая и медленная версия - 0.3.2) markdown Showdown = 1 markdown-js = 0.61 Marked = 2.99 Анализ бенчмарков: Видно, что в среднем commonmark.js, Marked и markdown-it быстрее, чем Showdown, в 3 раза. Данные бенчмарка 2 примерно подтверждают данные бенчмарка 1 По бенчмарку 3 remarkable быстрее commonmark.js в 2 раза, то есть быстрее Showdown в 6 раз. Это впечатляющий показатель, но так как он произведен разработчиком remarkable, ему нельзя слишком сильно доверять. Учитывая, что у remarkable и markdown-it одинаковые корни, можно предположить, что и производительность у них примерно одинаковая. По бенчмарку 4 markdown-js медленнее Showdown на 40% Теперь надо привести все это к общему знаменателю. Самым надежным выглядит бенчмарк 1, так что в качестве единицы возьму производительность Showdown. Итого получаем такую сравнительную таблицу: Парсер Производительность Источники оценки commonmark.js ~3 1 markdown-js ~0.6 4 markdown-it ~3 1 Marked ~3 1, 4 remarkable ~3 / ~6 моя догадка / 3 Showdown 1 - Результаты сравнения показывают, что по производительности markdown-js и Showdown катастрофически проигрывают остальным парсерам, в то время как остальные держатся примерно на одном уровне. Если верить бенчмарку от разработчика remarkable, то он быстрее всех с большим отрывом. Правда, я сомневаюсь в его достоверности. Было бы интересно посмотреть на производительность парсера remark. Возможно, в другой раз... Подводя итог, если вам важна производительность, вы можете смело выбирать: commonmark.js markdown-it Marked remarkable По результатам сравнения победили два парсера: markdown-it и remarkable. У этих проектов много общего, в том числе общие разработчки. Если посмотреть в историю версий проектов, то можно узнать много интересного. Так, первым появился проект remarkable. Через несколько месяцев возник markdown-it - скорее всего, как форк remarkable. С тех пор проекты развиваются параллельно. Оба проекта: имеют лицензию MIT предоставляют рабочее демо безупречно прошли тест на синтаксис дают широкие возможности к модификации своей логики работы имеют много готовых плагинов находятся в лидерах по производительности Я для себя выбрал remarkable, потому что у него в демо был пример кода и я смог быстро интегрировать его в свой проект. В целом я не нашел значительных отличий между этими двумя парсерами, так что рекомендую оба! Итак, я выбрал remarkable, и мне предстояло его настроить. Я был приятно удивлен, что из коробки он поддерживает много полезных вещей. В том числе и тех, о которых я не знал: Примечания: текст Аббревиатуры: SQL Но что оказалось действительно полезным, так это поддержка скрываемых блоков (спойлеров): Это спойлер! В списке плагинов есть много интересных. Себе я установил remarkable-katex, основанный на библиотеке KaTeX для отрисовки формул LaTeX в вебе. С ним можно делать такие вещи:  И такие: Если вы знаете японский, вам может пригодиться плагин remarkable-furigana, позволяющий отрисовывать над иероглифами их произношение. Остальные плагины оставлю вам для самостоятельного изучения. На сайте я храню исходники статей как файлы с текстом Markdown. Для удобства мне понадобилась возможность подключать содержимое одних файлов в другие. Решать эту задачу средствами remarkable было бы неправильно, поэтому я написал функцию препроцессора, которая получает на вход путь к корневому файлу и рекурсивно вставляет в него необходимые подфайлы. Например, для такой структуры файлов posts/ main.md parts/ part.md part2.md Это будет выглядеть примерно так:  Для того, чтобы кастомизировать внешний вид статей, я создал свои стили для всех HTML компонентов, получаемых при генерации из Markdown.  Для подсветки синтаксиса я использовал highlight.js. Пример подключения можно посмотреть на странице демо remarkable. Настала пора подводить итоги. Парсер для моего сайта выбран и настроен, чем я очень доволен. Работая над статьей, я узнал много нового про Markdown и открыл его для себя с новой стороны. Буду рад, если вам понравилось читать это небольшое исследование. До новых встреч, всем добра! В комментариях к этой статье мне накидали довольно много парсеров, которые не попали в нее. Так как я уже определился с выбором, я глянул на них лишь одним глазком, но в целом среди них есть довольно интересные. Например, markdown-wasm, основанный на web assembly, обещает быть в 2-2.5 раза быстрее лидеров данной статьи. Также мне посоветовали Transformer - он умеет парсить Яндексовый диалект Markdown со своими плюшками (каты, табы, переменные и др.). Разработчик ПО — Python, web