micromark-extension-gfm-task-list-item

micromark extension to support GFM task list items.

Contents

• What is this?
• When to use this
• Install
• Use
• API
  • gfmTaskListItem
  • gfmTaskListItemHtml
• Authoring
• HTML
• CSS
• Syntax
• Types
• Compatibility
• Security
• Related
• Contribute
• License

What is this?

This package contains extensions that add support for tasklists enabled by GFM to micromark. It matches how task list items work on github.com.

When to use this

These tools are all low-level. In many cases, you want to use remark-gfm with remark instead.

Even when you want to use micromark, you likely want to use micromark-extension-gfm to support all GFM features. That extension includes this extension.

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

Install

This package is ESM only. In Node.js (version 12.20+, 14.14+, 16.0+, or 18.0+), install with npm:

npm install micromark-extension-gfm-task-list-item

In Deno with esm.sh:

import {gfmTaskListItem, gfmTaskListItemHtml} from 'https://esm.sh/micromark-extension-gfm-task-list-item@1'

In browsers with esm.sh:

<script type="module">
  import {gfmTaskListItem, gfmTaskListItemHtml} from 'https://esm.sh/micromark-extension-gfm-task-list-item@1?bundle'
</script>

Use

import {micromark} from 'micromark'
import {
  gfmTaskListItem,
  gfmTaskListItemHtml
} from 'micromark-extension-gfm-task-list-item'

const output = micromark('* [x] a\n* [ ] b', {
  extensions: [gfmTaskListItem],
  htmlExtensions: [gfmTaskListItemHtml]
})

console.log(output)

Yields:

<ul>
<li><input checked="" disabled="" type="checkbox"> a</li>
<li><input disabled="" type="checkbox"> b</li>
</ul>

API

This package exports the identifiers gfmTaskListItem and gfmTaskListItemHtml. There is no default export.

The export map supports the endorsed development condition. Run node --conditions development module.js to get instrumented dev code. Without this condition, production code is loaded.

gfmTaskListItem

Syntax extension for micromark (passed in extensions).

gfmTaskListItemHtml

HTML extension for micromark (passed in htmlExtensions).

Authoring

When authoring markdown with task lists, it’s recommended to use a lowercase x (instead of an uppercase one) for checked items and a space (instead of a tab or a line ending) for unchecked items.

HTML

GFM task list items relate to the <input> element in HTML. See § 4.10.5.1.15 Checkbox state (type=checkbox) in the HTML spec for more info. The structure for unchecked and checked items looks as follows:

<!--…-->
<li><input type="checkbox" disabled="" /> foo</li>
<li><input type="checkbox" disabled="" checked="" /> bar</li>
<!--…-->

CSS

GitHub itself uses slightly different markup for task list items than they define in their spec. When following the spec, as this extension does, only inputs are added. They can be styled with the following CSS:

input[type="checkbox"] {
  margin: 0 .2em .25em -1.6em;
  vertical-align: middle;
}

input[type="checkbox"]:dir(rtl) {
  margin: 0 -1.6em .25em .2em;
}

For the complete actual CSS see sindresorhus/github-markdown-css.

Syntax

Task lists form with, roughly, the following BNF:

; Note: task list items form only in the first child, after definitions, of a
; list, if that child is a paragraph.
; Restriction: must be follow by `whitespace` (after trimming).
task_list_item ::= '[' ( checked | unchecked ) ']'
checked ::= 'x' | 'X'
unchecked ::= whitespace
whitespace ::= '\t' | '\r\n' | '\r' | '\n' | ' '

Types

This package is fully typed with TypeScript. It exports no additional types.

Compatibility

This package is at least compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, 16.0+, and 18.0+. It also works in Deno and modern browsers.

Security

This package is safe.

Related

• syntax-tree/mdast-util-gfm-task-list-item — support GFM task list items in mdast
• syntax-tree/mdast-util-gfm — support GFM in mdast
• remarkjs/remark-gfm — support GFM in remark

Contribute

See contributing.md in micromark/.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.

License

MIT © Titus Wormer