micromark extension to support GitHub flavored markdown (GFM).
- What is this?
- When to use this
- Install
- Use
- API
- Authoring
- HTML
- CSS
- Syntax
- Types
- Compatibility
- Security
- Contribute
- License
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.
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:
micromark/micromark-extension-gfm-autolink-literal— support GFM autolink literalsmicromark/micromark-extension-gfm-footnote— support GFM footnotesmicromark/micromark-extension-gfm-strikethrough— support GFM strikethroughmicromark/micromark-extension-gfm-table— support GFM tablesmicromark/micromark-extension-gfm-tagfilter— support GFM tagfiltermicromark/micromark-extension-gfm-task-list-item— support GFM tasklists
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-gfmIn 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>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>
<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>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.
Add support for parsing GFM in markdown.
Function that can be called to get a syntax extension for micromark (passed in
extensions).
Configuration (optional).
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.
Add support for turning GFM in markdown to HTML.
Function that can be called to get an HTML extension for micromark (passed in
htmlExtensions).
Configuration (optional).
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.
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.
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.
For recommendations on how to author GFM, see each corresponding readme:
- autolink literal
- footnote
- strikethrough
- table
- tagfilter n/a
- tasklists
For info on what HTML features GFM relates to, see each corresponding readme:
For info on how GitHub styles these features, see each corresponding readme:
- autolink literal
- footnote
- strikethrough
- table
- tagfilter n/a
- tasklists
For info on the syntax of these features, see each corresponding readme:
- autolink literal
- footnote
- strikethrough
- table
- tagfilter n/a
- tasklists
This package is fully typed with TypeScript.
It exports the additional types Options and HtmlOptions.
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.
This package is safe.
Setting htmlOptions.clobberPrefix = '' is dangerous.
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.