A native Markdown rendering engine that produces paginated PNG/SVG documents — no browser, no Chromium, no DOM.

Supports CommonMark, GFM (tables, task lists, strikethrough), syntax-highlighted code blocks (Shiki), and LaTeX math formulas (MathJax) — all rendered server-side.

📖 Documentation — Guide · Showcase · API Reference

Most Markdown rendering pipelines go through a browser:

Markdown → HTML → DOM/CSS → browser layout → screenshot

marknative takes a different path. It parses Markdown directly into a typed document model, runs its own block and inline layout engine, paginates the result into fixed-size pages, and paints each page using a native 2D canvas API.

The result is deterministic, server-renderable, and completely headless.

---

Gallery

Math formulas (MathJax block + inline) mixed with syntax-highlighted code:

Full syntax fixture, rendered across 10 pages with syntax-highlighted fenced code blocks:

---

Why

Requirement	Browser-based	marknative
Runs on the server without a browser	✗	✓
Deterministic page breaks across runs	✗	✓
Direct PNG / SVG output	✗	✓
LaTeX math formulas (server-side MathJax)	✗	✓
Syntax-highlighted code blocks (Shiki)	✗	✓
Batch rendering at scale	slow	fast
Embeddable as a library	heavy	lightweight

---

Installation

bun add marknative
# or
npm install marknative

Peer dependency: marknative uses skia-canvas as its paint backend. It ships prebuilt native binaries for macOS, Linux, and Windows — no additional setup is needed in most environments.

---

Quick Start

import { renderMarkdown } from 'marknative'

const pages = await renderMarkdown(`
# Hello, marknative

A native Markdown rendering engine that produces **paginated PNG pages**
without a browser.

- CommonMark + GFM support
- Deterministic layout and pagination
- PNG and SVG output
`)

console.log(`Rendered ${pages.length} page(s)`)

for (const [i, page] of pages.entries()) {
  // page.format === 'png'
  // page.data   === Buffer
  await Bun.write(`page-${i + 1}.png`, page.data)
}

---

API

renderMarkdown(markdown, options?)

Parses, lays out, paginates, and paints a Markdown document. Returns one output entry per page.

function renderMarkdown(
  markdown: string,
  options?: {
    format?: 'png' | 'svg'                      // default: 'png'
    singlePage?: boolean                         // render into one image instead of paginating
    theme?: BuiltInThemeName | ThemeOverrides    // default: defaultTheme
    scale?: number                               // PNG pixel density multiplier — default: 2 (retina)
    painter?: Painter                            // override the paint backend
    codeHighlighting?: {
      theme?: string                             // Shiki theme — auto-detected from page background
    }
  },
): Promise<RenderPage[]>

Return type:

type RenderPage =
  | { format: 'png'; data: Buffer;  page: PaintPage }
  | { format: 'svg'; data: string;  page: PaintPage }

Each entry carries both the raw output (data) and the fully resolved page layout (page) so you can inspect fragment positions without re-rendering.

---

parseMarkdown(markdown)

Parses Markdown source into marknative's internal document model without running layout or paint. Useful for inspecting document structure or building custom renderers.

function parseMarkdown(markdown: string): MarkdownDocument

---

defaultTheme

The built-in default theme. Page size is 1080 × 1440 px (portrait card ratio). Font sizes, line heights, margins, and block spacing are all defined here.

import { defaultTheme } from 'marknative'

console.log(defaultTheme.page)
// { width: 1080, height: 1440, margin: { top: 80, right: 72, bottom: 80, left: 72 } }

---

Theme System

marknative ships with 10 built-in themes and a full theme customization API.

Built-in themes — pass a name string as the theme option:

// 'default' | 'github' | 'solarized' | 'sepia' | 'rose'
// 'dark' | 'nord' | 'dracula' | 'ocean' | 'forest'
const pages = await renderMarkdown(markdown, { theme: 'dark' })
const pages = await renderMarkdown(markdown, { theme: 'nord' })

Partial overrides — merged onto defaultTheme:

const pages = await renderMarkdown(markdown, {
  theme: {
    colors: { background: '#1e1e2e', text: '#cdd6f4' },
    page: { width: 800 },
  },
})

Full control with mergeTheme:

import { mergeTheme, getBuiltInTheme } from 'marknative'

const myTheme = mergeTheme(getBuiltInTheme('nord'), {
  colors: { link: '#ff6b6b' },
})

const pages = await renderMarkdown(markdown, { theme: myTheme })

Gradient backgrounds:

import { mergeTheme, defaultTheme } from 'marknative'

const theme = mergeTheme(defaultTheme, {
  colors: {
    background: '#0f0c29',
    backgroundGradient: {
      type: 'linear',
      angle: 135,
      stops: [
        { offset: 0,   color: '#24243e' },
        { offset: 0.5, color: '#302b63' },
        { offset: 1,   color: '#0f0c29' },
      ],
    },
    text: '#e8e0ff',
  },
})

See the Themes guide and Themes showcase for the full reference.

---

Performance

Benchmarks run on Apple M-series (warm, singletons already initialised). Run bun bench/perf.ts to reproduce.

Throughput by document type — PNG 2× (default)

Document type	mean	p50	p90
Plain text (prose + lists + blockquotes)	116 ms	115 ms	120 ms
Code-heavy (3 languages, shiki)	101 ms	101 ms	104 ms
Math-heavy (4 block + 3 inline formulas)	100 ms	99 ms	103 ms
Mixed (math + code)	98 ms	97 ms	100 ms

Output format — mixed doc

Format	mean	p50	p90	note
SVG	5.6 ms	5.6 ms	6.5 ms	layout + serialize only
PNG 2×	99 ms	98 ms	102 ms	full rasterize + encode

SVG is ~17× faster than PNG. canvas.toBuffer('png') (pure CPU PNG compression) accounts for 94% of PNG render time; all parsing, layout, and drawing are <8 ms/page.

Scale factor — mixed doc, PNG only

Scale	Resolution	mean
1	1080 × ~650 (0.7 MP)	29 ms
1.5	1620 × ~975 (1.6 MP)	58 ms
2 (default)	2160 × ~1300 (2.8 MP)	99 ms
3	3240 × ~1950 (6.3 MP)	214 ms

PNG encode time scales linearly with pixel count. Use scale: 1 for previews, scale: 2 for retina output.

Concurrency — plain doc, PNG 2×

Mode	mean per batch
1× sequential	118 ms
2× parallel	127 ms
4× parallel	192 ms
8× parallel	363 ms

Parallel renders share CPU resources; throughput scales near-linearly up to core count.

---

Rendering Pipeline

Markdown source
  │
  ▼
CommonMark + GFM AST          (micromark, mdast-util-from-markdown)
  │
  ▼
MarkdownDocument               internal typed document model
  │
  ▼
BlockLayoutFragment[]          block + inline layout engine
  │
  ▼
Page[]                         paginator — slices fragments into fixed-height pages
  │
  ▼
PNG Buffer / SVG string        skia-canvas paint backend

Each stage is independently testable. The layout engine has no dependency on the paint backend, and the paint backend accepts a plain data structure — it does not re-run layout.

---

Supported Syntax

CommonMark

Element	Support
Headings (H1–H6)	✓
Paragraphs	✓
Bold, italic, bold italic	✓
Inline code	✓
Links	✓
Fenced code blocks	✓
Blockquotes (nested)	✓
Ordered lists	✓
Unordered lists (nested)	✓
Images (block + inline)	✓
Thematic breaks	✓
Hard line breaks	✓

GFM Extensions

Element	Support
Tables (with alignment)	✓
Task lists	✓
Strikethrough	✓

Math (LaTeX via MathJax)

Element	Support
Block formulas $$...$$	✓
Inline formulas $...$	✓
Math in blockquotes / lists / tables	✓
AMSmath, boldsymbol, mathtools	✓

---

Recipes

Save all pages as PNG files

import { renderMarkdown } from 'marknative'
import { writeFile } from 'node:fs/promises'

const markdown = await Bun.file('article.md').text()
const pages = await renderMarkdown(markdown)

await Promise.all(
  pages.map((page, i) =>
    writeFile(`out/page-${String(i + 1).padStart(2, '0')}.png`, page.data)
  )
)

Serve rendered pages over HTTP with Bun

import { renderMarkdown } from 'marknative'

Bun.serve({
  routes: {
    '/render': {
      async POST(req) {
        const { markdown } = await req.json()
        const pages = await renderMarkdown(markdown, { format: 'png' })
        const first = pages[0]

        if (!first || first.format !== 'png') {
          return new Response('no output', { status: 500 })
        }

        return new Response(first.data, {
          headers: { 'Content-Type': 'image/png' },
        })
      },
    },
  },
})

Export as SVG

const pages = await renderMarkdown(markdown, { format: 'svg' })

for (const page of pages) {
  if (page.format === 'svg') {
    console.log(page.data) // inline SVG string
  }
}

Math formulas

Block and inline LaTeX — rendered server-side via MathJax, no browser required. Formula colors follow the active theme automatically.

const pages = await renderMarkdown(`
## Fourier Transform

$$
\\hat{f}(\\xi) = \\int_{-\\infty}^{\\infty} f(x)\\,e^{-2\\pi ix\\xi}\\,dx
$$

The gradient $\\nabla f$ points in the direction of steepest ascent.
Entropy: $H(X) = -\\sum p \\log p$.

\`\`\`python
import numpy as np
def dft(x):
    N, n = len(x), np.arange(len(x))
    return np.exp(-2j * np.pi * n.reshape(N,1) * n / N) @ x
\`\`\`

Complexity: $O(N^2)$ naïve, $O(N\\log N)$ with FFT.
`)

MathJax is initialised lazily on first use (~180 ms cold start). All subsequent renders reuse the singleton and cached SVGs — warm overhead is < 2 ms.

See the Math guide for the full reference.

Syntax highlighting for code blocks

// Auto-detected from page background (light → github-light, dark → github-dark)
const pages = await renderMarkdown(markdown)
const pages = await renderMarkdown(markdown, { theme: 'dark' })   // uses github-dark automatically

// Override the Shiki theme explicitly
const pages = await renderMarkdown(markdown, {
  codeHighlighting: { theme: 'nord' },
})

The Shiki theme is auto-selected based on the WCAG relative luminance of the page background — dark page themes automatically get a dark code theme. Code blocks without a language tag fall back to plain monochrome text.

Control PNG resolution with scale

const pages = await renderMarkdown(markdown, { scale: 1 })   // ~29 ms/page — fast preview
const pages = await renderMarkdown(markdown, { scale: 2 })   // ~99 ms/page — retina (default)
const pages = await renderMarkdown(markdown, { scale: 3 })   // ~214 ms/page — print quality

---

Tech Stack

Layer	Library
Markdown parsing	micromark + mdast-util-from-markdown
GFM extensions	micromark-extension-gfm + mdast-util-gfm
Math rendering	mathjax-full (server-side SVG, liteAdaptor)
Syntax highlighting	shiki
Text shaping	@chenglou/pretext
2D rendering	skia-canvas
Language	TypeScript

---

Roadmap

• Improve paragraph line-breaking quality for English prose
• Refine CJK and mixed Chinese-English line-breaking rules
• Syntax highlighting for code blocks (Shiki, all themes, auto-detected from theme)
• LaTeX math rendering (MathJax, block + inline, all block types)
• Expose public theme and page configuration API
• PNG resolution control (scale option)
• Support custom fonts
• Complete GFM coverage (footnotes, autolinks)

---

License

MIT & Linux Do