@weave-md/basic

@weave-md/basic

CLI and exporter for Weave Markdown.

Installation

pnpm add @weave-md/basic

CLI

Export

weave-md-basic export html --entry=intro   # Export to HTML
weave-md-basic export ast                  # Export to JSON AST

HTML entry point: If exactly one .md file exists in the root directory, --entry is auto-detected:

weave-md-basic export html

Output: Use --out to specify output directory:

weave-md-basic export html --out=./build

Validate

weave-md-basic validate              # Check for errors
weave-md-basic validate --strict     # Exit 1 on errors
weave-md-basic validate --json       # JSON output

Help

weave-md-basic help

Programmatic Usage

import { loadWorkspace, exportToStaticHtml, parseToMdast } from '@weave-md/basic';

// Load sections from directory
const { sections, rawContent } = await loadWorkspace('./content');

// Parse to mdast trees
const trees = new Map();
for (const section of sections) {
  const content = rawContent.get(section.id);
  if (content) {
    const { tree } = parseToMdast(content);
    trees.set(section.id, tree);
  }
}

// Export to static HTML
const html = exportToStaticHtml(sections, trees, { title: 'My Document' });

API

loadWorkspace(path, options?)

Load sections from .md files with valid frontmatter. Recursively scans directories and subfolders.

• options.files - Load specific files only
• options.extensions - File extensions (default: ['.md'])
• options.exclude - Directories to skip (default: ['node_modules', '.git'])

Returns { sections, filePaths, rawContent }.

exportToStaticHtml(sections, trees, options?)

Generate a complete HTML document with footnotes and overlay support.

• options.title - Document title
• options.entry - Entry section ID (only renders this section and its references)

Display Modes

• footnote (default) - Numbered references at bottom
• inline - Expandable content inserted after paragraph
• overlay - Click to show tooltip preview

Nesting Rules

This renderer enforces the following nesting restrictions:

Context	Allowed Node Links
Main content	footnote, inline, overlay
Inside footnote	overlay only
Inside inline	overlay only
Inside overlay	none (plain text)

Node links inside footnotes and inline content are converted to overlays. Overlays cannot contain further interactive links.

License

MIT