Списки определений

Списки определений (Definition Lists) представляют собой особый тип структурирования информации, где каждому термину соответствует его определение. В Markdown это расширение не входит в стандарт, поэтому для работы с ним в библиотеке Markdown-it необходимо использовать плагин markdown-it-deflist.

Установка и подключение плагина

Для использования списков определений требуется подключение соответствующего плагина:

const MarkdownIt = require('markdown-it');
const deflist = require('markdown-it-deflist');

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

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

Синтаксис списков определений

Стандартная структура списка определений выглядит так:

Термин 1
: Определение термина 1

Термин 2
: Первое определение термина 2
: Второе определение термина 2

Особенности синтаксиса:

  • Термин всегда пишется в отдельной строке.
  • Определение начинается с двоеточия : и пробела.
  • Несколько определений одного термина могут следовать друг за другом с тем же форматированием.
  • Можно добавлять переносы строк внутри определения, отступив их хотя бы на один пробел или табуляцию.

Пример с многострочным определением:

Функция
: Блок кода, который выполняет определённое действие.
  Может принимать аргументы и возвращать значения.

Генерация HTML

Markdown-it с подключенным плагином преобразует список определений в HTML с тегами <dl>, <dt> и <dd>:

<dl>
  <dt>Термин 1</dt>
  <dd>Определение термина 1</dd>
  <dt>Термин 2</dt>
  <dd>Первое определение термина 2</dd>
  <dd>Второе определение термина 2</dd>
</dl>
  • <dl> — контейнер всего списка определений.
  • <dt> — отдельный термин.
  • <dd> — определение термина.

Вложенные элементы в определениях

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

  • Списки: нумерованные или маркированные
  • Код: как inline-код, так и блоки кода
  • Ссылки и форматирование текста (жирный, курсив)

Пример:

Фреймворк
: **JavaScript** библиотека для создания пользовательских интерфейсов.
  Содержит:
  - Компоненты
  - Директивы
  - События

HTML преобразуется следующим образом:

<dl>
  <dt>Фреймворк</dt>
  <dd>
    <p><strong>JavaScript</strong> библиотека для создания пользовательских интерфейсов.</p>
    <ul>
      <li>Компоненты</li>
      <li>Директивы</li>
      <li>События</li>
    </ul>
  </dd>
</dl>

Настройка поведения Markdown-it-deflist

Плагин поддерживает опции конфигурации для управления отступами и разметкой:

md.use(deflist, {
  multiline: true,  // Разрешает многострочные определения без дополнительного пробела
  marker: ':'       // Позволяет менять символ, используемый для начала определения
});
  • multiline: true — позволяет определению занимать несколько строк без необходимости строгого соблюдения пробелов.
  • marker — позволяет заменить стандартное : на другой символ, например ->, если требуется кастомная разметка.

Обработка ошибок и особенностей

  1. Пропущенный двоеточие: строка после термина без : не будет интерпретирована как определение.
  2. Отсутствие пустой строки между терминами: Markdown-it корректно обрабатывает последовательные термины, но рекомендуется разделять их пустой строкой для лучшей читаемости.
  3. Вложенные блоки: иногда при вложении сложных элементов, таких как таблицы или многоуровневые списки, требуется дополнительная пустая строка перед вложенным элементом, чтобы Markdown-it корректно его распознал.

Использование списков определений в учебных материалах

Списки определений идеально подходят для:

  • Глоссариев
  • Словарей терминов
  • Объяснения параметров функций или методов
  • Документации API с краткими описаниями полей и их значений

Примеры комбинации Markdown элементов

API Метод
: Получает данные с сервера.
  Параметры:
  1. `url` — адрес запроса
  2. `options` — объект настроек
  Возвращает `Promise` с результатом.

Результат HTML:

<dl>
  <dt>API Метод</dt>
  <dd>
    <p>Получает данные с сервера.</p>
    <ol>
      <li><code>url</code> — адрес запроса</li>
      <li><code>options</code> — объект настроек</li>
    </ol>
    <p>Возвращает <code>Promise</code> с результатом.</p>
  </dd>
</dl>

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

Оглавление