/** * 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; 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): 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(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(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('
\n'); ctx.pushIndent(); ctx.writeIndent(); ctx.sb.append('

'); ctx.escapeHtml(block.title); ctx.sb.append('

\n'); ctx.renderBlocks(block.blocks); ctx.popIndent(); ctx.writeIndent(); ctx.sb.append('
\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(1); transformers.push(new AlertsTransformer()); let renderers = new GrowableArray(1); renderers.push(new AlertsRenderer()); return new MarkdownExtension( new GrowableArray(0), new GrowableArray(0), new GrowableArray(0), transformers, renderers ); }