Wurd

An AI-enabled document compiler that turns markdown files into editorial-quality HTML. Powered by Pretext for typographic layout, KaTeX for math, and LLMs for AI-generated content. Implement your own plugins for unlimited versatility.

text.md ──→ wurd ──→ self-contained index.html
↑
plugins (math, graphs, tables, citations, ...)

Here's an example of what Wurd can produce:

Quick Start

# Install dependencies
npm install
# Compile the hello-world example (no API key needed)
npx tsx src/cli.ts examples/hello-world/text.md
# Open the output
open dist/hello-world/index.html

Installation

Global CLI

# From the repo directory:
npm install -g .# Now use it anywhere:
wurd path/to/text.md

Local (npx)

npx tsx src/cli.ts path/to/text.md

LLM Configuration

AI-driven plugins (graph, table) require an LLM. Create a .env file in the project root:

LLM_API_KEY=sk-...LLM_BASE_URL=https://api.anthropic.com/v1LLM_MODEL=claude-opus-4-6

Supports any OpenAI-compatible API. Without this, deterministic plugins (math, accordion, cite, binary-stream) still work fine.

Writing Documents

Documents are markdown files with optional frontmatter and plugin tags.

Frontmatter

YAML-style config between --- delimiters at the top of the file:

---columns: 2columnWidth: 500dropCap: trueaccentColor: '#7c6ee6'h1MaxFontSize: 120headingUnderline: 'subtitle'pointerEventsNone: 'title'---

Layout options:columns (1, 2, 3, or 'auto'), columnWidth, columnGap, maxContentWidth, gutter, narrowGutter, narrowBreakpoint

Heading options:h1MaxFontSize, h2MaxFontSize, h3MaxFontSize, h1MaxHeight, h2MaxHeight, h3MaxHeight, headingMinFontSize, headingLineHeightRatio, headingSpacingBelow, subheadingSpacingBelow, h1SpacingAbove, h2SpacingAbove, h3SpacingAbove

Spacing options:paragraphSpacing, listSpacing, rawSpacing, sectionGap, blockquoteSpacingAbove, blockquoteSpacingBelow

Typography:dropCap, dropCapLines, bodyFontSize, bodyLineHeight

Colors:bgColor, textColor, headingColor, accentColor, pullQuoteColor, pullQuoteBorderColor, headingUnderlineColor

Features:headingUnderline (comma-separated element IDs), pointerEventsNone (comma-separated element IDs), columnSpan (comma-separated: 'quotes', 'graphs', 'tables', 'math'), twoColumnMinWidth, threeColumnMinWidth

Open Graph / SEO:ogDescription, ogImage, ogUrl, ogType (default: 'article'), ogSiteName — generates <meta> tags for link previews on social media and messaging apps.

Plugin Tags

Inline:

The equation [plugin:math]x^2 + 1[/plugin] is simple.

Block:

[plugin:math]\[E = mc^2\][/plugin]

With config (key: value lines before content):

[plugin:binary-stream]
rows: 12
position: absolute
top: 80px
[/plugin]

Element IDs

Tag any heading with {#id} to reference it in frontmatter options:

# My Title {#title}## Subtitle {#subtitle}

Then use in frontmatter:

headingUnderline: 'subtitle'pointerEventsNone: 'title'

Blocks

Wrap content in [block]...[/block] to group elements that should stay together:

[block]
Some paragraph.
[plugin:math]\[x^2\][/plugin][/block]

Built-in Plugins

Plugin	Type	Description
math	Deterministic	KaTeX math rendering. Inline or block.
accordion	Deterministic	Expandable FAQ-style sections.
cite	Deterministic	Citations with auto-numbered references.
binary-stream	Deterministic	Decorative binary digit grid with mouse glow.
graph	LLM	AI-generated SVG charts from descriptions.
table	LLM	AI-generated HTML tables from descriptions.

Math

Inline: [plugin:math]x^2[/plugin]
Block:
[plugin:math]\[E = mc^2\][/plugin]

Accordion

[plugin:accordion]
Question one | Answer to question one.
Question two | Answer to question two.
[/plugin]

Citations

Some fact[plugin:cite]Author, "Title", Year, https://url[/plugin].

Automatically generates a numbered references section at the end.

Graph (requires LLM)

[plugin:graph]
Plot f(x) = x^2 as a smooth blue curve.
Data points at (1,1), (2,4), (3,9) as red circles.
Title: "Quadratic Function".
[/plugin]

Table (requires LLM)

[plugin:table]
A table with columns "Name" and "Value".
Row 1: Name = Alice, Value = 42
Row 2: Name = Bob, Value = 17
[/plugin]

Custom Plugins

Use --plugins <dir> to load plugins from an external directory:

wurd text.md --plugins ./my-plugins

Each plugin is either a name/index.ts folder or a standalone .ts file that default-exports a plugin object.

Deterministic Plugin

importtype{DeterministicPlugin}from'wurd/src/plugins.js'constmyPlugin: DeterministicPlugin={name: 'my-plugin',mode: 'deterministic',render(content: string,id: string): string{return`<div id="${id}">${content}</div>`},assets: {css: `.my-class { color: red; }`,},}exportdefaultmyPlugin

LLM Plugin

importtype{LLMPlugin}from'wurd/src/plugins.js'constmyPlugin: LLMPlugin={name: 'my-plugin',mode: 'llm',systemPrompt: 'You generate HTML from descriptions.',guidelines: 'Use dark theme colors.',extractContent(response: string): string{// Parse the LLM response and return HTMLreturnresponse},}exportdefaultmyPlugin

Plugin Assets

Plugins can declare CSS, head elements, and a browser-side runtime module:

assets: {css: `.my-class { color: white; }`,headElements: ['<link rel="stylesheet" href="...">'],runtimeModule: join(__dirname,'runtime.ts'),// bundled into the page}

CLI Options

wurd <path-to-markdown> [options]
Options:
--no-cache Skip LLM response cache (re-generate all AI content)
--pdf Generate a PDF alongside the HTML output (requires Puppeteer)
--plugins <dir> Load additional plugins from directory (repeatable)

Compiled pages include a download button (bottom-right corner) that opens the browser's "Save as PDF" dialog.

Project Structure

src/
cli.ts Entry point
parser.ts Markdown + plugin tag parser
plugins.ts Plugin loader and executor
template.ts HTML page template
llm.ts LLM client with caching
runtime/
layout.ts Pretext-powered editorial layout engine
main.ts Browser runtime entry
plugins/
accordion/ Expandable sections
binary-stream/ Decorative binary grid
cite/ Citation references
graph/ LLM-generated charts
math/ KaTeX math
table/ LLM-generated tables
examples/
hello-world/ Minimal example (no LLM needed)
zippy/ Full-featured article

Output

The compiler produces a self-contained HTML file in dist/<dir-name>/index.html. Everything — CSS, JavaScript, plugin output — is inlined. No external dependencies at runtime except optional CDN links (e.g. KaTeX fonts).

Recommended Editors

Wurd documents are just markdown files, so any editor works. A few that make the writing experience nicer:

• VS Code with Rich Markdown Editor — WYSIWYG-style editing with live preview
• Typora — clean, distraction-free markdown editor with inline rendering
• iA Writer — focused writing with syntax highlighting and content blocks
• Obsidian — good for organizing multiple documents with wiki-style linking