Списки задач

Markdown-it — это мощная библиотека для парсинга Markdown в JavaScript, предоставляющая гибкие возможности расширения и настройки синтаксиса. Одной из востребованных функций является поддержка списков задач (task lists), которые позволяют создавать интерактивные или просто визуально структурированные контрольные списки.

Поддержка списков задач

Markdown по умолчанию не поддерживает нативный синтаксис списков задач. Однако Markdown-it позволяет расширять стандартные возможности через плагины. Наиболее часто используется плагин markdown-it-task-lists, который добавляет синтаксис:

- [ ] Задача без отметки
- [x] Выполненная задача

Каждый элемент списка начинается с - или *, затем идёт пробел и конструкция [ ] для невыполненной задачи или [x] для выполненной.

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

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

npm install markdown-it markdown-it-task-lists

Затем подключение в коде JavaScript выглядит следующим образом:

const MarkdownIt = require('markdown-it');
const markdownItTaskLists = require('markdown-it-task-lists');

const md = new MarkdownIt()
  .use(markdownItTaskLists, { enabled: true, label: true });

Параметры плагина:

  • enabled — включение функциональности плагина (true/false).
  • label — поддержка добавления HTML-атрибутов <label> для чекбоксов, что позволяет использовать их с формами.

Синтаксис и правила форматирования

  1. Начало строки: элемент списка задачи начинается с символа - или * с последующим пробелом.
  2. Метка задачи: [ ] или [x] сразу после пробела.
  3. Описание задачи: текст после метки. Пробел после закрывающей скобки обязателен.
  4. Вложенные задачи: поддерживаются через стандартное Markdown-вложение списков с двумя или более пробелами перед маркером подсписка:
- [ ] Главная задача
  - [x] Подзадача выполнена
  - [ ] Подзадача невыполнена

В HTML это преобразуется в:

<ul class="task-list">
  <li class="task-list-item"><input type="checkbox" disabled> Главная задача
    <ul>
      <li class="task-list-item"><input type="checkbox" checked disabled> Подзадача выполнена</li>
      <li class="task-list-item"><input type="checkbox" disabled> Подзадача невыполнена</li>
    </ul>
  </li>
</ul>

Настройка рендеринга чекбоксов

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

const md = new MarkdownIt()
  .use(markdownItTaskLists, {
    enabled: true,
    label: true,
    ulClass: 'custom-task-list',
    liClass: 'custom-task-list-item'
  });
  • ulClass и liClass позволяют задавать CSS-классы для <ul> и <li> соответственно, что упрощает кастомное оформление.
  • Чекбоксы можно сделать активными, убрав disabled, если планируется взаимодействие через JavaScript.

Взаимодействие с CSS

Списки задач обычно оформляются через стили, чтобы визуально отличать выполненные и невыполненные элементы:

.custom-task-list {
  list-style: none;
  padding-left: 0;
}

.custom-task-list-item input[type="checkbox"] {
  margin-right: 0.5em;
}

.custom-task-list-item input[type="checkbox"]:checked + span {
  text-decoration: line-through;
  color: gray;
}

HTML можно дополнить <span> для текста задачи, если необходимо точное позиционирование стилизации.

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

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

- [ ] Основная задача
  - Обычный подпункт
  - [x] Завершённая подзадача

При рендеринге такой список сохраняет вложенность <ul> и <li>, автоматически добавляя чекбоксы только к элементам с [ ] или [x].

Преимущества использования Markdown-it для списков задач

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

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

Оглавление