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
5.4 KiB
Raw
/**
* GitHub alerts / notes extension (`> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`,
* `> [!WARNING]`, `> [!CAUTION]`).
*/
import {GrowableArray} from 'zena:core';
import {Block, CustomBlock, CustomInline, Document, Inline, Paragraph, BlockQuote, ListBlock, ListItem, Text, SoftBreak, HardBreak, Span} from '../ast.zena';
import {AstTransformer, BlockParserFactory, DelimiterProcessor, HtmlRenderContext, InlineContentParser, InlineParserRunner, MarkdownExtension, NodeRenderer} from '../plugin.zena';
import {trimSpaces} from '../scanner.zena';
/**
* The five GitHub alert levels.
*/
export enum AlertKind {
Note,
Tip,
Important,
Warning,
Caution
}
/**
* AST block node representing a GitHub alert block (`> [!NOTE] ...`).
*/
export final class AlertBlock extends CustomBlock {
kind: AlertKind;
kindSlug: String;
title: String;
var blocks: GrowableArray<Block>;
new(this.kind, this.kindSlug, this.title, this.blocks, span: Span) : super(span) {}
}
final class AlertsTransformer implements AstTransformer {
transform(doc: Document, inlineParser: InlineParserRunner): void {
this.#transformBlockList(doc.blocks);
}
#transformBlockList(blocks: GrowableArray<Block>): void {
var i = 0;
while (i < blocks.length) {
let block = blocks[i];
match (block) {
case BlockQuote as bq: {
this.#transformBlockList(bq.blocks);
let converted = this.#tryConvertBlockQuote(bq);
if (converted != null) {
blocks[i] = converted;
};
}
case ListBlock {items}: {
for (let item in items) {
this.#transformBlockList(item.blocks);
}
}
case ListItem {blocks: let children}: {
this.#transformBlockList(children);
}
case _: {}
};
i += 1;
}
}
#tryConvertBlockQuote(bq: BlockQuote): AlertBlock | null {
if (bq.blocks.length == 0) {
return null;
}
if (let Paragraph {inlines as firstInlines, id as firstId, span as firstSpan} = bq.blocks[0]) {
if (firstInlines.length == 0) {
return null;
}
if (let Text {literal} = firstInlines[0]) {
let trimmed = trimSpaces(literal);
let (matched, kind, slug, defaultTitle) = parseAlertMarker(trimmed);
if (!matched) {
return null;
}
// Marker must be the entire first Text inline (meaning either the end
// of the paragraph or immediately followed by a SoftBreak / HardBreak)
if (firstInlines.length > 1) {
let second = firstInlines[1];
if (!(second is SoftBreak) && !(second is HardBreak)) {
return null;
}
}
// Remove the marker Text and optional line break from `firstPara`
let remainingInlines = new GrowableArray<Inline>(firstInlines.length);
var k = 2; // skip index 0 (`[!KIND]`) and index 1 (`SoftBreak`/`HardBreak`)
while (k < firstInlines.length) {
remainingInlines.push(firstInlines[k]);
k += 1;
}
let alertChildren = new GrowableArray<Block>(bq.blocks.length);
if (remainingInlines.length > 0) {
alertChildren.push(
new Paragraph(remainingInlines, firstId, firstSpan)
);
}
var bIdx = 1;
while (bIdx < bq.blocks.length) {
alertChildren.push(bq.blocks[bIdx]);
bIdx += 1;
}
return new AlertBlock(kind, slug, defaultTitle, alertChildren, bq.span);
}
}
return null;
}
}
function parseAlertMarker(s: String): inline (boolean, AlertKind, String, String) {
let lower = s.asciiLowerCase();
if (lower == '[!note]') {
return (true, AlertKind.Note, 'note', 'Note');
}
if (lower == '[!tip]') {
return (true, AlertKind.Tip, 'tip', 'Tip');
}
if (lower == '[!important]') {
return (true, AlertKind.Important, 'important', 'Important');
}
if (lower == '[!warning]') {
return (true, AlertKind.Warning, 'warning', 'Warning');
}
if (lower == '[!caution]') {
return (true, AlertKind.Caution, 'caution', 'Caution');
}
return (false, AlertKind.Note, '', '');
}
final class AlertsRenderer implements NodeRenderer {
renderBlock(block: CustomBlock, ctx: HtmlRenderContext): boolean {
if (block is AlertBlock) {
ctx.writeIndent();
ctx.sb.append('<div class="markdown-alert markdown-alert-');
ctx.escapeAttribute(block.kindSlug);
ctx.sb.append('">\n');
ctx.pushIndent();
ctx.writeIndent();
ctx.sb.append('<p class="markdown-alert-title">');
ctx.escapeHtml(block.title);
ctx.sb.append('</p>\n');
ctx.renderBlocks(block.blocks);
ctx.popIndent();
ctx.writeIndent();
ctx.sb.append('</div>\n');
return true;
}
return false;
}
renderInline(node: CustomInline, ctx: HtmlRenderContext): boolean {
return false;
}
}
/**
* Returns the `MarkdownExtension` for GitHub alerts (`> [!NOTE]`, `> [!TIP]`,
* `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]`).
*/
export function alertsExtension(): MarkdownExtension {
let transformers = new GrowableArray<AstTransformer>(1);
transformers.push(new AlertsTransformer());
let renderers = new GrowableArray<NodeRenderer>(1);
renderers.push(new AlertsRenderer());
return new MarkdownExtension(
new GrowableArray<BlockParserFactory>(0),
new GrowableArray<DelimiterProcessor>(0),
new GrowableArray<InlineContentParser>(0),
transformers,
renderers
);
}
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 | none |
|