markdown 0.0.1-preview.1

CommonMark and GFM Markdown parser, AST, plugin system, and HTML renderer

Readme Files Dependencies Versions

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) {
        '&amp;';
      } else if (cp == 0x3C) {
        '&lt;';
      } else if (cp == 0x3E) {
        '&gt;';
      } else if (cp == 0x22) {
        '&quot;';
      } 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);
}
none
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19 none