Getting Started

First, install @commonmark/js via npm/yarn (npm install @commonmark/js). Despite the package name not matching the repo URL (the official package is @commonmark/js, not commonmark/commonmark.js), this is the canonical CommonMark implementation for JS. Start by parsing and rendering Markdown to HTML in Node.js or the browser:

const { read } = require('fs');
const { Parser, HtmlRenderer } = require('@commonmark/js');

const parser = new Parser();
const renderer = new HtmlRenderer();

const md = '# Hello\n\nThis is **bold** text.';
const ast = parser.parse(md);
const html = renderer.render(ast);
console.log(html); // '<h1>Hello</h1>\n<p>This is <strong>bold</strong> text.</p>\n'

Use the official docs for API reference—focus on Parser, HtmlRenderer, and Node traversal.

Implementation Patterns

Pre-rendering in build pipelines: Pre-parse Markdown files (e.g., in a static site generator) to AST, apply transformations, then render—ensuring deterministic output.
Editor integrations: Use the AST to power rich editing experiences (e.g., detect link targets, headings for TOC generation) before final HTML rendering.
Custom renderers: Extend HtmlRenderer (or implement your own renderer) to output JSX, JSON, or LaTeX—leverage the enter/leave hooks.

Node transformation: Traverse the AST to sanitize or enrich content (e.g., inject rel="noopener" on links, rewrite image paths):

ast.walk((node, info) => {
  if (node.type === 'link' && node.destination?.startsWith('/')) {
    node.destination = `https://example.com${node.destination}`;
  }
});

Gotchas and Tips

Whitespace sensitivity: CommonMark treats trailing whitespace and blank lines strictly—ensure consistent formatting in source MD to avoid unexpected HTML output.
Node immutability: AST nodes are mutable during traversal, but avoid replacing nodes mid-walk—use info.stop() and re-parse if structural changes are needed.
Renderer options: HtmlRenderer supports safe (escape HTML), unsafe (allow raw HTML—not recommended), and fragment (no <html>, <body> wrappers). Use fragment: true for inline rendering.
No built-in extensions: This is strict CommonMark—no GitHub Flavored Markdown (GFM). For footnotes, task lists, or tables, layer extensions after parsing (e.g., via custom AST post-processing or a wrapper like remark).
Debug AST: Use console.log(JSON.stringify(ast, null, 2)) during development to inspect node structure—critical for building custom transforms.
Browser tip: Bundle with esm imports (e.g., import { Parser } from '@commonmark/js') and tree-shake to avoid full parser bloat in production.

Commonmark.js Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips