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
15.6 KiB
Raw
/**
* HTML renderer for `Document` ASTs with `safe` sanitization mode, optional
* indentation tracking, and `NodeRenderer` extension dispatch.
*/
import {GrowableArray, Some} from 'zena:core';
import {StringBuilder, StringReader, isAsciiWhitespace} from 'zena:string';
import {URL} from 'zena:url';
import {Block, CustomBlock, Document, Inline, CustomInline, Paragraph, Heading, BlockQuote, ListBlock, ListItem, FencedCodeBlock, IndentedCodeBlock, HtmlBlock, ThematicBreak, Text, CodeSpan, Emphasis, Strong, Link, Image, Autolink, HtmlInline, SoftBreak, HardBreak, appendInlinesPlainText} from './ast.zena';
import {HtmlRenderContext, MarkdownExtension, NodeRenderer} from './plugin.zena';
/**
* Options controlling HTML rendering and sanitization.
*/
export type HtmlRenderOptions = {safe?: boolean, escapeRawHtml?: boolean, softBreak?: String, indent?: i32, extensions?: GrowableArray<MarkdownExtension>, resolver?: UrlResolver, headingLinks?: boolean};
/**
* Rewrites the URL of each link, image and autolink before it is rendered,
* such as to put a document's relative links under the address it is
* served at (`HtmlRenderOptions.resolver`). `safe` mode checks the URL it
* returns.
*/
export interface UrlResolver {
/**
* The URL to render for `url`, or null to leave it out: a link is
* rendered as its text alone, and an image not at all.
*/
resolve(url: String, isImage: boolean): String | null;
}
/** The resolver that keeps every URL as it is written, which `HtmlRenderOptions` defaults to. */
final class KeepUrls implements UrlResolver {
resolve(url: String, isImage: boolean): String | null {
return url;
}
}
/**
* When `true`, raw HTML (`HtmlBlock`, `HtmlInline`) is omitted (or escaped
* if `escapeRawHtml` is also `true`) and link/image URLs are checked with
* `isSafeUrl`.
*/
/**
* When `true` alongside `safe: true`, raw HTML blocks and inline HTML are
* rendered as escaped text rather than dropped.
*/
/** String emitted for `SoftBreak` nodes (default `"\n"`). */
/**
* Number of spaces per indentation level for nested block containers
* (default `0` for compact CommonMark output).
*/
/** Extensions supplying `NodeRenderer` implementations. */
/** Rewrites or removes link and image URLs (`UrlResolver`). */
/**
* When `true`, a heading with an `id` ends with a `#` link to itself,
* `<a class="heading-link">`, for a reader to copy (default `false`).
*/
/**
* Renders `doc` to an HTML string.
*/
export function renderHtml(doc: Document, options: HtmlRenderOptions = {}): String {
let renderer = new HtmlRenderer(options);
return renderer.render(doc);
}
/**
* Checks whether `url` uses a safe scheme (or is a relative reference).
*
* Allows relative references (`/`, `./`, `../`, `#`, `?`, or paths with no `:`
* before the first `/`, `?`, or `#`). When a scheme is present, allows `http:`
* and `https:` for both links and images, safe `data:image/*` rasters, and
* `mailto:`, `irc:`, `ircs:`, and `xmpp:` for links. Rejects `javascript:`,
* `vbscript:`, `data:text/html`, and other schemes.
*/
export function isSafeUrl(url: String, isImage: boolean = false): boolean {
let parsed = URL.parse(url, 'relative://base/');
if (parsed == null) {
return false;
}
let proto = parsed.protocol;
if (proto == 'relative:') {
// Ensure no obfuscated scheme colon precedes '/', '?', or '#'
let r = new StringReader(url);
while (!r.isAtEnd) {
let cp = r.advance();
if (cp == 0x2F || cp == 0x3F || cp == 0x23) {
// /, ?, #
return true;
}
if (cp == 0x3A) {
// :
return false;
}
}
return true;
}
if (proto == 'http:' || proto == 'https:') {
return true;
}
if (proto == 'data:') {
let body = parsed.pathname.asciiLowerCase();
return body.startsWith('image/png;')
|| body.startsWith('image/gif;')
|| body.startsWith('image/jpeg;')
|| body.startsWith('image/webp;');
}
return !isImage
&& (proto == 'mailto:'
|| proto == 'irc:'
|| proto == 'ircs:'
|| proto == 'xmpp:');
}
/**
* Stateful HTML renderer implementing `HtmlRenderContext`.
*/
export final class HtmlRenderer implements HtmlRenderContext {
sb = new StringBuilder(256);
var safe = false;
var escapeRawHtml = false;
var #softBreak = '\n';
var #indentStep = 0;
var #indentLevel = 0;
#renderers = new GrowableArray<NodeRenderer>(4);
var #resolver: UrlResolver = new KeepUrls();
var #headingLinks = false;
new(options: HtmlRenderOptions = {}) {
let {safe = false, escapeRawHtml = false, softBreak = '\n', indent = 0, extensions = new GrowableArray<MarkdownExtension>(
0
), resolver = new KeepUrls(), headingLinks = false} = options;
this.#resolver = resolver;
this.#headingLinks = headingLinks;
this.safe = safe;
this.escapeRawHtml = escapeRawHtml;
this.#softBreak = softBreak;
this.#indentStep = if (indent > 0) indent else 0;
for (let ext in extensions) {
for (let r in ext.nodeRenderers) {
this.#renderers.push(r);
}
}
}
pushIndent(): void {
this.#indentLevel += 1;
}
popIndent(): void {
if (this.#indentLevel > 0) {
this.#indentLevel -= 1;
}
}
writeIndent(): void {
let spaces = this.#indentLevel * this.#indentStep;
var i = 0;
while (i < spaces) {
this.sb.appendByte(0x20);
i += 1;
}
}
render(doc: Document): String {
this.sb.clear();
this.#indentLevel = 0;
this.renderBlocks(doc.blocks);
return this.sb.toString();
}
renderBlocks(blocks: GrowableArray<Block>): void {
for (let block in blocks) {
this.renderBlock(block);
}
}
renderBlock(block: Block): void {
match (block) {
case Paragraph {inlines, id}: {
this.writeIndent();
if (id != null) {
this.sb.append('<p id="');
this.escapeAttribute(id);
this.sb.append('">');
} else {
this.sb.append('<p>');
};
this.renderInlines(inlines);
this.sb.append('</p>\n');
}
case Heading {level, inlines, id}: {
this.writeIndent();
this.sb.append('<h');
this.sb.appendI32(level);
if (id != null) {
this.sb.append(' id="');
this.escapeAttribute(id);
this.sb.append('"');
};
this.sb.append('>');
this.renderInlines(inlines);
if (id != null && this.#headingLinks) {
this.sb.append('<a class="heading-link" href="#');
this.escapeAttribute(id);
this.sb.append('" aria-label="Link to this heading">#</a>');
};
this.sb.append('</h');
this.sb.appendI32(level);
this.sb.append('>\n');
}
case BlockQuote {blocks}: {
this.writeIndent();
this.sb.append('<blockquote>\n');
this.pushIndent();
this.renderBlocks(blocks);
this.popIndent();
this.writeIndent();
this.sb.append('</blockquote>\n');
}
case ListBlock {ordered, startNumber, tight, items}: {
this.writeIndent();
if (ordered) {
if (startNumber != 1) {
this.sb.append('<ol start="');
this.sb.appendI32(startNumber);
this.sb.append('">\n');
} else {
this.sb.append('<ol>\n');
};
} else {
this.sb.append('<ul>\n');
};
this.pushIndent();
for (let item in items) {
this.#renderListItem(item, tight);
}
this.popIndent();
this.writeIndent();
if (ordered) {
this.sb.append('</ol>\n');
} else {
this.sb.append('</ul>\n');
};
}
case ListItem as item: {
this.#renderListItem(item, false);
}
case FencedCodeBlock {info, literal}: {
this.writeIndent();
let lang = firstWord(info);
if (!lang.isEmpty) {
this.sb.append('<pre><code class="language-');
this.escapeAttribute(lang);
this.sb.append('">');
} else {
this.sb.append('<pre><code>');
};
this.escapeHtml(literal);
this.sb.append('</code></pre>\n');
}
case IndentedCodeBlock {literal}: {
this.writeIndent();
this.sb.append('<pre><code>');
this.escapeHtml(literal);
this.sb.append('</code></pre>\n');
}
case HtmlBlock {literal}: {
if (this.safe) {
if (this.escapeRawHtml) {
this.writeIndent();
this.sb.append('<p>');
this.escapeHtml(literal);
this.sb.append('</p>\n');
};
} else {
this.writeIndent();
this.sb.append(literal);
this.sb.appendByte(0x0A);
};
}
case ThematicBreak: {
this.writeIndent();
this.sb.append('<hr />\n');
}
case CustomBlock as custom: {
for (let renderer in this.#renderers) {
if (renderer.renderBlock(custom, this)) {
return;
}
}
}
};
}
#renderListItem(item: ListItem, tight: boolean): void {
var hasCheckbox = false;
var isChecked = false;
if (let Some {value} = item.checked) {
hasCheckbox = true;
isChecked = value;
}
this.writeIndent();
if (hasCheckbox) {
this.sb.append('<li class="task-list-item">');
} else {
this.sb.append('<li>');
}
let checkboxHtml = if (isChecked) '<input type="checkbox" disabled="" checked="" /> ' else '<input type="checkbox" disabled="" /> ';
if (item.blocks.length == 0) {
if (hasCheckbox) {
this.sb.append(checkboxHtml);
}
this.sb.append('</li>\n');
return;
}
if (tight) {
var idx = 0;
var indentedBody = false;
while (idx < item.blocks.length) {
let child = item.blocks[idx];
if (let Paragraph {inlines} = child) {
if (idx == 0 && hasCheckbox) {
this.sb.append(checkboxHtml);
} else if (idx > 0) {
this.writeIndent();
}
this.renderInlines(inlines);
if (idx + 1 < item.blocks.length) {
this.sb.appendByte(0x0A);
if (!indentedBody) {
this.pushIndent();
indentedBody = true;
}
}
} else {
if (idx == 0) {
if (hasCheckbox) {
this.sb.append(checkboxHtml);
}
this.sb.appendByte(0x0A);
this.pushIndent();
indentedBody = true;
}
this.renderBlock(child);
}
idx += 1;
}
if (indentedBody) {
this.popIndent();
if (!(item.blocks[item.blocks.length - 1] is Paragraph)) {
this.writeIndent();
}
}
this.sb.append('</li>\n');
return;
}
this.sb.appendByte(0x0A);
this.pushIndent();
var idx = 0;
while (idx < item.blocks.length) {
let child = item.blocks[idx];
if (idx == 0 && hasCheckbox) {
if (let Paragraph {inlines, id} = child) {
this.writeIndent();
if (id != null) {
this.sb.append('<p id="');
this.escapeAttribute(id);
this.sb.append('">');
} else {
this.sb.append('<p>');
}
this.sb.append(checkboxHtml);
this.renderInlines(inlines);
this.sb.append('</p>\n');
idx += 1;
continue;
}
this.writeIndent();
this.sb.append(checkboxHtml);
}
this.renderBlock(child);
idx += 1;
}
this.popIndent();
this.writeIndent();
this.sb.append('</li>\n');
}
renderInlines(nodes: GrowableArray<Inline>): void {
for (let node in nodes) {
this.renderInline(node);
}
}
renderInline(node: Inline): void {
match (node) {
case Text {literal}: {
this.escapeHtml(literal);
}
case CodeSpan {literal}: {
this.sb.append('<code>');
this.escapeHtml(literal);
this.sb.append('</code>');
}
case Emphasis {children}: {
this.sb.append('<em>');
this.renderInlines(children);
this.sb.append('</em>');
}
case Strong {children}: {
this.sb.append('<strong>');
this.renderInlines(children);
this.sb.append('</strong>');
}
case Link {destination: let written, title, children}: {
let destination = this.#resolver.resolve(written, false);
if (destination == null) {
this.renderInlines(children);
return;
};
this.sb.append('<a href="');
if (!this.safe || this.isSafeUrl(destination, false)) {
this.escapeAttribute(destination);
};
this.sb.append('"');
if (!title.isEmpty) {
this.sb.append(' title="');
this.escapeAttribute(title);
this.sb.append('"');
};
this.sb.append('>');
this.renderInlines(children);
this.sb.append('</a>');
}
case Image {destination: let written, title, children}: {
let destination = this.#resolver.resolve(written, true);
if (destination == null) {
return;
};
this.sb.append('<img src="');
if (!this.safe || this.isSafeUrl(destination, true)) {
this.escapeAttribute(destination);
};
this.sb.append('" alt="');
let altSb = new StringBuilder(32);
appendInlinesPlainText(children, altSb);
this.escapeAttribute(altSb.toString());
this.sb.append('"');
if (!title.isEmpty) {
this.sb.append(' title="');
this.escapeAttribute(title);
this.sb.append('"');
};
this.sb.append(' />');
}
case Autolink {destination: let written, label}: {
let destination = this.#resolver.resolve(written, false);
if (destination == null) {
this.escapeHtml(label);
return;
};
this.sb.append('<a href="');
if (!this.safe || this.isSafeUrl(destination, false)) {
this.escapeAttribute(destination);
};
this.sb.append('">');
this.escapeHtml(label);
this.sb.append('</a>');
}
case HtmlInline {literal}: {
if (this.safe) {
if (this.escapeRawHtml) {
this.escapeHtml(literal);
};
} else {
this.sb.append(literal);
};
}
case SoftBreak: {
this.sb.append(this.#softBreak);
}
case HardBreak: {
this.sb.append('<br />\n');
}
case CustomInline as custom: {
for (let renderer in this.#renderers) {
if (renderer.renderInline(custom, this)) {
return;
}
}
}
};
}
escapeHtml(text: String): void {
let r = new StringReader(text);
var last = r.mark();
while (!r.isAtEnd) {
let pos = r.mark();
let cp = r.advance();
let entity = if (cp == 0x26) {
'&';
} else if (cp == 0x3C) {
'<';
} else if (cp == 0x3E) {
'>';
} else if (cp == 0x22) {
'"';
} else {
null;
};
if (entity != null) {
if (pos > last) {
this.sb.append(r.sliceRange(last, pos));
}
this.sb.append(entity);
last = r.mark();
}
}
if (last == 0) {
this.sb.append(text);
} else if (last < r.mark()) {
this.sb.append(r.sliceFrom(last));
}
}
escapeAttribute(text: String): void {
this.escapeHtml(text);
}
isSafeUrl(url: String, isImage: boolean): boolean {
return isSafeUrl(url, isImage);
}
}
function firstWord(s: String) {
let r = new StringReader(s);
let start = r.mark();
r.skipWhile((cp) => !isAsciiWhitespace(cp));
return r.sliceFrom(start);
}
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 | none |
|