mdast extensions to parse and serialize GFM task list items.

• What is this?
• When to use this
• Install
• Use
• API
  • gfmTaskListItemFromMarkdown()
  • gfmTaskListItemToMarkdown()
• HTML
• Syntax
• Syntax tree
  • Nodes
  • Content model
• Types
• Compatibility
• Related
• Contribute
• License

This package contains two extensions that add support for GFM task list item syntax in markdown to mdast. These extensions plug into mdast-util-from-markdown (to support parsing task lists in markdown into a syntax tree) and mdast-util-to-markdown (to support serializing task lists in syntax trees to markdown).

You can use these extensions when you are working with mdast-util-from-markdown and mdast-util-to-markdown already.

When working with mdast-util-from-markdown, you must combine this package with micromark-extension-gfm-task-list-item.

When you don’t need a syntax tree, you can use micromark directly with micromark-extension-gfm-task-list-item.

When you are working with syntax trees and want all of GFM, use mdast-util-gfm instead.

All these packages are used remark-gfm, which focusses on making it easier to transform content by abstracting these internals away.

This utility does not handle how markdown is turned to HTML. That’s done by mdast-util-to-hast.

This package is ESM only. In Node.js (version 16+), install with npm:

npm install mdast-util-gfm-task-list-item

In Deno with esm.sh:

import {gfmTaskListItemFromMarkdown, gfmTaskListItemToMarkdown} from 'https://esm.sh/mdast-util-gfm-task-list-item@2'

In browsers with esm.sh:

<script type="module">
  import {gfmTaskListItemFromMarkdown, gfmTaskListItemToMarkdown} from 'https://esm.sh/mdast-util-gfm-task-list-item@2?bundle'
</script>

Say our document example.md contains:

* [ ] To do
* [x] Done

1. Mixed…
2. [x] …messages

…and our module example.js looks as follows:

import fs from 'node:fs/promises'
import {gfmTaskListItem} from 'micromark-extension-gfm-task-list-item'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {gfmTaskListItemFromMarkdown, gfmTaskListItemToMarkdown} from 'mdast-util-gfm-task-list-item'
import {toMarkdown} from 'mdast-util-to-markdown'

const doc = await fs.readFile('example.md')

const tree = fromMarkdown(doc, {
  extensions: [gfmTaskListItem()],
  mdastExtensions: [gfmTaskListItemFromMarkdown()]
})

console.log(tree)

const out = toMarkdown(tree, {extensions: [gfmTaskListItemToMarkdown()]})

console.log(out)

…now running node example.js yields (positional info removed for brevity):

{
 type: 'root',
 children: [
   {
     type: 'list',
     ordered: false,
     start: null,
     spread: false,
     children: [
       {
         type: 'listItem',
         spread: false,
         checked: false,
         children: [
           {type: 'paragraph', children: [{type: 'text', value: 'To do'}]}
         ]
       },
       {
         type: 'listItem',
         spread: false,
         checked: true,
         children: [
           {type: 'paragraph', children: [{type: 'text', value: 'Done'}]}
         ]
       }
     ]
   },
   {
     type: 'list',
     ordered: true,
     start: 1,
     spread: false,
     children: [
       {
         type: 'listItem',
         spread: false,
         checked: null,
         children: [
           {type: 'paragraph', children: [{type: 'text', value: 'Mixed…'}]}
         ]
       },
       {
         type: 'listItem',
         spread: false,
         checked: true,
         children: [
           {type: 'paragraph', children: [{type: 'text', value: '…messages'}]}
         ]
       }
     ]
   }
 ]
}

*   [ ] To do
*   [x] Done

1.  Mixed…
2.  [x] …messages

This package exports the identifiers gfmTaskListItemFromMarkdown and gfmTaskListItemToMarkdown. There is no default export.

Create an extension for mdast-util-from-markdown to enable GFM task list items in markdown.

Extension for mdast-util-from-markdown to enable GFM task list items (FromMarkdownExtension).

Create an extension for mdast-util-to-markdown to enable GFM task list items in markdown.

Extension for mdast-util-to-markdown to enable GFM task list items (ToMarkdownExtension).

This utility does not handle how markdown is turned to HTML. That’s done by mdast-util-to-hast.

See Syntax in micromark-extension-gfm-task-list-item.

The following interfaces are added to mdast by this utility.

interface ListItemGfm <: ListItem {
  checked: boolean?
}

In GFM, a checked field can be present. It represents whether the item is done (when true), not done (when false), or indeterminate or not applicable (when null or not present).

type ListContentGfm = ListItemGfm

This package is fully typed with TypeScript. It does not export additional types.

The ListItem type of the mdast nodes are exposed from @types/mdast.

Projects maintained by the unified collective are compatible with maintained versions of Node.js.

When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, mdast-util-gfm-task-list-item@^2, compatible with Node.js 16.

• remarkjs/remark-gfm — remark plugin to support GFM
• syntax-tree/mdast-util-gfm — same but all of GFM (autolink literals, footnotes, strikethrough, tables, tasklists)
• micromark/micromark-extension-gfm-task-list-item — micromark extension to parse GFM task list items

See contributing.md in syntax-tree/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

MIT © Titus Wormer