unified

Project: micromark/micromark-extension-gfm

Package: micromark-extension-gfm@2.0.1

  1. Dependents: 0
  2. micromark extension to support GFM (GitHub Flavored Markdown)
  1. unified 179
  2. markdown 151
  3. micromark 35
  4. gfm 20
  5. micromark-extension 17
  6. table 13
  7. github 10
  8. footnote 7
  9. strikethrough 6
  10. autolink 6
  11. tasklist 3
  12. tagfilter 3

micromark-extension-gfm

Build Coverage Downloads Size Sponsors Backers Chat

micromark extension to support GitHub flavored markdown (GFM).

Contents

What is this?

This package contains extensions that add support for all features enabled by GFM to micromark. It supports autolink literals, footnotes, strikethrough, tables, tagfilter, and tasklists.

When to use this

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

When you do want to use micromark, you likely want to use this to support all GFM features.

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

Alternatively, you can also use the underlying features separately:

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

In Deno with esm.sh:

import {gfm, gfmHtml} from 'https://esm.sh/micromark-extension-gfm@2'

In browsers with esm.sh:

<script type="module">
  import {gfm, gfmHtml} from 'https://esm.sh/micromark-extension-gfm@2?bundle'
</script>

Use

Say our document example.md contains:

# GFM

## Autolink literals

www.example.com, https://example.com, and contact@example.com.

## Footnote

A note[^1]

[^1]: Big note.

## Strikethrough

~one~ or ~~two~~ tildes.

## Table

| a | b  |  c |  d  |
| - | :- | -: | :-: |

## Tag filter

<plaintext>

## Tasklist

* [ ] to do
* [x] done

…and our module example.js looks as follows:

import fs from 'node:fs/promises'
import {micromark} from 'micromark'
import {gfm, gfmHtml} from 'micromark-extension-gfm'

const output = micromark(await fs.readFile('example.md'), {
  allowDangerousHtml: true,
  extensions: [gfm()],
  htmlExtensions: [gfmHtml()]
})

console.log(output)

…now running node example.js yields:

<h1>GFM</h1>
<h2>Autolink literals</h2>
<p><a href="http://www.example.com">www.example.com</a>, <a href="https://example.com">https://example.com</a>, and <a href="mailto:contact@example.com">contact@example.com</a>.</p>
<h2>Footnote</h2>
<p>A note<sup><a href="#user-content-fn-1" id="user-content-fnref-1" data-footnote-ref="" aria-describedby="footnote-label">1</a></sup></p>
<h2>Strikethrough</h2>
<p><del>one</del> or <del>two</del> tildes.</p>
<h2>Table</h2>
<table>
<thead>
<tr>
<th>a</th>
<th align="left">b</th>
<th align="right">c</th>
<th align="center">d</th>
</tr>
</thead>
</table>
<h2>Tag filter</h2>
&lt;plaintext>
<h2>Tasklist</h2>
<ul>
<li><input type="checkbox" disabled="" /> to do</li>
<li><input type="checkbox" disabled="" checked="" /> done</li>
</ul>
<section data-footnotes="" class="footnotes"><h2 id="footnote-label" class="sr-only">Footnotes</h2>
<ol>
<li id="user-content-fn-1">
<p>Big note. <a href="#user-content-fnref-1" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content"></a></p>
</li>
</ol>
</section>

API

This package exports the identifiers gfm and gfmHtml. 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.

gfm(options?)

Add support for parsing GFM in markdown.

Function that can be called to get a syntax extension for micromark (passed in extensions).

options

Configuration (optional).

options.singleTilde

Whether to support strikethrough with a single tilde (boolean, default: true). Single tildes work on github.com, but are technically prohibited by GFM.

Passed as singleTilde in micromark-extension-gfm-strikethrough.

gfmHtml(htmlOptions?)

Add support for turning GFM in markdown to HTML.

Function that can be called to get an HTML extension for micromark (passed in htmlExtensions).

htmlOptions

Configuration (optional).

htmlOptions.clobberPrefix

Prefix to use before the id attribute to prevent it from clobbering (string, default: 'user-content-'). DOM clobbering is this:

<p id=x></p>
<script>console.log(x)</script>
<!-- The element is printed to the console. -->

Elements by their ID are made available in browsers on the window object. Using a prefix prevents this from being a problem

Passed as clobberPrefix in micromark-extension-gfm-footnote.

htmlOptions.label

Label to use for the footnotes section (string, default: 'Footnotes'). Affects screen reader users. Change it if you’re authoring in a different language.

Passed as label in micromark-extension-gfm-footnote.

htmlOptions.backLabel

Label to use from backreferences back to their footnote call (string, default: 'Back to content'). Affects screen reader users. Change it if you’re authoring in a different language.

Passed as backLabel in micromark-extension-gfm-footnote.

Authoring

For recommendations on how to author GFM, see each corresponding readme:

HTML

For info on what HTML features GFM relates to, see each corresponding readme:

CSS

For info on how GitHub styles these features, see each corresponding readme:

Syntax

For info on the syntax of these features, see each corresponding readme:

Types

This package is fully typed with TypeScript. It exports the additional types Options and HtmlOptions.

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. Setting htmlOptions.clobberPrefix = '' is dangerous.

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