micromark

What is micromark?

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.

What are micromark's main functionalities?

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('![alt text](/path/to/img.jpg)', {
  htmlExtensions: [{
    enter: {image: (node) => `<img src="${node.url}" alt="${node.alt}" class="custom-class">`}
  }]
});
console.log(html);

Other packages similar to micromark

marked

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

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

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.

README

smol markdown parser that’s different (open beta)

Intro

micromark is a long awaited markdown parser. It uses a state machine to parse the entirety of markdown into tokens. It’s the smallest CommonMark compliant markdown parser in JavaScript. It’ll replace the internals of remark-parse, the most popular markdown parser. Its interface is optimized to compile to HTML, but its parts can be used to generate syntax trees or compile to other output formats too. It’s in open beta: up next are extensions (GFM, MDX), integration in remark, performance, CSTs, and docs.

• for updates, see Twitter
• for more about us, see unifiedjs.com
• for questions, see Discussions
• to help, see contribute or sponsor below

Contents

• Checklist
• Install
• Use
• API
  • micromark(doc[, encoding][, options])
  • createSteam(options?)
• List of extensions
• Version
• Security
• Contribute
• Sponsor
• License

Checklist

• CommonMark compliant
• Smallest CM parser that exists (and there’s some more to shave off!)
• Safe by default
• Streaming interface
• 1500+ tests and 100% coverage
• Abstract syntax tree (mdast-util-from-markdown, mdast-util-to-markdown)
• Extensions: GFM, directives, MDX
• Integrate into remark
• Complementary docs on state machine (CMSM) for parsers in other languages
• Performance
• Concrete syntax tree

Install

npm:

npm install micromark

Use

var micromark = require('micromark')

console.log(micromark('## Hello, *world*!'))

Yields:

<h2>Hello, <em>world</em>!</h2>

Or:

var fs = require('fs')
var micromark = require('micromark/stream')

fs.createReadStream('example.md').pipe(micromark()).pipe(process.stdout)

Or use remark, which will soon include micromark, has ASTs, and is stable.

API

Note that there are more APIs than listed here currently. Those are considered to be in progress.

micromark(doc[, encoding][, options])

Compile markdown to HTML.

Parameters

doc

Markdown to parse (string or Buffer)

encoding

Character encoding to understand doc as when it’s a Buffer (string, default: 'utf8').

options.defaultLineEnding

Value to use for line endings not in doc (string, 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>.

options.allowDangerousHtml

Whether to allow embedded HTML (boolean, default: false).

options.allowDangerousProtocol

Whether to allow potentially dangerous protocols in links and images (boolean, default: false). URLs relative to the current protocol are always allowed (such as, image.jpg). For links, the allowed protocols are http, https, irc, ircs, mailto, and xmpp. For images, the allowed protocols are http and https.

options.extensions

Array of syntax extensions (Array.<SyntaxExtension>, default: []).

options.htmlExtensions

Array of HTML extensions (Array.<HtmlExtension>, default: []).

Returns

string — Compiled HTML.

createSteam(options?)

Streaming version of micromark. Compiles markdown to HTML. options are the same as the buffering API above. Available at require('micromark/stream').

List of extensions

• micromark/micromark-extension-frontmatter — support frontmatter (YAML, TOML, etc)
• micromark/micromark-extension-gfm-autolink-literal — support GFM autolink literals
• micromark/micromark-extension-gfm-strikethrough — support GFM strikethrough
• micromark/micromark-extension-gfm-tagfilter — support GFM tagfilter

Version

The open beta of micromark starts at version 2.0.0 (there was a different package published on npm as micromark before). micromark will adhere to semver at 3.0.0. Use tilde ranges for now: "micromark": "~2.0.0".

Security

It’s safe to compile markdown to HTML if it does not include embedded HTML nor uses dangerous protocols in links (such as javascript: or data:). micromark is safe by default if embedded HTML or dangerous protocols are used too, as it encodes or drops them. Turning on the allowDangerousHtml or allowDangerousProtocol options for user-provided markdown opens you up to cross-site scripting (XSS) attacks.

For more information on markdown sanitation, see improper-markup-sanitization.md by @chalker.

See security.md in micromark/.github for how to submit a security report.

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, organisation, or community you agree to abide by its terms.

Sponsor

Support this effort and give back by sponsoring on OpenCollective!

Salesforce 🏅
Gatsby 🥇	Vercel 🥇	Netlify	Holloway	ThemeIsle	BoostIO	Expo
You?

License

MIT © Titus Wormer