markdown 0.0.1-preview.1
CommonMark and GFM Markdown parser, AST, plugin system, and HTML renderer
Markdown (@zena-lang/markdown)#
A CommonMark and GitHub Flavored Markdown (GFM) parser, syntax tree, plugin
system, and HTML renderer written in Zena (zena-lang:markdown/<library>).
See docs/design/markdown.md for the design.
Usage#
Add it with zena pkg add zena-lang:markdown, then import its main
library:
import {
parse, renderHtml, markdownToHtml, gfmExtensions
} from 'zena-lang:markdown';
// Render CommonMark + GFM to safe HTML (raw HTML stripped, unsafe URLs blocked)
let html = markdownToHtml('# Hello\n\nSome ~~old~~ **new** text.', {
extensions: gfmExtensions(),
safe: true,
});
// Or parse to an AST first
let doc = parse('# Heading\n\nParagraph.', gfmExtensions());
let out = renderHtml(doc, {safe: true, extensions: gfmExtensions()});
Running Tests#
npm test -w @zena-lang/markdown
npm run test:quick -- packages/markdown/test
8.0 KiB
Raw
/**
* Plugin and extension interfaces for `markdown`.
*
* Extensions hook into five points of the pipeline:
* 1. `BlockParserFactory` (Phase 1: line-by-line block structure)
* 2. `DelimiterProcessor` (Phase 2: paired inline delimiters on the delimiter stack)
* 3. `InlineContentParser` (Phase 2: trigger-byte inline scanners)
* 4. `AstTransformer` (Phase 3: post-parse AST transformations)
* 5. `NodeRenderer` (Phase 4: rendering `CustomBlock` and `CustomInline` nodes)
*/
import {Array, GrowableArray, StringBuilder} from 'zena:core';
import {Block, CustomBlock, Inline, CustomInline, Document, LinkDef, Span} from './ast.zena';
import {HashMap} from 'zena:collections';
/**
* Runner interface passed to blocks and transformers that need to parse inline
* Markdown text using the document's active link definitions and inline
* plugins.
*/
export interface InlineParserRunner {
parse(text: String, baseOffset: i32): GrowableArray<Inline>;
links: HashMap<String, LinkDef>;
}
/**
* Snapshot of the current line and cursor during Phase 1 block parsing.
*/
export final class BlockLineState(source: String, line: String, lineStartOffset: i32, var index: i32, var column: i32, var nextNonSpaceIndex: i32, var nextNonSpaceColumn: i32, var indent: i32, var isBlank: boolean)
/**
* Information about the currently open tip block when trying to start a new
* child block.
*/
export final class MatchedBlockInfo(isParagraph: boolean, paragraphLines: GrowableArray<String> | null, paragraphStartOffset: i32)
/**
* Result of `CustomBlockParser.tryContinue`.
*/
export final class BlockContinue(matched: boolean, newIndex: i32, newColumn: i32, finalize: boolean) {
static none(): BlockContinue {
return new BlockContinue(false, -1, -1, false);
}
static atIndex(newIndex: i32): BlockContinue {
return new BlockContinue(true, newIndex, -1, false);
}
static atColumn(newColumn: i32): BlockContinue {
return new BlockContinue(true, -1, newColumn, false);
}
static finished(): BlockContinue {
return new BlockContinue(true, -1, -1, true);
}
}
/**
* A stateful parser for a custom block opened by a `BlockParserFactory`.
*/
export interface CustomBlockParser {
/** Whether this block can accept raw content lines via `addLine`. */
acceptsLines(): boolean;
/**
* Checks whether this open block continues on `state`.
*/
tryContinue(state: BlockLineState): BlockContinue;
/**
* Appends the remaining slice of the current line to this block.
*/
addLine(line: String, startOffset: i32): void;
/**
* Runs Phase 2 inline parsing on any text accumulated inside this block.
*/
parseInlines(inlineParser: InlineParserRunner): void;
/**
* Finalizes the block at `endOffset` and returns the resulting AST `Block`.
*/
closeBlock(endOffset: i32): Block;
}
/**
* Result of `BlockParserFactory.tryStart` when a custom block matches.
*/
export final class CustomBlockStart(parser: CustomBlockParser, newIndex: i32, newColumn: i32, replaceParagraph: boolean) {
static of(parser: CustomBlockParser): CustomBlockStart {
return new CustomBlockStart(parser, -1, -1, false);
}
atIndex(newIndex: i32): CustomBlockStart {
return new CustomBlockStart(
this.parser,
newIndex,
this.newColumn,
this.replaceParagraph
);
}
atColumn(newColumn: i32): CustomBlockStart {
return new CustomBlockStart(
this.parser,
this.newIndex,
newColumn,
this.replaceParagraph
);
}
replacingParagraph(): CustomBlockStart {
return new CustomBlockStart(
this.parser,
this.newIndex,
this.newColumn,
true
);
}
}
/**
* Phase 1 extension point: starts a custom block on a line.
*/
export interface BlockParserFactory {
/**
* ASCII starter bytes (`< 128`) that can begin this block at
* `state.nextNonSpaceIndex`, or an empty array if this factory can
* start on any non-space byte.
*/
triggerBytes(): Array<i32>;
/**
* Inspects `state` and `matched` and returns a `CustomBlockStart` when a new
* block begins, or `null` otherwise.
*/
tryStart(state: BlockLineState, matched: MatchedBlockInfo): CustomBlockStart | null;
}
/**
* Metadata for an opening or closing delimiter run on the Phase 2 delimiter
* stack.
*/
export final class DelimiterRunInfo(delimiterByte: i32, length: i32, originalLength: i32, canOpen: boolean, canClose: boolean, startOffset: i32, endOffset: i32)
/**
* Phase 2 extension point: processes paired inline delimiters (such as `~~`
* for strikethrough) using CommonMark's delimiter stack.
*/
export interface DelimiterProcessor {
/** ASCII byte (`< 128`) that opens the delimiter pair. */
openingByte(): i32;
/** ASCII byte (`< 128`) that closes the delimiter pair. */
closingByte(): i32;
/** Minimum run length required to trigger `process`. */
minLength(): i32;
/**
* Inspects `opener` and `closer` and the `children` between them.
*
* Returns `(usedCount, node)` where `usedCount` (`> 0`) is the number of
* delimiter characters consumed from both `opener` and `closer` and `node`
* is the replacement `Inline` node, or `(0, null)` when the runs do not
* form a valid delimiter pair.
*/
process(opener: DelimiterRunInfo, closer: DelimiterRunInfo, children: GrowableArray<Inline>): inline (i32, Inline | null);
}
/**
* Result of `InlineContentParser.tryParse`.
*/
export final class InlineMatch(node: Inline, nextIndex: i32)
/**
* Phase 2 extension point: scans an inline construct starting at one of its
* declared `triggerBytes`.
*/
export interface InlineContentParser {
/** Non-empty array of ASCII starter bytes (`< 128`). */
triggerBytes(): Array<i32>;
/**
* Attempts to parse an inline node starting at `index` in `source` (where
* `baseOffset` is the byte offset of `source` in the document and
* `precedingByte` is the byte at `index - 1`, or `-1` at index 0).
*/
tryParse(source: String, baseOffset: i32, index: i32, precedingByte: i32, inlineParser: InlineParserRunner): InlineMatch | null;
}
/**
* Phase 3 extension point: transforms the `Document` AST after block and
* inline parsing complete.
*/
export interface AstTransformer {
transform(doc: Document, inlineParser: InlineParserRunner): void;
}
/**
* Context passed to `NodeRenderer` plugins during HTML rendering.
*/
export interface HtmlRenderContext {
sb: StringBuilder;
safe: boolean;
escapeRawHtml: boolean;
pushIndent(): void;
popIndent(): void;
writeIndent(): void;
renderBlock(block: Block): void;
renderBlocks(blocks: GrowableArray<Block>): void;
renderInline(node: Inline): void;
renderInlines(nodes: GrowableArray<Inline>): void;
escapeHtml(text: String): void;
escapeAttribute(text: String): void;
isSafeUrl(url: String, isImage: boolean): boolean;
}
/**
* Phase 4 extension point: renders `CustomBlock` and `CustomInline` nodes to
* HTML.
*/
export interface NodeRenderer {
renderBlock(block: CustomBlock, ctx: HtmlRenderContext): boolean;
renderInline(node: CustomInline, ctx: HtmlRenderContext): boolean;
}
/**
* Bundles any combination of block factories, delimiter processors, inline
* parsers, AST transformers, and node renderers into one registrable unit.
*/
export final class MarkdownExtension {
blockFactories: GrowableArray<BlockParserFactory>;
delimiterProcessors: GrowableArray<DelimiterProcessor>;
inlineParsers: GrowableArray<InlineContentParser>;
astTransformers: GrowableArray<AstTransformer>;
nodeRenderers: GrowableArray<NodeRenderer>;
new(blockFactories: GrowableArray<BlockParserFactory> = new GrowableArray<BlockParserFactory>(
0
), delimiterProcessors: GrowableArray<DelimiterProcessor> = new GrowableArray<DelimiterProcessor>(
0
), inlineParsers: GrowableArray<InlineContentParser> = new GrowableArray<InlineContentParser>(
0
), astTransformers: GrowableArray<AstTransformer> = new GrowableArray<AstTransformer>(
0
), nodeRenderers: GrowableArray<NodeRenderer> = new GrowableArray<NodeRenderer>(
0
)) : blockFactories = blockFactories, delimiterProcessors = delimiterProcessors, inlineParsers = inlineParsers, astTransformers = astTransformers, nodeRenderers = nodeRenderers {}
}
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 | none |
|