markdown-it-task-lists-ts

A TypeScript-first markdown-it plugin that converts GitHub-style task lists to HTML checkboxes. Built with type safety and customization in mind.

Features

• Full TypeScript support with comprehensive type definitions
• Customizable CSS classes for all elements
• Support for nested task lists
• Configurable checkbox behavior (enabled/disabled)
• Accessible HTML output with proper labeling
• Zero dependencies (except for markdown-it peer dependency)

Installation

npm install markdown-it-task-lists-ts
# or
yarn add markdown-it-task-lists-ts

Usage

import MarkdownIt from 'markdown-it';
import taskLists, { type TaskListOptions } from 'markdown-it-task-lists-ts';

const md = new MarkdownIt();

// Basic usage with default options
md.use(taskLists);

// Usage with custom options
md.use(taskLists, {
  enabled: true,           // Enable checkbox interaction
  label: true,            // Wrap checkboxes in labels
  labelAfter: false,      // Place label before checkbox
  listClass: 'todo-list', // Custom class for ul elements
  itemClass: 'todo-item', // Custom class for li elements
  checkboxClass: 'todo-checkbox', // Custom class for input elements
  labelClass: 'todo-label',        // Custom class for label elements
  tiptapCompatible: true // Output HTML compatible with Tiptap's task list extension
});

// Convert markdown to HTML
const markdown = `
- [ ] Unchecked task
- [x] Checked task
  - [ ] Nested task
`;

const html = md.render(markdown);

Output HTML

The plugin generates semantic HTML with proper ARIA attributes and customizable classes:

<ul class="contains-task-list">
  <li class="task-list-item">
    <label class="task-list-item-label" for="task-item-1">
      <input class="task-list-item-checkbox" type="checkbox" id="task-item-1">
      Unchecked task
    </label>
  </li>
  <li class="task-list-item">
    <label class="task-list-item-label" for="task-item-2">
      <input class="task-list-item-checkbox" type="checkbox" checked id="task-item-2">
      Checked task
    </label>
    <ul class="contains-task-list">
      <li class="task-list-item">
        <label class="task-list-item-label" for="task-item-3">
          <input class="task-list-item-checkbox" type="checkbox" id="task-item-3">
          Nested task
        </label>
      </li>
    </ul>
  </li>
</ul>

Options

Option	Type	Default	Description
enabled	boolean	false	When true, checkboxes are interactive. When false, they have the disabled attribute.
label	boolean	true	When true, wraps checkboxes in label elements for better accessibility and UX.
labelAfter	boolean	false	When true, places the label after the checkbox instead of before.
listClass	string	'contains-task-list'	CSS class for the ul element containing task items.
itemClass	string	'task-list-item'	CSS class for the li elements containing tasks.
checkboxClass	string	'task-list-item-checkbox'	CSS class for the checkbox input elements.
labelClass	string	'task-list-item-label'	CSS class for the label elements (when label option is true).
tiptapCompatible	boolean	false	Whether to output HTML compatible with Tiptap's task list extension

Tiptap Compatibility

When tiptapCompatible is set to true, the plugin will output HTML that is compatible with Tiptap's task list extension:

<ul data-type="taskList">
  <li data-type="taskItem" data-checked="false">Unchecked task</li>
  <li data-type="taskItem" data-checked="true">Checked task</li>
</ul>

This is useful when using the plugin with Tiptap's TaskList and TaskItem extensions.

Example:

import MarkdownIt from 'markdown-it';
import taskLists, { type TaskListOptions } from 'markdown-it-task-lists-ts';

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

Styling

The plugin provides default classes that you can style, or you can specify your own classes through the options:

/* Default styling */
.contains-task-list {
  list-style-type: none;
  padding-left: 0;
}

.task-list-item {
  display: flex;
  align-items: center;
  gap: 0.5rem;
}

.task-list-item-checkbox {
  margin: 0;
}

.task-list-item-label {
  cursor: pointer;
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

MIT License - see the LICENSE file for details.