Download this page as .mdz

MDZip renderer

@mdzip/renderer turns Markdown and MDZip (.mdz) files into HTML. It's the renderer behind the preview in MDZip Studio, the VS Code extension and the web editor, and it builds this website. Use it in your own app or site and your pages come out exactly the way they look while they're being written.

It does two jobs:

  • Markdown to HTML, the same way the MDZip editor's preview does: GitHub-style Markdown with tables and task lists, footnotes, highlighted code, Mermaid diagrams, stable heading anchors, and sanitizing for content you didn't write.
  • An .mdz to a web page: the main document's HTML, its pictures ready to publish, links between pages rewritten, and the title and description from the file's manifest.

It runs in Node.js and in the browser, and it's open source under the Apache 2.0 license.

Install

npm install @mdzip/renderer
npm install jsdom   # only in Node.js, for sanitizing

It installs @mdzip/core-js, the JavaScript core library, with it. Sanitizing needs a DOM: browsers have one, and in Node.js the renderer uses jsdom when it's installed.

Markdown to HTML

import { renderMdzipMarkdown } from '@mdzip/renderer';

const html = renderMdzipMarkdown('# Trip notes\n\nWe went to the **beach**.');
// <h1 id="trip-notes">Trip notes</h1>
// <p>We went to the <strong>beach</strong>.</p>

In Node.js, give it a DOM window once first: useMdzipDomWindow(new JSDOM('').window), with JSDOM from jsdom. (renderMdzPage() below does that for you.)

The HTML is sanitized by default, so it's safe to show Markdown from other people. Pass { sanitize: false } for content you wrote yourself.

Code blocks are highlighted with highlight.js for common languages: the HTML has its classes (<code class="hljs language-js">), so add a highlight.js theme, or your own colors for those classes, to see them. Mermaid code blocks come out as <pre><code class="language-mermaid">. Load Mermaid on the page to draw them, as this site does.

An .mdz to a web page

import fs from 'node:fs';
import path from 'node:path';
import { renderMdzPage } from '@mdzip/renderer/page';

const page = await renderMdzPage(fs.readFileSync('about.mdz'));

page.title;        // from the manifest
page.description;  // from the manifest
page.html;         // the main document, rendered

// Save the pictures next to the page, where the HTML expects them.
for (const picture of page.assets) {
  fs.mkdirSync(path.dirname(`site/${picture.path}`), { recursive: true });
  fs.writeFileSync(`site/${picture.path}`, picture.bytes);
}

The renderer doesn't store anything itself: it gives you each picture's bytes in page.assets, and you save them. Each one has a path relative to the page, assets/page-images/ and a file name made from its content (3f9a1c0b7e2d.png). The HTML already points there, so if you save the pictures at those paths beside the page, they show up with no setup.

A file name made from the content means a picture used on several pages is published once, and browsers can keep it cached.

Pictures somewhere else

If your pictures live in a different folder, or on another server, say where with assetUrl. It gets each picture's file name and returns the address to put in the HTML:

const page = await renderMdzPage(bytes, {
  assetUrl: (fileName) => `https://cdn.example.com/images/${fileName}`,
});

Then upload page.assets to that place. If you only learn a picture's address after uploading it (to a CMS media library, say), render first and swap the addresses in afterwards with page.withAssetUrls(urls), passing the address for each picture's archive path or file name.

A page with no separate files

inlineImages: true puts the pictures into the HTML itself as data: URIs, so the page is one self-contained file and page.assets is empty. PNG, JPEG, WebP and other binary pictures are base64-encoded (data:image/png;base64,…). SVGs are text already, so they're percent-encoded instead (data:image/svg+xml,…), which is usually smaller.

const page = await renderMdzPage(bytes, { inlineImages: true });
fs.writeFileSync('about.html', page.html);

That suits a page you email or attach. Base64 makes each picture about a third bigger, and browsers can't cache a picture separately, so for a website, separate files are better.

Links to other pages go through resolveLink, so a link to faq.mdz can become faq.html or /faq/:

const page = await renderMdzPage(bytes, {
  resolveLink: (href) => href.replace(/\.mdz$/, '.html'),
  externalLinks: 'new-tab',
});

With externalLinks: 'new-tab', links to other sites open in a new tab, as they do on this site. SVG pictures that contain links are put into the page itself, so their links work.

Write the HTML into your own page layout. The renderer doesn't make navigation, menus or a sitemap: your site generator or template does that.

Heading anchors

Every heading gets an id made from its text: lowercase, punctuation and emoji removed, spaces turned into hyphens. Letters in any language are kept. A repeated heading gets -1, -2 and so on, as on GitHub. ## MDZip Studio — the desktop app becomes #mdzip-studio-the-desktop-app.

Studio, VS Code, the web editor and this site all use the same rule, so a link to a section works everywhere the document is shown. MDZip for Pandoc makes the same anchors when it converts to HTML.

How this site uses it

Most pages on this site are each one .mdz file, written in Studio or VS Code. The build renders each one with renderMdzPage, puts it into the site's page layout and publishes the pictures. How these pages are made walks through the whole process.

Other ways to show .mdz

  • A full viewer or editor in your web app: @mdzip/editor, which uses this renderer for its preview.
  • Your own Markdown renderer: read the files with a core library and follow Add MDZip to your app.
  • No code: MDZip for Pandoc converts .mdz to HTML, Word, EPUB and more, and can publish a website with a GitHub Action.

More

This page renders from renderer.mdz (MDZip, ~5 KB, updated 2026-11-18) — one self-contained file. Download it, open it in the web editor, or read how these pages are made. Built with @mdzip/renderer.