/** * 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, 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, * ``, 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(4); var #resolver: UrlResolver = new KeepUrls(); var #headingLinks = false; new(options: HtmlRenderOptions = {}) { let {safe = false, escapeRawHtml = false, softBreak = '\n', indent = 0, extensions = new GrowableArray( 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): 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('

'); } else { this.sb.append('

'); }; this.renderInlines(inlines); this.sb.append('

\n'); } case Heading {level, inlines, id}: { this.writeIndent(); this.sb.append(''); this.renderInlines(inlines); if (id != null && this.#headingLinks) { this.sb.append('
#'); }; this.sb.append('\n'); } case BlockQuote {blocks}: { this.writeIndent(); this.sb.append('
\n'); this.pushIndent(); this.renderBlocks(blocks); this.popIndent(); this.writeIndent(); this.sb.append('
\n'); } case ListBlock {ordered, startNumber, tight, items}: { this.writeIndent(); if (ordered) { if (startNumber != 1) { this.sb.append('
    \n'); } else { this.sb.append('
      \n'); }; } else { this.sb.append('
        \n'); }; this.pushIndent(); for (let item in items) { this.#renderListItem(item, tight); } this.popIndent(); this.writeIndent(); if (ordered) { this.sb.append('
    \n'); } else { this.sb.append('\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('
    ');
            } else {
              this.sb.append('
    ');
            };
            this.escapeHtml(literal);
            this.sb.append('
    \n'); } case IndentedCodeBlock {literal}: { this.writeIndent(); this.sb.append('
    ');
            this.escapeHtml(literal);
            this.sb.append('
    \n'); } case HtmlBlock {literal}: { if (this.safe) { if (this.escapeRawHtml) { this.writeIndent(); this.sb.append('

    '); this.escapeHtml(literal); this.sb.append('

    \n'); }; } else { this.writeIndent(); this.sb.append(literal); this.sb.appendByte(0x0A); }; } case ThematicBreak: { this.writeIndent(); this.sb.append('
    \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('
  1. '); } else { this.sb.append('
  2. '); } let checkboxHtml = if (isChecked) ' ' else ' '; if (item.blocks.length == 0) { if (hasCheckbox) { this.sb.append(checkboxHtml); } this.sb.append('
  3. \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('\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('

    '); } else { this.sb.append('

    '); } this.sb.append(checkboxHtml); this.renderInlines(inlines); this.sb.append('

    \n'); idx += 1; continue; } this.writeIndent(); this.sb.append(checkboxHtml); } this.renderBlock(child); idx += 1; } this.popIndent(); this.writeIndent(); this.sb.append('\n'); } renderInlines(nodes: GrowableArray): 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(''); this.escapeHtml(literal); this.sb.append(''); } case Emphasis {children}: { this.sb.append(''); this.renderInlines(children); this.sb.append(''); } case Strong {children}: { this.sb.append(''); this.renderInlines(children); this.sb.append(''); } case Link {destination: let written, title, children}: { let destination = this.#resolver.resolve(written, false); if (destination == null) { this.renderInlines(children); return; }; this.sb.append(''); this.renderInlines(children); this.sb.append(''); } case Image {destination: let written, title, children}: { let destination = this.#resolver.resolve(written, true); if (destination == null) { return; }; this.sb.append('');
        let altSb = new StringBuilder(32);
        appendInlinesPlainText(children, altSb);
        this.escapeAttribute(altSb.toString());
        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(''); this.escapeHtml(label); this.sb.append(''); } 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('
    \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); }