micromark
!Buildbuild-badgebuild
!Coveragecoverage-badgecoverage
!Downloadsdownloads-badgedownloads
!Sizebundle-size-badgebundle-size
!Sponsorssponsors-badgeopencollective
!Backersbackers-badgeopencollective
!Chatchat-badgechatMarkdown parser.
Note: this is the micromark
package from the micromark monorepo.
See the monorepo readmemicromark for more on the project.
See this readme for how to use it.
Feature highlights
- x compliantcommonmark (100% to CommonMark)
- x extensions (100% GFM, 100% MDX.jsmdxjs, directives,
[frontmatter][], [math][])
- x safesecurity (by default)
- x robusttest (±2k tests, 100% coverage, fuzz testing)
- x smallsize-debug (smallest CM parser at ±14kb)
Contents
* [`micromark(value[, encoding][, options])`](#micromarkvalue-encoding-options)
* [`stream(options?)`](#streamoptions)
* [`Options`](#options)
When should I use this?
- If you just want to turn markdown into HTML (with maybe a few extensions)
- If you want to do really complex things with markdown
See § Comparisoncomparison for more info
What is this?
micromark
is an open source markdown parser written in JavaScript.
It’s implemented as a state machine that emits concrete tokens, so that every
byte is accounted for, with positional info.
It then compiles those tokens directly to HTML, but other tools can take the
data and for example build an AST which is easier to work with
(mdast-util-to-markdown
mdast-util-to-markdown).While most markdown parsers work towards compliancy with CommonMark (or GFM), this project goes further by following how the reference parsers (
cmark
,
cmark-gfm
) work, which is confirmed with thousands of extra tests.Other than CommonMark and GFM, micromark also supports common extensions to markdown such as MDX, math, and frontmatter.
These npm packages have a sibling project in Rust:
markdown-rs
markdown-rs.- to learn markdown, see this cheatsheet and tutorialcheat
- for more about us, see
unifiedjs.com
site - for updates, see Twitter
- for questions, see Discussionschat
- to help, see contribute and sponsor below
Install
This package is ESM onlyesm. In Node.js (version 16+), install with npm:
npm install micromark
In Deno with
esm.sh
esmsh:import {micromark} from 'https://esm.sh/micromark@3'
In browsers with
esm.sh
esmsh:<script type="module">
import {micromark} from 'https://esm.sh/micromark@3?bundle'
</script>
Use
Typical use (buffering):
import {micromark} from 'micromark'
console.log(micromark('## Hello, *world*!'))
Yields:
<h2>Hello, <em>world</em>!</h2>
You can pass extensions (in this case
micromark-extension-gfm
gfm):import {micromark} from 'micromark'
import {gfm, gfmHtml} from 'micromark-extension-gfm'
const value = '* [x] contact@example.com ~~strikethrough~~'
const result = micromark(value, {
extensions: [gfm()],
htmlExtensions: [gfmHtml()]
})
console.log(result)
Yields:
<ul>
<li><input checked="" disabled="" type="checkbox"> <a href="mailto:contact@example.com">contact@example.com</a> <del>strikethrough</del></li>
</ul>
Streaming interface:
import {createReadStream} from 'node:fs'
import {stream} from 'micromark/stream'
createReadStream('example.md')
.on('error', handleError)
.pipe(stream())
.pipe(process.stdout)
function handleError(error) {
// Handle your error here!
throw error
}
API
micromark
core has two entries in its export map: micromark
and
micromark/stream
.micromark
exports the identifier micromark
api-micromark.
micromark/stream
exports the identifier stream
api-stream.
There are no default exports.The export map supports the
development
conditiondevelopment.
Run node --conditions development module.js
to get instrumented dev code.
Without this condition, production code is loaded.
See § Size & debugsize-debug for more info.micromark(value[, encoding][, options])
Compile markdown to HTML.Note: which encodings are supported depends on the engine. For info on Node.js, see WHATWG supported encodingsencoding.
Parameters
value
(string
orUint8Array
uint8-array)
— markdown to parse
encoding
(string
, default:'utf8'
)
— [character encoding][encoding] to understand `value` as when it’s a
[`Uint8Array`][uint8-array]
options
(Options
api-options, optional)
— configuration
Returns
Compiled HTML (string
).stream(options?)
Create a duplex (readable and writable) stream.Some of the work to parse markdown can be done streaming, but in the end buffering is required.
micromark does not handle errors for you, so you must handle errors on whatever streams you pipe into it. As markdown does not know errors,
micromark
itself does not emit errors.Parameters
options
(Options
api-options, optional)
— configuration
Returns
Duplex stream.Options
Configuration (TypeScript type).Fields
allowDangerousHtml
Whether to allow (dangerous) HTML (boolean
, default: false
).The default is
false
, which still parses the HTML according to CommonMark
but shows the HTML as text instead of as elements.Pass
true
for trusted content to get actual HTML elements.
See § Securitysecurity.allowDangerousProtocol
Whether to allow dangerous protocols in links and images (boolean
, default:
false
).The default is
false
, which drops URLs in links and images that use dangerous
protocols.Pass
true
for trusted content to support all protocols.URLs that have no protocol (which means it’s relative to the current page, such as
./some/page.html
) and URLs that have a safe protocol (for images: http
,
https
; for links: http
, https
, irc
, ircs
, mailto
, xmpp
), are
safe.
All other URLs are dangerous and dropped.
See § Securitysecurity.defaultLineEnding
Default line ending to use when compiling to HTML, for line endings not in
value
('\r'
, '\n'
, or '\r\n'
; default: first line ending or '\n'
).Generally,
micromark
copies line endings (\r
, \n
, \r\n
) in the markdown
document over to the compiled HTML.
In some cases, such as > a
, CommonMark requires that extra line endings are
added: <blockquote>\n<p>a</p>\n</blockquote>
.To create that line ending, the document is checked for the first line ending that is used. If there is no line ending,
defaultLineEnding
is used.
If that isn’t configured, \n
is used.extensions
Array of syntax extensions (Array<SyntaxExtension>
, default: []
).
See § Extensionsextensions.htmlExtensions
Array of syntax extensions (Array<HtmlExtension>
, default: []
).
See § Extensionsextensions.Types
This package is fully typed with TypeScript. It exports the additional typeOptions
api-options.Compatibility
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,
micromark@^4
, compatible
with Node.js 16.Security
This package is safe. Seesecurity.md
securitymd in micromark/.github
health for how to
submit a security report.Contribute
Seecontributing.md
contributing in micromark/.github
health for ways
to get started.
See support.md
support for ways to get help.This project has a code of conductcoc. By interacting with this repository, organisation, or community you agree to abide by its terms.
Sponsor
Support this effort and give back by sponsoring on OpenCollective!
Salesforce 🏅 |
||||||||
Vercel |
Motif |
HashiCorp |
GitBook |
Gatsby |
||||
Netlify |
Coinbase |
ThemeIsle |
Expo |
Boost Note |
Markdown Space |
Holloway |
||
You? |