small commonmark compliant markdown parser with positional info and concrete tokens
Micromark is a powerful, low-level Markdown parser and compiler. It allows for parsing Markdown content into abstract syntax trees (ASTs), manipulating those trees, and then compiling them back into Markdown or HTML. It's designed for flexibility, extensibility, and adherence to the CommonMark specification, making it suitable for a wide range of applications where Markdown processing is required.
Parsing Markdown to HTML
This feature allows you to convert Markdown text into HTML. The code sample demonstrates how to parse a simple Markdown heading into its HTML equivalent.
const micromark = require('micromark');
const html = micromark('# Hello World');
console.log(html);Extensibility with Syntax Extensions
Micromark can be extended with additional syntax features not covered by the CommonMark specification. This example shows how to use the GitHub Flavored Markdown (GFM) extension to parse text with GFM-specific features.
const micromark = require('micromark');
const gfm = require('micromark-extension-gfm');
const html = micromark('Hello, world!', {extensions: [gfm()]});
console.log(html);Custom HTML Renderers
This feature allows for custom HTML rendering of Markdown elements. The code sample demonstrates how to customize the rendering of images by adding a custom CSS class to the <img> tag.
const micromark = require('micromark');
const html = micromark('', {
htmlExtensions: [{
enter: {image: (node) => `<img src="${node.url}" alt="${node.alt}" class="custom-class">`}
}]
});
console.log(html);Marked is a fast Markdown parser and compiler built for speed. It is simpler and less customizable than micromark but offers a good balance between speed and extensibility for many common use cases.
Remark is part of the unified collective and provides a powerful Markdown processor powered by plugins. It focuses on the manipulation of Markdown and ASTs, similar to micromark, but with a higher-level API and a broader ecosystem of plugins for extended functionality.
Showdown is a JavaScript Markdown to HTML converter, which can be used both on the client side and server side. It is designed to be easy to use and extend, similar to micromark, but with a focus on simplicity and ease of integration into existing projects.
Markdown parser.
Note: this is the
micromarkpackage from the micromark monorepo. See the monorepo readme for more on the project. See this readme for how to use it.
See § Comparison for more info
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).
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.
unifiedjs.comThis package is ESM only. In Node.js (version 16+), install with npm:
npm install micromark
In Deno with esm.sh:
import {micromark} from 'https://esm.sh/micromark@3'
In browsers with esm.sh:
<script type="module">
import {micromark} from 'https://esm.sh/micromark@3?bundle'
</script>
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):
import {micromark} from 'micromark'
import {gfmHtml, gfm} 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
}
micromark core has two entries in its export map: micromark and
micromark/stream.
micromark exports the identifier micromark.
micromark/stream exports the identifier stream.
There are no default exports.
The export map supports the development condition.
Run node --conditions development module.js to get instrumented dev code.
Without this condition, production code is loaded.
See § Size & 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 encodings.
value (string or Uint8Array)
— markdown to parseencoding (string, default: 'utf8')
— character encoding to understand value as when it’s a
Uint8Arrayoptions (Options, optional)
— configurationCompiled 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.
options (Options, optional)
— configurationDuplex stream.
OptionsConfiguration (TypeScript type).
allowDangerousHtmlWhether 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 § Security.
allowDangerousProtocolWhether 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 § Security.
defaultLineEndingDefault 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.
extensionsArray of syntax extensions (Array<SyntaxExtension>, default: []).
See § Extensions.
htmlExtensionsArray of syntax extensions (Array<HtmlExtension>, default: []).
See § Extensions.
This package is fully typed with TypeScript.
It exports the additional type Options.
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.
This package is safe.
See security.md in micromark/.github for how to
submit a security report.
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, organisation, or community you agree to abide by its terms.
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? |
FAQs
small commonmark compliant markdown parser with positional info and concrete tokens
The npm package micromark receives a total of 8,436,969 weekly downloads. As such, micromark popularity was classified as popular.
We found that micromark demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.