Плагин для сносок

Для работы со сносками в Markdown-it используется плагин markdown-it-footnote. Он позволяет добавлять в текст сноски и автоматически формировать ссылки на них и сноски внизу документа. Подключение выглядит следующим образом:

const MarkdownIt = require('markdown-it');
const markdownItFootnote = require('markdown-it-footnote');

const md = new MarkdownIt();
md.use(markdownItFootnote);

После подключения плагина синтаксис сносок становится доступным в стандартном Markdown:

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

[^1]: Содержимое сноски.

Этот код будет преобразован в HTML с корректными ссылками на сноски и их содержимое.

Синтаксис сносок

Объявление сносок осуществляется через квадратные скобки с символом ^ и идентификатором сноски. Идентификатор может состоять из букв, цифр и дефисов:

Пример сноски[^note-id].

[^note-id]: Это содержимое сноски.

Важные моменты:

  • Идентификатор сноски должен быть уникальным.
  • Сноска может содержать несколько абзацев и любые элементы Markdown, включая списки и кодовые блоки.
  • Порядок объявления сносок не обязательно совпадает с порядком их использования в тексте — Markdown-it автоматически нумерует их при рендеринге.

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

Содержимое сноски может включать любые Markdown-элементы:

Текст с многострочной сноской[^example].

[^example]: Первый абзац сноски.

    Второй абзац с отступом.

    - Список в сноске
    - С поддержкой Markdown

При рендеринге это преобразуется в HTML с <sup> для ссылки на сноску и отдельным блоком <section class="footnotes"> для самой сноски.

Настройка нумерации и оформления

По умолчанию сноски нумеруются в порядке их появления. Для кастомизации HTML можно использовать события renderer rules:

md.renderer.rules.footnote_caption = function(tokens, idx, options, env, slf) {
  let n = Number(tokens[idx].meta.id + 1).toString();
  return n;
};

Эта функция позволяет изменить отображаемый номер сноски. Также можно переопределять шаблоны для ссылок на сноски и их обратные ссылки.

Обработка вложенных сносок и ссылок

Markdown-it поддерживает вложенные элементы внутри сносок, включая другие ссылки или форматирование текста:

Сложная сноска[^complex].

[^complex]: Сноска с **жирным текстом**, [ссылкой](https://example.com) и `кодом`.

Сноска будет корректно отрендерена с сохранением всех вложенных Markdown-элементов. Важно помнить, что плагин не поддерживает вложенные сноски (сноска внутри другой сноски).

Совместная работа с другими плагинами

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

const markdownItEmoji = require('markdown-it-emoji');
const markdownItAnchor = require('markdown-it-anchor');

md.use(markdownItFootnote)
  .use(markdownItEmoji)
  .use(markdownItAnchor);

При этом Markdown-it гарантирует корректную обработку сносок, даже если текст сноски содержит emoji или якоря.

Настройка CSS и стилизация

Стилизовать сноски можно через стандартные CSS-классы:

  • .footnotes — контейнер всех сносок.
  • .footnote-item — отдельная сноска.
  • .footnote-ref — ссылка на сноску.

Пример CSS:

.footnotes {
  font-size: 0.9em;
  border-top: 1px solid #ccc;
  margin-top: 1em;
  padding-top: 0.5em;
}

.footnote-item {
  margin-bottom: 0.5em;
}

.footnote-ref {
  text-decoration: none;
  color: #007bff;
}

Таким образом, плагин markdown-it-footnote позволяет интегрировать сноски в любые документы Markdown с полной поддержкой HTML-рендеринга и гибкой кастомизацией.

Полезные практики при работе со сносками

  • Использовать короткие и понятные идентификаторы для удобного редактирования.
  • Следить за последовательностью и уникальностью идентификаторов, чтобы избежать конфликтов.
  • Если сноски содержат большие блоки текста, форматировать их с отступами для сохранения читаемости исходного Markdown.
  • Для сложных документов создавать отдельный CSS-файл для сносок, чтобы не смешивать стили с основным текстом.

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

Оглавление