Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nuejs/nue/llms.txt

Use this file to discover all available pages before exploring further.

Nuemark is Nue’s Markdown-based authoring format. Beyond the standard Markdown you already know, it adds automatic sections, custom tags, responsive images, and structured data access — while keeping content files free from JavaScript. The package exposes a rendering function, a document parser, and a set of lower-level utilities for building custom pipelines.

​
Installation

bun add nuemark
# or
npm install nuemark

​
Exports

import { nuemark, parseNuemark, elem, renderInline, parseSize, renderIcon } from 'nuemark'

​
nuemark(content, opts?)

Renders a Nuemark string directly to an HTML string. This is the simplest entry point — pass content in, get HTML out. 
const html = nuemark(content, opts)
​
content
string
required
The full Nuemark source text including optional YAML front-matter, Markdown, and Nuemark tag blocks.
​
opts
object
Rendering options forwarded to the block renderer.
Return value — an HTML string. Example: 
import { nuemark } from 'nuemark'

const md = `
# Hello World

This is a paragraph with **bold** and _italic_ text.

[image src="/img/hero.jpg" alt="Hero image"]
`

const html = nuemark(md, { heading_ids: true })

​
parseNuemark(content)

Parses a Nuemark string into a document object without rendering. Use this when you need to inspect headings, extract front-matter, or render with custom options later. 
const doc = parseNuemark(content)
​
content
string
required
The raw Nuemark source string, including optional YAML front-matter delimited by ---.
Return value — a document object:
​
meta
object
Key–value pairs parsed from the YAML front-matter block. If the document has an # H1 heading and no explicit title in front-matter, meta.title is set automatically. If the first paragraph exists and meta.description is absent, it is set from that paragraph.
​
blocks
Array
The flat list of parsed block nodes (headings, paragraphs, code blocks, tag invocations, etc.) before sectionization.
​
headings
Array
A computed property that filters blocks to heading nodes and returns objects with { id, level, text, attr }. The id is derived from the heading text when not set explicitly.
doc.headings.forEach(h => {
  console.log(h.level, h.id, h.text)
})
​
codeblocks
Array
All fenced code-block nodes in the document. Each item exposes name (language), code (raw source), attr, and data.
​
render(opts?)
function
Render the parsed document to an HTML string. Accepts the same opts object as nuemark(). Calling render multiple times with different options is safe — the document object is not mutated.
const doc = parseNuemark(content)
const html = doc.render({ heading_ids: true, data: pageData })
Example: 
import { parseNuemark } from 'nuemark'

const content = `
---
title: Getting Started
author: Ada
---

# Getting Started

Learn how to use Nue in five minutes.
`

const doc = parseNuemark(content)
console.log(doc.meta.title)       // 'Getting Started'
console.log(doc.meta.author)      // 'Ada'
console.log(doc.headings[0].id)   // 'getting-started'

const html = doc.render({ heading_ids: true })

​
elem(tag, attrs?, content?)

A low-level HTML element builder. Returns a serialized HTML string for the given tag, optional attribute object, and inner content. 
const html = elem('p', { class: 'lead' }, 'Hello world')
// => '<p class="lead">Hello world</p>'
​
tag
string
required
The HTML tag name, e.g. 'p', 'div', 'figure'.
​
attrs
object | string
When an object, each key–value pair is serialized as an HTML attribute. Falsy values are omitted. When a string is passed as the second argument (no attrs object), it is treated as the content.
​
content
string
Inner HTML content to place between the opening and closing tags.
Return value — an HTML string. Examples: 
import { elem } from 'nuemark'

elem('a', { href: '/docs', class: 'nav-link' }, 'Documentation')
// => '<a href="/docs" class="nav-link">Documentation</a>'

elem('img', { src: '/img/logo.svg', alt: 'Logo' })
// => '<img src="/img/logo.svg" alt="Logo">'

elem('ul', null, '<li>One</li><li>Two</li>')
// => '<ul><li>One</li><li>Two</li></ul>'

​
renderInline(str, opts?)

Renders a single line of Nuemark inline markup — bold, italic, code spans, links, images, and inline tag invocations — to an HTML string. 
const html = renderInline(str, opts)
​
str
string
required
A single-line string of Nuemark inline content.
​
opts
object
Same options accepted by nuemark(), particularly data and tags. Used when the inline string contains { expr } variables or custom inline tags.
Return value — an HTML string with all inline markup expanded. Examples: 
import { renderInline } from 'nuemark'

renderInline('**Bold** and _italic_')
// => '<strong>Bold</strong> and <em>italic</em>'

renderInline('Read the [docs](/docs)')
// => 'Read the <a href="/docs">docs</a>'

renderInline('Hello, { name }!', { data: { name: 'Ada' } })
// => 'Hello, Ada!'

​
parseSize(data)

Extracts width and height values from a data object that may use a compact size shorthand (e.g. "800x600"). Used internally by the [image] tag renderer; export it when you build custom image tags. 
const dimensions = parseSize(data)
​
data
object
required
An object that may contain any of: size (e.g. "800x600" or "400"), width, height.
Return value — an object { width, height }:
  • size: "800x600" → { width: "800", height: "600" }
  • size: "400" → { width: "400", height: "400" } (square)
  • width: 640, height: 480 → { width: 640, height: 480 } (passthrough)
Example: 
import { parseSize } from 'nuemark'

parseSize({ size: '1200x630' })
// => { width: '1200', height: '630' }

parseSize({ size: '64' })
// => { width: '64', height: '64' }

parseSize({ width: 800, height: 400 })
// => { width: 800, height: 400 }

​
renderIcon(name, symbol, icon_dir?)

Renders an SVG icon either by reading an .svg file from disk or by generating an inline <use> reference to a sprite. 
const html = renderIcon(name, symbol, icon_dir)
​
name
string
The filename (without extension) of an .svg file to inline. Takes precedence over symbol when provided.
​
symbol
string
A sprite symbol ID. Generates <svg class="icon icon-{symbol}"><use href="#{symbol}"/></svg>.
​
icon_dir
string
The file-system directory to look up icon files in when name is set.
Return value — an SVG HTML string, or '' if both name and symbol are falsy. Examples: 
import { renderIcon } from 'nuemark'

// Sprite reference
renderIcon(null, 'arrow-right')
// => '<svg class="icon icon-arrow-right"><use href="#arrow-right"/></svg>'

// Inline SVG from file
renderIcon('logo', null, './icons')
// Reads ./icons/logo.svg and returns its content

​
Document structure

parseNuemark returns a document whose internal blocks map to these types:
Block typeDetected byNotes
Headingblock.level (1–6)text, attr, and computed id
Paragraphblock.is_contentcontent is an array of line strings
Code blockblock.is_codename = language, code = raw source
Tag invocationblock.is_tagname, attr, data, blocks
Tableblock.is_tablerows, head, foot, caption
Listblock.is_listitems (array of block arrays), numbered
Blockquoteblock.is_quoteblocks contains inner blocks
Thematic breakblock.is_breakRenders as <hr>
Section separatorblock.is_separator--- lines that split sections

​
Sections

Documents are automatically split into sections at --- separators or at heading boundaries. The render({ sections: true }) option wraps each section in a <section> element: 
const doc = parseNuemark(content)
const html = doc.render({
  sections: ['hero', 'features', 'pricing'],
  content_wrapper: 'container'
})
// Each <section> gets the matching class name
// Content inside is wrapped: <div class="container">…</div>

​
Front-matter

YAML front-matter is stripped before parsing and returned as doc.meta: 
---
title: My Page
description: A short description.
date: 2024-01-15
tags: [nue, web, dev]
---

# Content starts here

const doc = parseNuemark(content)
doc.meta.title        // 'My Page'
doc.meta.tags         // ['nue', 'web', 'dev']

Build docs developers (and LLMs) love

Get started for freeTalk to us