npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

micromark

v4.0.1

Published

small commonmark compliant markdown parser with positional info and concrete tokens

Downloads

37,746,362

Readme

micromark

Build Coverage Downloads Size Sponsors Backers Chat

Markdown parser.

Note: this is the micromark package from the micromark monorepo. See the monorepo readme for more on the project. See this readme for how to use it.

Feature highlights

Contents

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 § Comparison 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).

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.

Install

This 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>

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):

import {micromark} from 'micromark'
import {gfmHtml, gfm} from 'micromark-extension-gfm'

const value = '* [x] [email protected] ~~strikethrough~~'

const result = micromark(value, {
  extensions: [gfm()],
  htmlExtensions: [gfmHtml()]
})

console.log(result)

Yields:

<ul>
<li><input checked="" disabled="" type="checkbox"> <a href="mailto:[email protected]">[email protected]</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. 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.

Parameters
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, 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 § Security.

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 § Security.

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 § Extensions.

htmlExtensions

Array of syntax extensions (Array<HtmlExtension>, default: []). See § Extensions.

Types

This package is fully typed with TypeScript. It exports the additional type 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. 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!

License

MIT © Titus Wormer