nikitalogos 19 июн 2022 в 17:52

Как я Markdown парсер выбирал

18 мин

25K

JavaScript*HTML*Usability*Лайфхаки для гиков

Вступление

Я обожаю Markdown. Это мощный, но вместе с тем лаконичный язык разметки. В его основе лежит концепция разделения данных и представления, что делает его очень удобным в ряде применений, например в системах контроля версий. Поэтому, например, Markdown является стандартом для документации на GitHub.

Markdown широко распространен в вебе как язык разметки для текстовых редакторов: на сайтах для ведения блогов, в вики проектах и т. д. Я сам ежедневно использую Markdown, и не только в разработке ПО, но и для ведения заметок. Я использую программу Obsidian: ide-подобный текстовый редактор Markdown для управления базой знаний.

Вообще говоря, Obsidian - одна из лучших программ для ведения заметок. Если вы еще не слышали о ней или о принципе zettelkasten, то, возможно, вам стоит заглянуть сюда и сюда.

Недавно я решил создать свой сайт, и мне понадобилось выбрать язык для разметки статей. Разумеется, я выбрал Markdown. Оставалось только определиться со всем остальным стеком.

Поискав готовые решения, я наткнулся на jekyll - генератор статических сайтов на основе Markdown. Он выглядел неплохим решением для минималистов, но, на мой взгляд, имел слишком много ограничений. В итоге я решил остаться на своем любимом фреймворке vue.js, а для конвертации Markdown в HTML использовать библиотеку. И вот тут началось самое интересное...

Выбор инструмента

Благодаря открытости, сравнительной простоте и популярности Markdown среди разработчиков, существует несколько десятков его реализаций на различных языках программирования. Далеко не полный список реализаций можно посмотреть здесь.

Когда я увидел это множество вариантов, первой мыслью было написать все самому с нуля ~~и пальцы сами потянулись к клавиатуре~~, но я мужественно пересилил себя. Вместо этого я решил сравнить парсеры и выбрать лучший.

Конечно, для рендеринга статических страниц можно было бы использовать реализацию на любом языке, но я решил остановиться на pure-JavaScript решениях для большей гибкости.
Так у меня осталось 9 кандидатов:

Для сравнения парсеров я составил такой список параметров:

лицензия
инфраструктура
1. документация
2. наличие демо
3. живое коммьюнити
поддержка определенного подмножества синтаксиса 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)
текстовые блоки
- перевод строки
цитаты (>)
1. вложенные цитаты
блоки кода (a = b)
- эскейпинг спецсимволов
- подсветка синтаксиса
списки
1. нумерованный (1.)
2. маркированный (-)
3. смешанный
выделение текста
1. курсив (*text*)
2. жирный (**text**)
3. жирный курсив (***text***)
4. подчеркнутый (text)
5. зачеркнутый (~~)
6. выделение цветом (==)
7. однострочный код (code)
8. подстрочный регистр (_a)
9. надстрочный регистр (^a)
ссылки
1. внешние (в интернет)
2. внутренние (к заголовкам)
медиа
1. изображения
2. эмодзи
таблицы
другое
1. эскейпинг спецсимволов
2. разделительная полоса (---)
html
- отрисовка html
- сохранение html "как есть"

Для тестирования парсеров я составил текст с примерами всей необходимой разметки:

Тестовый текст в формате Markdown:

# 1. Headers

# h1
## h2
### h3
#### h4
##### h5
###### h6

# 2. Text blocks

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 break
Text after line break

# 3. Quotes
> quote

>quote
> > nested quote
> - list in quote

# 4. Code blocks

```
untyped code block
```

```
escaped chars in code:
\```
```

```js
// js code
let a = 0
```

```python
# python code
print({"a":0})
```


# 5. lists

1. item-1
1. item-1
	1. item-1
	1. item-1
	- item
		- item

- item
	1. item-1
	2. item-2

# 6. Text decoration

*italic*

**bold**

***bold italic***

<u>underscored</u>

~~strikethrough~~

==highlighted==

`one line code`

A~subscript~

A^superscript^

# 7. Links

External link: [example.com](http://example.com)

Internal link: [link to h1](#h1)

# 8. Media

image: 

![Luke](https://habrastorage.org/webt/m_/it/vm/m_itvm5jqcvwj68gsk150c_caj0.jpeg)

emoji: ⛺  ?‚

# 9. Tables

| title | title2 |
| --- | ---- |
| data | data2 |
| more data | more data2 |
| even more data | even more data2 |

# 10. other
## 10.1 Escaped special symbols

\\
\`
\*
\_
\{ \}
\[ \]
\< \>
\( \)
\#
\+
\-
\.
\!
\|

## 10.2 Hline

---

---

---

# 11. html

<h2> H2 header </h2>


<p> # This markdown inside "p" tag should stay intact </p>

html image inside text block <img src="https://habrastorage.org/webt/m_/it/vm/m_itvm5jqcvwj68gsk150c_caj0.jpeg" style="width:200px; max-width:100%"> like that

**The first YouTube video "Me at the zoo". Embedded as an iframe**
<iframe style="width:560px; max-width:100%; height:315px" src="https://www.youtube.com/embed/jNQXAC9IVRw" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

Под спойлером ниже показано, как примерно должен рендериться в HTML описанный выше Markdown. Редактор статей на Хабре - это WYSIWIG, а не на Markdown, так что мне не удалось вставить в превью вложенную цитату и выделение текста цветом, однако остальная верстка должна быть в порядке.

Тестовый текст после конвертации в HTML

1. Headers

h1

h2

h3

h4

h5

h6

2. Text blocks

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 break
Text after line break

3. Quotes

quote

quote
nested quote
- list in quote

4. Code blocks

untyped code block

escaped chars in code:
```

// js code
let a = 0

# python code
print({"a":0})

5. lists

item-1
item-1
1. item-1
2. item-1
- item
  - item

item
1. item-1
2. item-2

6. Text decoration

italic

bold

bold italic

underscored

~~strikethrough~~

highlighted

one line code

A_subscript

A^superscript

7. Links

External link: example.com

Internal link: link to h1

8. Media

image:

emoji: ⛺ ?

9. Tables

title	title2
data	data2
more data	more data2
even more data	even more data2

10. other

10.1 Escaped special symbols

\
`
*
_
{ }
[ ]
< >
( )
#
+
-
.
!
|

10.2 Hline

11. html

H2 header

# 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). Для переноса нужно добавить два пробела в конце предыдущей строки, а новую начать на следующей строке.

Все из исследованных парсеров поддерживают эту функцию. На момент написания этой статьи я не знал об этом, и проверял в парсерах работоспособность переноса строки без отбивки из двух пробелов.

Мне отбивка пробелами кажется громоздкой и неудобной, а также не наглядной, ведь пробелы не отображаются в окне текстового редактора. Поэтому, я решил оставить проверку поддержки "переносов без отбивки" в статье, однако стоит воспринимать ее не как критичную фичу, а как приятный бонус.

commonmark.js

Что не работает:

перевод строки в текстовых блоках без отбивки
подсветка синтаксиса
выделение текста
1. зачеркнутый текст (приходится использовать <del>)
2. выделение цветом (приходится использовать <mark>)
3. подстрочный регистр
4. надстрочный регистр
таблицы

Немного неудобно, что в демо не работают переходы по ссылкам и не отрисовывается видео с YouTube, но сырой код HTML вроде верный

markdown-it

Все работает!

Можно включить по желанию:

перевод строки в текстовых блоках без отбивки
парсинг HTML

MarkdownDeep

Пожалуй, это самый косячный парсер Markdown из проверенных.

Что не работает:

перевод строки в текстовых блоках без отбивки
вложенная цитата интерферирует со списком
блоки кода
1. перевод строки в коде
2. подсветка синтаксиса
3. экранирование спец. символов
4. код почему-то дублируется: один раз как код и еще раз как текст
выделение текста
1. зачеркнутый текст
2. выделение цветом
3. подстрочный регистр
4. надстрочный регистр
iframe не работает

Баги с цитатами и блоками кода наглядно:

Что не так:

Текст - list in quote должен быть на следующей строке.
Весь текст из кодового блока идет в одну линию
значки ``` вылезли из кодового блока
текст из последнего блока повторяется - но уже как Markdown

Marked

Что не работает:

выделение текста
1. зачеркнутый текст
2. выделение цветом
3. подстрочный регистр
4. надстрочный регистр
таблицы

Можно включить по желанию:

перевод строки в текстовых блоках без отбивки
В демо синтаксис не подсвечивается. Однако, в конфиге есть поля "highlight": null и "langPrefix": "language-", указывающие на то, что как-то можно подключить подсветку синтаксиса. Правда, как это сделать, я не разбирался.

Не отрисовывается iframe с видео с YouTube, но сырой код HTML вроде верный.

remarkable

Все работает!

Можно включить по желанию:

перевод строки в текстовых блоках без отбивки
парсинг HTML

Проект очень сильно напоминает markdown-it, и неспроста (см. далее).

Showdown

Что не работает

Заголовки h5 и h6
перевод строки в текстовых блоках без отбивки
подсветка синтаксиса
выделение текста
1. выделение цветом
2. подстрочный регистр
3. надстрочный регистр
iframe не работает

С заголовками творится что-то странное: # транслируется в <h3>, ## в <h4> и т. д., а на заголовки 5 и 6 уровней тегов в HTML не остается, и они вставляются как простой текст. Это мешает их нормальной стилизации через CSS, а также приводит к багу с переносом на следующую строчку:

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

Судя по названию одной из галочек (simpleLineBreaks) перевод строки без отбивки должен работать, но у меня заставить его работать не получилось.

Bonus: Obsidian

В конце концов мне захотелось проверить и свой заметочник Obsidian, так как именно в нем я буду набирать статьи, которые затем пойдут на сайт. (Сами понимаете, где я набирал эту статью). К моей радости, он без труда справился со всем за исключением subscript-а и superscript-а. Но это простительно.

Bonus 2: PyCharm

Так как код сайта я пишу в PyCharm Community Edition, а у него есть встроенный просмотрщик Markdown, то... ну вы поняли!

Что не работает:

перевод строки в текстовых блоках без отбивки
выделение текста
1. выделение цветом
2. подстрочный регистр
3. надстрочный регистр
внутренние ссылки не работают внутри 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-js позволяет получить доступ к внутренним представлениям. Логика работы парсера такая:

Markdown -> парсинг -> дерево Markdown -> конвертация -> дерево HTML -> рендеринг -> HTML

Промежуточные представления хранятся в виде деревьев в формате JsonML и к ним можно получить доступ, вызывая функции парсинга, конвертации и рендеринга по очереди.

markdown-it

Пайплайн markdown-it состоит из парсера и рендерера.

Логика работы парсера описывается правилами, разбитыми на 3 группы: core, block и inline, что бы это ни значило. К существующим правилам можно дописывать свои.

Результатом работы парсера, вместо синтаксического дерева, является список токенов. Разработчики утверждают, что это сделано в целях упрощения алгоритма. И, хотя я не вижу ничего сложного в синтаксическом дереве, у плоской структуры должны быть свои преимущества.

Список токенов также можно модифицировать самостоятельно.

Список токенов передается в рендерер, который также можно расширять, добавляя свои правила.

Список доступных плагинов можно посмотреть здесь.

Marked

Логика работы Marked выглядит во многом похоже на остальные парсеры:

Markdown -> парсер -> синтаксическое дерево -> рендерер -> HTML

Правда, документация весьма вольно использует термины.

Парсер, который называется lexer, управляет набором правил, которые называются tokenizers. Можно как добавлять свои токенайзеры, так и модифицировать встроенные при помощи способа, напоминающего наследование, от встроенного объекта, содержащего функции-токенайзеры. При этом если функция в классе-наследнике вернет false, то будет выполнена функция из класса-родителя.

Можно определить функцию walkTokens, которая получает на вход синтаксическое дерево и его же должна отдать на выходе. Внутри можно провести любые модификации дерева.

Дерево отдается рендереру, который здесь parser, и он вызывает набор правил renderers. Как и в случае с парсером, можно и добавить свои функции, и отнаследоваться от существующих.

remark

Проект remark разработан с горячей любовью к декомпозиции. Remark использует парсер mdast-util-from-markdown, основанный на micromark, синтаксическое дерево mdast, являющееся реализацией unist для Markdown, рендерер mdast-util-to-markdown, а также обертку unified, чтобы склеить все это воедино. Фуууф!

В общем, разбираться во всем этом мне не очень хочется, тем более что логика работы особо не отличается от других парсеров.

С другой стороны, список плагинов у проекта весьма внушительный, так что, возможно, подход с микрорепозиториями имеет свои плюсы.

remarkable

Так как remarkable имеет общие корни с markdown-it (см. далее), то и логика работы у них схожая. Я не вдавался в подробности, так что за тонкостями реализации обращайтесь сюда.

Список плагинов можно посмотреть здесь.

Showdown

Похоже на то, что плагины Showdown представляют собой набор регулярных выражений и функций, последовательно модифицирующих весь текст.

Логику работы можно описать так:

Markdown -> regex/function 1 -> modified text -> regex/function 2 -> ... -> regex/function n -> HTML

Это довольно топорное решение, позволяющее очень просто создавать плагины. Однако, существенный минус такого подхода заключается в низкой производительности, поскольку каждая функция выполняется независимо и вынуждена заново парсить весь текст.

texts.js

Насколько я понял из документации, существует возможность получить доступ к внутреннему представлению 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
1. showdown = 1
2. commonmark.js ~ Marked ~ markdown-it = 3
markdown-it
1. commonmark.js = 1
2. markdown-it = 0.6 (1.28 в режиме CommonMark)
3. Marked = 1.3 (версия 0.3.5)
remarkable
1. commonmark.js = 1
2. remarkable = 1.88 (2.34 в режиме CommonMark)
3. Marked = 0.573 (тут старая и медленная версия - 0.3.2)
markdown
1. Showdown = 1
2. markdown-js = 0.61
3. 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, и мне предстояло его настроить.

Что есть из коробки

Я был приятно удивлен, что из коробки он поддерживает много полезных вещей. В том числе и тех, о которых я не знал:

Примечания: текст^[1]
Аббревиатуры: SQL

Но что оказалось действительно полезным, так это поддержка скрываемых блоков (спойлеров):

Нажмите, чтобы увидеть спойлер

Это спойлер!

Плагины

В списке плагинов есть много интересных.

Себе я установил remarkable-katex, основанный на библиотеке KaTeX для отрисовки формул LaTeX в вебе.

С ним можно делать такие вещи: $\frac{1}{2}$

И такие:

$\frac{1}{2}$

Если вы знаете японский, вам может пригодиться плагин remarkable-furigana, позволяющий отрисовывать над иероглифами их произношение.

Остальные плагины оставлю вам для самостоятельного изучения.

include

На сайте я храню исходники статей как файлы с текстом Markdown. Для удобства мне понадобилась возможность подключать содержимое одних файлов в другие.

Решать эту задачу средствами remarkable было бы неправильно, поэтому я написал функцию препроцессора, которая получает на вход путь к корневому файлу и рекурсивно вставляет в него необходимые подфайлы.

Например, для такой структуры файлов

posts/
- main.md
- parts/
  - part.md
  - part2.md

Это будет выглядеть примерно так:

// main.md
// absolute path
@include '/posts/parts/part.md'
// or relative path
@include './parts/part2.md'
!!!

// part.md
Hello

// part2.md
world

// output
Hello
world
!!!

Для тех, кто заинтересовался, вот код препроцессора:

async load_content_by_url(url) {
  let response = await fetch(url)
  let text = await response.text()
  return text
},

// str.replace() can't handle asynchronous requests, so we need a wrapper
// source: https://stackoverflow.com/questions/33631041/javascript-async-await-in-replace
async replaceAsync(str, regex, asyncFn) {
  const promises = [];
  str.replace(regex, (match, ...args) => {
    const promise = asyncFn(match, ...args);
    promises.push(promise);
  });
  const data = await Promise.all(promises);
  return str.replace(regex, () => data.shift());
},

async load_content_with_includes(url) {
  let file_dir = url.substring(0, url.lastIndexOf("/"))

  let text = await load_content_by_url(url)

  let out_text = await replaceAsync(
    text,
    /^@include\s*"(.+)"\s*$/mg, // regex for file includes
    async (...match) => {
      let url = match[1]
      url = url.replace(/^\./, file_dir) // if relative path -> make absolute

      let included_text = await load_content_with_includes(url) // get data by url
      return included_text
    }
  )
  return out_text
},

Стили

Для того, чтобы кастомизировать внешний вид статей, я создал свои стили для всех HTML компонентов, получаемых при генерации из Markdown.

Вот моя таблица стилей для тех, кому интересно:

<style lang="scss">
$site-defaults-color: #c8c3bc;

// 3.
$quote-border-color: #666;
// 4.
$code-border-color: #666;
$code-bg-color: rgba(255, 255, 255, 0.05);
// 6.
$highlight-color: $site-defaults-color;

$inline-code-color: rgb(3, 218, 197); // = #03dac5
$inline-code-bg-color: rgba(3, 218, 197, 0.1);
// 9.
$table-border-color: #666;
$table-stripe-color: rgba(255, 255, 255, 0.07);
// 10
$hline-color: $site-defaults-color;
//
$details-border-color: #666;

.md-wrapper {
  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~1. headers~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  @for $i from 1 through 6 {
    $sel: "h" + $i;
    #{$sel} {
      // nothing here
    }
  }
  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~2. text blocks~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~3. quotes~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  blockquote {
    margin: 15px 0;
    padding: 0 20px;

    border: 1px solid $quote-border-color;
    border-left: 5px solid $quote-border-color;
  }
  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~4. code blocks~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  code {
    font-family: Raleway;
  }
  pre {
    padding: 10px;
    margin-bottom: 10px;
    display: block;

    border: 1px solid $code-border-color;
    border-radius: 4px;
    background-color: $code-bg-color;

    overflow-x: auto;

    code {
      white-space: pre;
      word-break: normal;
      word-spacing: normal;
      word-wrap: normal;
    }
  }
  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~5. lists~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  ul {
    list-style-type: circle;
  }
  ol,
  ul {
    padding-inline-start: 25px;
  }
  li {
    padding: 3px 0;
  }
  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~6. text-decoration~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  mark {
    padding: 2px;
    background-color: $highlight-color;
  }
  code:not([class]) {
    padding: 2px 4px;
    font-size: 90%;
    color: $inline-code-color;
    background-color: $inline-code-bg-color;
  }

  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~7. links~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  @mixin link {
    color: #fff;
    font-weight: bold;
    text-decoration: none;
    cursor: pointer;
  }
  a {
    @include link;
  }
  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~8. images~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  img {
    max-width: 100%;
  }
  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~9. tables~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  table {
    width: 100%;
    max-width: 100%;
    margin: 15px 0;

    border-collapse: collapse;
    border-spacing: 0;

    text-align: left;

    display: block;
    overflow-x: auto;

    th,
    td {
      padding: 10px;
      border: 1px solid $table-border-color;
    }
    thead tr th {
      border-bottom: 2px solid $table-border-color;
    }

    tbody tr:nth-child(odd) {
      td,
      th {
        background-color: $table-stripe-color;
      }
    }
  }
  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~10.2 hline~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  hr {
    border: 0;
    height: 1px;
    width: 100%;

    background-image: linear-gradient(
      to right,
      rgba(0, 0, 0, 0),
      $hline-color,
      rgba(0, 0, 0, 0)
    );
  }

  // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~spoilers~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  @mixin user_select_none {
    -webkit-touch-callout: none;
    -webkit-user-select: none;
    -khtml-user-select: none;
    -moz-user-select: none;
    -ms-user-select: none;
    user-select: none;
  }

  details {
    background-color: rgba(255, 255, 255, 0.02);
    padding: 10px;
    border: dotted 1px $details-border-color;

    summary {
      @include link;
      @include user_select_none;
    }
  }
}
</style>

Для подсветки синтаксиса я использовал highlight.js. Пример подключения можно посмотреть на странице демо remarkable.

Заключение

Настала пора подводить итоги. Парсер для моего сайта выбран и настроен, чем я очень доволен.

Работая над статьей, я узнал много нового про Markdown и открыл его для себя с новой стороны.

Буду рад, если вам понравилось читать это небольшое исследование. До новых встреч, всем добра!

P. S.

В комментариях к этой статье мне накидали довольно много парсеров, которые не попали в нее. Так как я уже определился с выбором, я глянул на них лишь одним глазком, но в целом среди них есть довольно интересные. Например, markdown-wasm, основанный на web assembly, обещает быть в 2-2.5 раза быстрее лидеров данной статьи.

Также мне посоветовали Transformer - он умеет парсить Яндексовый диалект Markdown со своими плюшками (каты, табы, переменные и др.).

Теги:

Хабы: