Базовый синтаксис преобразования

Для работы с библиотекой markdown-it необходимо сначала установить её через npm или yarn:

npm install markdown-it

или

yarn add markdown-it

После установки создаётся объект парсера:

const MarkdownIt = require('markdown-it');
const md = new MarkdownIt();

Объект md предоставляет метод .render(), который принимает строку с Markdown и возвращает HTML.

const result = md.render('# Заголовок\n\nТекст абзаца');
console.log(result);

Результатом будет строка:

<h1>Заголовок</h1>
<p>Текст абзаца</p>

Основные элементы синтаксиса Markdown

Заголовки

Markdown-it поддерживает оба типа заголовков:

  • ATX-заголовки с символами #:
# H1
## H2
### H3
  • Setext-заголовки с подчеркиванием:
Заголовок H1
============

Заголовок H2
------------

При преобразовании они становятся соответствующими тегам <h1>–<h6>.

Абзацы и разрывы строк

Обычный текст разделяется пустой строкой:

Это первый абзац.

Это второй абзац.

Markdown-it превращает это в:

<p>Это первый абзац.</p>
<p>Это второй абзац.</p>

Для жёсткого разрыва строки используется двойной пробел перед переводом строки:

Строка с разрывом  
Следующая строка

Преобразуется в:

<p>Строка с разрывом<br>
Следующая строка</p>

Списки

Поддерживаются ненумерованные и нумерованные списки.

  • Ненумерованные:
- Пункт 1
- Пункт 2
  - Подпункт
* Альтернативный маркер

Результат:

<ul>
<li>Пункт 1</li>
<li>Пункт 2
  <ul>
    <li>Подпункт</li>
  </ul>
</li>
<li>Альтернативный маркер</li>
</ul>
  • Нумерованные:
1. Первый
2. Второй
3. Третий

Результат:

<ol>
<li>Первый</li>
<li>Второй</li>
<li>Третий</li>
</ol>

Markdown-it корректно поддерживает вложенные списки и их смешанные типы.

Форматирование текста

  • Жирный текст:
**Жирный** или __Жирный__

Результат:

<strong>Жирный</strong>
  • Курсив:
*Курсив* или _Курсив_

Результат:

<em>Курсив</em>
  • Зачёркнутый текст:
~~Зачёркнуто~~

Результат:

<s>Зачёркнуто</s>
  • Комбинация стилей:
**Жирный и *курсив***

Результат:

<strong>Жирный и <em>курсив</em></strong>

Markdown-it умеет корректно обрабатывать вложенные и пересекающиеся стили.

Ссылки и изображения

  • Ссылки стандартного вида:
[Текст ссылки](https://example.com)

Результат:

<a href="https://example.com">Текст ссылки</a>
  • Ссылки с заголовком:
[Текст ссылки](https://example.com "Заголовок")

Результат:

<a href="https://example.com" title="Заголовок">Текст ссылки</a>
  • Изображения:
![Alt текст](https://example.com/image.png "Заголовок изображения")

Результат:

<img src="https://example.com/image.png" alt="Alt текст" title="Заголовок изображения">

Цитаты

Markdown-it поддерживает блочные цитаты:

> Это цитата.
> 
> С новой строки.

Результат:

<blockquote>
<p>Это цитата.</p>
<p>С новой строки.</p>
</blockquote>

Код

  • Встроенный код:
Используем `код` внутри строки.

Результат:

<p>Используем <code>код</code> внутри строки.</p>
  • Блочный код с отступом или тройными обратными кавычками:
```javascript
console.log("Hello, world!");

Результат:

```html
<pre><code class="language-javascript">console.log("Hello, world!");
</code></pre>

Markdown-it поддерживает подсветку синтаксиса через плагины.

Горизонтальная линия

---
***
___

Все три варианта создают:

<hr>

Таблицы

Markdown-it поддерживает стандартные таблицы GitHub Flavored Markdown:

| Имя  | Возраст |
|------|--------|
| Иван | 25     |
| Анна | 30     |

Результат:

<table>
<thead>
<tr>
<th>Имя</th>
<th>Возраст</th>
</tr>
</thead>
<tbody>
<tr>
<td>Иван</td>
<td>25</td>
</tr>
<tr>
<td>Анна</td>
<td>30</td>
</tr>
</tbody>
</table>

Выравнивание колонок поддерживается с помощью двоеточий:

| Левый | Центр | Правый |
|:------|:----:|------:|
| A     | B    | C    |

Настройки и расширения

Markdown-it позволяет гибко настраивать поведение через опции при создании объекта:

const md = new MarkdownIt({
  html: true,        // Разрешает HTML в Markdown
  linkify: true,     // Превращает URL в ссылки
  typographer: true  // Использует типографские символы
});

Подключение плагинов расширяет функционал:

const markdownItFootnote = require('markdown-it-footnote');
md.use(markdownItFootnote);

После этого можно использовать сноски в Markdown:

Текст с сноской.[^1]

[^1]: Это сама сноска.

Прочие возможности

  • Автоматическое создание якорей для заголовков через плагины.
  • Поддержка чекбоксов в списках.
  • Интеграция с подсветкой синтаксиса кода через highlight.js или Prism.
  • Настройка рендереров для кастомного вывода HTML.

Markdown-it обеспечивает строгую совместимость с CommonMark, расширяемость через плагины и высокую производительность, что делает его подходящим инструментом для сложных систем рендеринга Markdown в веб-приложениях.

Оглавление