mdast-util-gfm-task-list-item

mdast-util-gfm-task-list-item is part of the unified/syntax-tree ecosystem and provides two extensions that add GitHub Flavored Markdown task list item support to mdast, the markdown abstract syntax tree. One extension plugs into mdast-util-from-markdown to parse checkbox list items into list item nodes carrying a checked boolean, and the other plugs into mdast-util-to-markdown to serialize those nodes back to markdown.

It handles the [ ] and [x] checkbox markers at the start of list items, keeping the checked state on the tree so it survives a parse-and-stringify round trip. It is typically combined with micromark-extension-gfm-task-list-item for tokenization, and is one of the building blocks used by mdast-util-gfm and remark-gfm.

What You Get

• A from-markdown extension that parses [ ]/[x] checkboxes into list items with a checked field
• A to-markdown extension that serializes checked list items back to GFM markdown
• Preservation of the boolean checked state across parse and stringify
• Support for the standard GFM task list item syntax
• TypeScript type definitions for typed pipelines

Common Use Cases

• Adding task list support to a remark or unified markdown pipeline
• Parsing GFM checklists into an mdast tree for programmatic transformation
• Serializing generated task list nodes back into markdown documents
• Building custom GFM tooling alongside micromark-extension-gfm-task-list-item

Under The Hood

Architecture - The package is implemented in a compact lib/index.js (~141 lines) exporting two objects. The from-markdown extension registers handlers for micromark task list check token events and sets a checked boolean on the enclosing listItem node. The to-markdown extension provides a listItem handler that prepends the [ ] or [x] marker when a checked field is present, along with the necessary unsafe/escape rules.

Tech Stack - Pure ESM JavaScript typed via JSDoc with generated type declarations. It depends on sibling unist/mdast utilities and micromark helper packages, targeting modern Node.js and browsers.

Code Quality - The code adheres to the strict, uniform conventions of the syntax-tree project, with a dedicated test.js suite and full type coverage. The logic is small, declarative, and easy to audit.

API Design - The two-object, from/to naming mirrors every other mdast-util extension, so it integrates with no new concepts. It composes by being passed into from-markdown/to-markdown option arrays alongside its micromark counterpart.