@rse/specbook 0.9.2

package/dst/specbook-export-html.d.ts

@@ -0,0 +1,9 @@
+import type { Specification } from "./specbook-struct-spec.js";
+import type { SchemaSpecification } from "./specbook-struct-schema.js";
+export type OutlineEntry = {
+    title: string;
+    anchor: string;
+    childs: OutlineEntry[];
+};
+export declare const htmlOutline: (specification: Specification, maxColumns: number) => OutlineEntry[];
+export declare const renderHtml: (specification: Specification, maxColumns: number, config?: SchemaSpecification, tocPages?: Map<string, number>, css?: string) => Promise<string>;

package/dst/specbook-export-html.js

@@ -0,0 +1,452 @@
+/*
+**  Specification Book (SpecBook)
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import { marked } from "marked";
+import { markedSmartypants } from "marked-smartypants";
+import nunjucks from "nunjucks";
+import nunjucksAddons from "@rse/nunjucks-addons";
+import textframe from "textframe";
+import { Gradia } from "@rse/gradia";
+import { buildLinkIndex, resolveUnique, expandReferences, anchorPaths } from "./specbook-link.js";
+import { compileValueExpr, splitItems } from "./specbook-parse-value.js";
+import { embeddingRegex, embeddingMimeType } from "./specbook-parse-common.js";
+import { escapeHtml, stylesheet, searchScript, fallbackLogo, isTitleObject, documentTitle, documentLang, documentThemeStyle } from "./specbook-export-common.js";
+import { specDiagrams } from "./specbook-diagram.js";
+/*  ==== Templates ====  */
+/*  the built-in Nunjucks templates for the HTML export  */
+const templates = {
+    /*  <Document/>  */
+    "Document": textframe `
+        <!DOCTYPE html>
+        <html{% if Document.lang %} lang="{{ Document.lang }}"{% endif %}{% if Document.theme %} class="theme-{{ Document.theme }}"{% endif %}>
+            <head>
+                <meta charset="utf-8"/>
+                <title>{{ Document.title }}</title>
+                <style>
+                    {{ Document.css }}
+                </style>
+                <script>
+                    (function () {
+                        let style = null
+                        try { style = localStorage.getItem("specbook-theme") } catch (ex) {}
+                        if (style === null) {
+                            const m = document.documentElement.className.match(/theme-(light|dark)/)
+                            style = m !== null ? m[1] : null
+                        }
+                        if (style === null)
+                            style = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"
+                        document.documentElement.className = "theme-" + style
+                    })()
+                    function themeSwitch () {
+                        const style = document.documentElement.className === "theme-dark" ? "light" : "dark"
+                        document.documentElement.className = "theme-" + style
+                        try { localStorage.setItem("specbook-theme", style) } catch (ex) {}
+                    }
+                </script>
+            </head>
+            <body>
+                <div class="theme-switch" onclick="themeSwitch()" title="switch color theme">&#x25D0;</div>
+                {{ Document.titlepage }}
+                {% if not Document.titlepage %}<div class="meta">created: {{ Document.created }}, modified: {{ Document.modified }}</div>{% endif %}
+                {{ Document.toc }}
+                {{ Document.artifacts }}
+                {% if Document.search %}<script>{{ Document.search }}</script>{% endif %}
+            </body>
+        </html>
+    `,
+    /*  <TitlePage/>  */
+    "TitlePage": textframe `
+        <div class="titlepage">
+            {% if TitlePage.logo %}<div class="logo">{{ TitlePage.logo }}</div>{% endif %}
+            <div class="title">{{ TitlePage.title }}</div>
+            {% if TitlePage.subtitle %}<div class="subtitle">{{ TitlePage.subtitle }}</div>{% endif %}
+            {% if TitlePage.author %}<div class="author">{{ TitlePage.author }}</div>{% endif %}
+            <table class="meta">
+                {% if TitlePage.version %}<tr><td class="label">Version:</td><td>{{ TitlePage.version }}</td></tr>{% endif %}
+                <tr><td class="label">Created:</td><td>{{ TitlePage.created }}</td></tr>
+                <tr><td class="label">Modified:</td><td>{{ TitlePage.modified }}</td></tr>
+            </table>
+            {{ TitlePage.description }}
+            {{ TitlePage.properties }}
+            <div class="search">
+                <input type="text" id="search-input" placeholder="Search&hellip;" autocomplete="off" spellcheck="false"/>
+                <span class="search-clear" id="search-clear" title="clear search">&#x00D7;</span>
+            </div>
+        </div>
+    `,
+    /*  <Toc/>  */
+    "Toc": textframe `
+        <nav class="toc">
+            <h1>Table of Contents</h1>
+            <table>
+                {% for entry in Toc.entries %}
+                <tr><td><a href="#{{ entry.id }}"><span class="object-kind">{{ entry.kind }}:</span> {{ entry.name }} <span class="link-symbol">&#x26AD;</span></a></td>{% if entry.page %}<td class="page"><a href="#{{ entry.id }}">{{ entry.page }}</a></td>{% endif %}</tr>
+                {% endfor %}
+            </table>
+        </nav>
+    `,
+    /*  <Artifact/>  */
+    "Artifact": textframe `
+        <article>
+            {{ Artifact.objects }}
+        </article>
+    `,
+    /*  <Object/>  */
+    "Object": textframe `
+        <section>
+            <h{{ Object.level }} id="{{ Object.id }}"><span class="object-kind">{{ Object.kind }}:</span> {{ Object.name }}{% if Object.primary %} <span class="primary-marker">&#x2318;</span>{% endif %}{% if Object.paren %} <span class="anchor-paren">({{ Object.paren }})</span>{% endif %} <a href="#{{ Object.id }}"><span class="anchor-symbol">&#x2693;&#xFE0E;</span></a></h{{ Object.level }}>
+            {{ Object.diagram }}
+            {{ Object.properties }}
+            {{ Object.description }}
+            {{ Object.childs }}
+        </section>
+    `,
+    /*  <Properties/>  */
+    "Properties": textframe `
+        <table class="props">
+            {% for property in Properties %}
+            <tr><td class="key property-name">{{ property.key }}</td><td>{{ property.value }}</td></tr>
+            {% endfor %}
+        </table>
+    `,
+    /*  <Description/>  */
+    "Description": textframe `
+        {%- if Description.block %}
+        <div class="description">{{ Description.description }}{% if Description.rationale %}
+            <p class="rationale">&mdash; <span class="keyword">BECAUSE</span> {{ Description.rationale }}</p>{% endif %}</div>
+        {%- else %}
+        <p class="description">{{ Description.description }}{% if Description.rationale %}
+            <span class="rationale">&mdash; <span class="keyword">BECAUSE</span> {{ Description.rationale }}</span>{% endif %}</p>
+        {%- endif %}
+        {%- for embedding in Description.embeddings %}
+        <div class="embedding">{{ embedding }}</div>
+        {%- endfor %}
+    `,
+    /*  <Table/>  */
+    "Table": textframe `
+        <table class="objects">
+            <thead>
+                <tr>
+                    <th class="object-kind">{{ Table.head }}</th>
+                    {%- for key in Table.keys %}<th class="property-name">{{ key }}</th>{% endfor %}
+                    {%- if Table.desc %}<th class="description" style="width: {{ Table.width }}%">Description</th>{% endif %}
+                </tr>
+            </thead>
+            <tbody>
+                {% for row in Table.rows %}
+                <tr id="{{ row.id }}">
+                    <td>{{ row.name }}{% if row.primary %} <span class="primary-marker">&#x2318;</span>{% endif %}{% if row.paren %} <span class="anchor-paren">({{ row.paren }})</span>{% endif %} <a href="#{{ row.id }}"><span class="anchor-symbol">&#x2693;&#xFE0E;</span></a></td>
+                    {%- for value in row.values %}<td>{{ value }}</td>{% endfor %}
+                    {%- if Table.desc %}<td>{{ row.description }}</td>{% endif %}
+                </tr>
+                {% endfor %}
+            </tbody>
+        </table>
+    `
+};
+/*  ==== Rendering ====  */
+/*  the per-language double quote styles for the smart typography
+    (single quotes stay curly, as smartypants cannot distinguish a
+    closing single quote from an apostrophe)  */
+const quoteStyles = {
+    "en": ["&#8220;", "&#8221;"], /*  “...”    */
+    "nl": ["&#8220;", "&#8221;"], /*  “...”    */
+    "de": ["&#8222;", "&#8220;"], /*  „...“    */
+    "cs": ["&#8222;", "&#8220;"], /*  „...“    */
+    "sk": ["&#8222;", "&#8220;"], /*  „...“    */
+    "pl": ["&#8222;", "&#8221;"], /*  „...”    */
+    "fr": ["&#171;&#160;", "&#160;&#187;"], /*  « ... »  */
+    "it": ["&#171;", "&#187;"], /*  «...»    */
+    "es": ["&#171;", "&#187;"], /*  «...»    */
+    "pt": ["&#171;", "&#187;"], /*  «...»    */
+    "no": ["&#171;", "&#187;"], /*  «...»    */
+    "da": ["&#187;", "&#171;"], /*  »...«    */
+    "sv": ["&#8221;", "&#8221;"], /*  ”...”    */
+    "fi": ["&#8221;", "&#8221;"] /*  ”...”    */
+};
+/*  the active double quote style (set per document during rendering)  */
+let quotes = quoteStyles.en;
+/*  improve the typography of all rendered Markdown text (curly quotes,
+    "--" as the em dash, ellipsis); as smartypants requires unescaped text,
+    the extension switches off the text escaping of marked, so the stray
+    ampersands left behind have to be re-escaped afterwards; the English
+    double quotes of smartypants are remapped to the document language;
+    as marked runs later-registered pass-through hooks first, the
+    post-processing hook has to be registered before smartypants  */
+marked.use({ hooks: { postprocess: (html) => html.replace(/&#8220;/g, quotes[0]).replace(/&#8221;/g, quotes[1])
+            .replace(/&(?![a-zA-Z][a-zA-Z0-9]*;|#\d+;|#x[0-9a-fA-F]+;)/g, "&amp;") } });
+marked.use(markedSmartypants({ config: 1 }));
+/*  the Nunjucks environment with the @rse/nunjucks-addons extensions  */
+const env = new nunjucks.Environment(null, { autoescape: true });
+nunjucksAddons(env);
+/*  mark pre-rendered HTML as safe for template interpolation  */
+const safe = (html) => new nunjucks.runtime.SafeString(html);
+const render = (name, context) => env.renderString(templates[name], context);
+/*  the active per-document reference expander, fully-qualified
+    anchor paths, enum/tags property value kinds, and pre-rendered
+    diagram SVGs (all set during HTML rendering)  */
+let linker = null;
+let anchors = null;
+let members = null;
+let diagrams = null;
+/*  determine the fully-qualified anchor path of an object  */
+const anchorOf = (object) => anchors?.get(object) ?? object.id;
+/*  expand the inline Markdown of a text (code spans, emphasis, etc.),
+    with Wiki-style references expanded upfront  */
+const inline = (text) => safe(marked.parseInline(linker !== null ? linker(text) : text));
+/*  expand the full Markdown of a text, keeping its block-level
+    constructs (lists, quotes, code blocks, tables) intact  */
+const block = (text) => safe(marked.parse(linker !== null ? linker(text) : text));
+/*  check whether a text carries any block-level Markdown, i.e. is
+    anything else than the single paragraph a description usually is  */
+const isBlock = (text) => {
+    const tokens = marked.lexer(text).filter((token) => token.type !== "space");
+    return tokens.length > 0 && !(tokens.length === 1 && tokens[0].type === "paragraph");
+};
+/*  render the embedded image files of a text into HTML (SVG inlined
+    as-is, PNG/JPEG placed onto <img> tags), taking the image alternate
+    texts from the corresponding "![alt](file)" markups  */
+const renderEmbeddings = (text, embedding) => {
+    const alts = [...text.matchAll(embeddingRegex)]
+        .filter((m) => embeddingMimeType(m[2].trim()) !== undefined)
+        .map((m) => m[1].trim());
+    return embedding.map((content, i) => content.startsWith("data:") ?
+        `<img src="${content}" alt="${escapeHtml(alts[i] ?? "")}"/>` :
+        content.replace(/^\s*<\?xml[^>]*\?>\s*(?:<!DOCTYPE[^>]*>\s*)?/i, ""));
+};
+/*  render a description into HTML, expanding its inline Markdown and
+    moving the file embeddings to the end of the description  */
+const renderDescription = (description) => {
+    const text = description.description
+        .replace(embeddingRegex, (markup, _alt, reference) => embeddingMimeType(reference.trim()) !== undefined ? "" : markup)
+        .replace(/(?<=\S)[ \t]{2,}/g, " ").trim();
+    const embeddings = renderEmbeddings(description.description, description.embedding ?? []).map((content) => safe(content));
+    const blocked = isBlock(text);
+    return render("Description", { Description: {
+            block: blocked,
+            description: blocked ? block(text) : inline(text),
+            rationale: description.rationale !== undefined ?
+                inline(description.rationale) : undefined,
+            embeddings
+        } });
+};
+/*  collect the "enum(...)"/"tags(...)" constrained properties of the
+    schema configuration, keyed by object kind and property name  */
+const collectMembers = (schemas, result) => {
+    for (const schema of schemas) {
+        for (const property of schema.props ?? []) {
+            if (property.value === undefined)
+                continue;
+            try {
+                const expr = compileValueExpr(property.value);
+                if (expr.kind === "enum" || expr.kind === "tags")
+                    result.set(`${schema.kind}${property.name}`, expr.kind);
+            }
+            catch {
+                /*  an invalid expression is the concern of lint  */
+            }
+        }
+        collectMembers(schema.childs ?? [], result);
+    }
+    return result;
+};
+/*  render a property value, badging the individual members of an
+    "enum(...)" (a single member) or "tags(...)" (a member set) value  */
+const inlineValue = (kind, key, value) => {
+    const member = members?.get(`${kind}${key.replace(/\s*\([^)]*\)\s*$/, "").trim()}`);
+    if (member === undefined)
+        return inline(value);
+    const items = member === "tags" ? splitItems(value) : [value.trim()];
+    return safe(items.map((item) => `<span class="value-member">${inline(item)}</span>`).join(" "));
+};
+/*  expand the inline Markdown of the property values  */
+const inlineProperties = (kind, properties) => properties.map((property) => ({ key: property.key,
+    value: inlineValue(kind, property.key, property.value) }));
+/*  determine the column shape of a potential compact table  */
+const tableShape = (childs) => {
+    const keys = new Array();
+    for (const child of childs)
+        for (const property of child.properties)
+            if (!keys.includes(property.key))
+                keys.push(property.key);
+    return { keys, desc: childs.some((child) => child.description !== undefined) };
+};
+/*  check whether the childs of an object form the deepest level and every
+    per-kind group is compact enough (at most maxColumns name/property/
+    description columns) for a tabular rendering  */
+const tabularChilds = (object, maxColumns) => {
+    if (object.childs.length === 0
+        || !object.childs.every((child) => child.childs.length === 0))
+        return false;
+    return groupChilds(object.childs).every((group) => {
+        const { keys, desc } = tableShape(group);
+        return 1 + keys.length + (desc ? 1 : 0) <= maxColumns;
+    });
+};
+/*  group the childs of an object by their kind, preserving order  */
+const groupChilds = (childs) => {
+    const groups = new Map();
+    for (const child of childs) {
+        const group = groups.get(child.kind);
+        if (group === undefined)
+            groups.set(child.kind, [child]);
+        else
+            group.push(child);
+    }
+    return [...groups.values()];
+};
+/*  render a single-kind group of leaf childs into one compact table:
+    the name first, then the property columns, then the description  */
+const renderTable = (childs) => {
+    const { keys, desc } = tableShape(childs);
+    return render("Table", { Table: {
+            head: childs[0].kind !== "" ? childs[0].kind : "Name",
+            keys,
+            desc,
+            /*  under the fixed table layout the description column claims
+                twice the share of a regular column, compressing the others  */
+            width: Math.round(200 / (keys.length + 3)),
+            rows: childs.map((child) => ({
+                id: anchorOf(child),
+                paren: child.paren,
+                primary: child.primary,
+                name: inline(child.name),
+                values: keys.map((key) => {
+                    const value = child.properties.find((property) => property.key === key)?.value;
+                    return value !== undefined ? inlineValue(child.kind, key, value) : "";
+                }),
+                description: child.description !== undefined ?
+                    safe(renderDescription(child.description)) : ""
+            }))
+        } });
+};
+/*  recursively render an object into HTML  */
+const renderObject = (object, level, maxColumns) => render("Object", { Object: {
+        level: Math.min(level, 6),
+        kind: object.kind,
+        id: anchorOf(object),
+        paren: object.paren,
+        primary: object.primary,
+        name: inline(object.name),
+        diagram: diagrams?.has(object) === true ?
+            safe(`<div class="diagram">${diagrams.get(object) ?? ""}</div>`) : "",
+        properties: object.properties.length > 0 ?
+            safe(render("Properties", { Properties: inlineProperties(object.kind, object.properties) })) : "",
+        description: object.description !== undefined ?
+            safe(renderDescription(object.description)) : "",
+        childs: tabularChilds(object, maxColumns) ?
+            safe(groupChilds(object.childs).map(renderTable).join("")) :
+            safe(object.childs.map((child) => renderObject(child, level + 1, maxColumns)).join(""))
+    } });
+/*  render the title object into a title page  */
+const renderTitlePage = (object, created, modified) => {
+    const prop = (name) => object.properties.find((property) => property.key === name)?.value;
+    const rest = object.properties.filter((property) => !["LOGO", "TITLE", "SUBTITLE", "AUTHOR", "VERSION",
+        "LANG", "CHARSET", "PAPER-SIZE", "THEME-STYLE", "THEME-TONE"].includes(property.key));
+    /*  the logo is rendered above the title, from the embedded image content
+        of the LOGO property or, for a non-embeddable reference, as its inline
+        Markdown; without a LOGO property the built-in SpecBook logo is used  */
+    const logo = object.properties.find((property) => property.key === "LOGO");
+    const image = logo !== undefined ? renderEmbeddings(logo.value, logo.embedding ?? []) : [];
+    return render("TitlePage", { TitlePage: {
+            logo: logo === undefined ? safe(`<img src="${fallbackLogo()}" alt="SpecBook"/>`) :
+                (image.length > 0 ? safe(image.join("")) : inline(logo.value)),
+            title: inline(prop("TITLE") ?? object.name),
+            subtitle: prop("SUBTITLE") !== undefined ? inline(prop("SUBTITLE") ?? "") : "",
+            author: prop("AUTHOR") !== undefined ? inline(prop("AUTHOR") ?? "") : "",
+            version: prop("VERSION") !== undefined ? inline(prop("VERSION") ?? "") : "",
+            description: object.description !== undefined ?
+                safe(renderDescription(object.description)) : "",
+            properties: rest.length > 0 ?
+                safe(render("Properties", { Properties: inlineProperties(object.kind, rest) })) : "",
+            created, modified
+        } });
+};
+/*  render an artifact into HTML  */
+const renderArtifact = (artifact, maxColumns) => render("Artifact", { Artifact: {
+        objects: safe(artifact.objects.map((object) => renderObject(object, 1, maxColumns)).join(""))
+    } });
+/*  derive the hierarchy of the rendered object headings, skipping the
+    title page object and the leaf childs collapsing into compact tables  */
+export const htmlOutline = (specification, maxColumns) => {
+    const paths = anchorPaths(buildLinkIndex(specification));
+    const entry = (object) => ({
+        title: (object.kind !== "" ? `${object.kind}: ` : "") + object.name,
+        anchor: paths.get(object) ?? object.id,
+        childs: tabularChilds(object, maxColumns) ? [] : object.childs.map(entry)
+    });
+    return specification.artifacts
+        .filter((artifact) => !artifact.objects.some(isTitleObject))
+        .flatMap((artifact) => artifact.objects)
+        .map(entry);
+};
+/*  render the entire specification into a self-contained HTML document,
+    with the build-time pre-assembled stylesheet embedded inline, the
+    artifact timestamps aggregated into min(Created)/max(Modified), and
+    optional per-anchor page numbers attached to the ToC entries  */
+export const renderHtml = async (specification, maxColumns, config, tocPages, css) => {
+    /*  the document language selects the smart typography quote style  */
+    const lang = documentLang(specification);
+    quotes = quoteStyles[lang?.toLowerCase().split(/[-_]/)[0] ?? "en"] ?? quoteStyles.en;
+    /*  pre-render the configured diagrams as embeddable SVGs (a runtime
+        rendering failure omits the diagram, as the statically detectable
+        invalid situations are already reported as lint diagnostics),
+        displayed at a reduced coordinate scale, as the Gradia geometry
+        (node boxes, font sizes) is dimensioned for a stand-alone
+        canvas and would dwarf the document text at 1:1  */
+    const scale = 0.75;
+    diagrams = null;
+    if (config !== undefined) {
+        diagrams = new Map();
+        for (const [object, result] of specDiagrams(specification, config)) {
+            if (result.spec === undefined)
+                continue;
+            try {
+                const svg = await Gradia.render(result.spec, { format: "svg:embedded" });
+                diagrams.set(object, svg.replace(/(<svg[^>]*) width="([0-9.]+)" height="([0-9.]+)"/, (_, head, w, h) => `${head} width="${Number(w) * scale}" height="${Number(h) * scale}"`));
+            }
+            catch {
+                /*  intentionally omitted  */
+            }
+        }
+    }
+    /*  expand "[[xxx]]" references into hyperlinks (an unresolvable or
+        ambiguous reference stays literal, marked as broken), targeting
+        the fully-qualified anchor paths of the objects  */
+    const index = buildLinkIndex(specification);
+    anchors = anchorPaths(index);
+    members = config !== undefined ? collectMembers(config, new Map()) : null;
+    linker = (text) => expandReferences(text, (reference) => {
+        const target = resolveUnique(index, reference).target;
+        if (target === undefined)
+            return `<span class="link-broken">[[${escapeHtml(reference)}]]</span>`;
+        return `<a href="#${escapeHtml(anchorOf(target))}">` +
+            `<span class="object-kind">${escapeHtml(target.kind)}:</span> <strong>${target.name}</strong>` +
+            " <span class=\"link-symbol\">&#x26AD;</span></a>";
+    });
+    const created = new Date(Math.min(...specification.artifacts.map((artifact) => artifact.created.getTime())));
+    const modified = new Date(Math.max(...specification.artifacts.map((artifact) => artifact.modified.getTime())));
+    /*  a "META: Title" object becomes the title page and leaves the regular flow  */
+    const title = specification.artifacts
+        .flatMap((artifact) => artifact.objects).find(isTitleObject);
+    const artifacts = specification.artifacts
+        .filter((artifact) => !artifact.objects.some(isTitleObject));
+    const entries = artifacts.flatMap((artifact) => artifact.objects)
+        .map((object) => ({ id: anchorOf(object), kind: object.kind, name: inline(object.name),
+        page: tocPages?.get(anchorOf(object)) }));
+    return render("Document", { Document: {
+            title: documentTitle(specification).title,
+            lang,
+            theme: documentThemeStyle(specification)?.toLowerCase(),
+            css: safe(css ?? stylesheet()),
+            created: created.toISOString(),
+            modified: modified.toISOString(),
+            titlepage: title !== undefined ?
+                safe(renderTitlePage(title, created.toISOString().slice(0, 10), modified.toISOString().slice(0, 10))) : "",
+            search: title !== undefined ? safe(searchScript()) : "",
+            toc: entries.length > 0 ? safe(render("Toc", { Toc: { entries } })) : "",
+            artifacts: safe(artifacts.map((artifact) => renderArtifact(artifact, maxColumns)).join(""))
+        } });
+};

package/dst/specbook-export-logo.svg

@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="Layer_1" xmlns="http://www.w3.org/2000/svg" version="1.1" viewBox="0 0 260.81 110.54">
+  <!-- Generator: Adobe Illustrator 30.7.0, SVG Export Plug-In . SVG Version: 2.1.4 Build 114)  -->
+  <defs>
+    <style>
+      .st0 {
+        fill: none;
+      }
+
+      .st1 {
+        fill: #231f20;
+      }
+
+      .st2 {
+        fill: #666766;
+      }
+    </style>
+  </defs>
+  <g>
+    <rect class="st0" x="128.02" y="5.89" width="297.69" height="245.38"/>
+    <path class="st1" d="M132.56,41.28c2.62,1.34,6.66,2.69,10.82,2.69,4.48,0,6.85-1.86,6.85-4.67s-2.05-4.22-7.23-6.08c-7.17-2.5-11.84-6.46-11.84-12.73,0-7.36,6.14-12.99,16.32-12.99,4.86,0,8.45,1.02,11.01,2.18l-2.18,7.87c-1.73-.83-4.8-2.05-9.02-2.05s-6.27,1.92-6.27,4.16c0,2.75,2.43,3.97,8,6.08,7.62,2.82,11.2,6.78,11.2,12.86,0,7.23-5.57,13.38-17.41,13.38-4.93,0-9.79-1.28-12.22-2.62l1.98-8.06Z"/>
+    <path class="st1" d="M163.28,30.53c0-4.1-.13-7.62-.26-10.5h8.45l.45,4.35h.13c2.3-3.33,5.89-5.06,10.43-5.06,6.85,0,12.99,5.95,12.99,15.93,0,11.39-7.23,16.77-14.21,16.77-3.78,0-6.72-1.54-8.13-3.58h-.13v15.55h-9.73V30.53ZM173.01,37.89c0,.77.06,1.47.19,2.05.64,2.62,2.88,4.61,5.7,4.61,4.22,0,6.72-3.52,6.72-8.83,0-4.99-2.24-8.77-6.59-8.77-2.75,0-5.18,2.05-5.82,4.93-.13.51-.19,1.15-.19,1.73v4.29Z"/>
+    <path class="st1" d="M206.03,38.78c.32,4.03,4.29,5.95,8.83,5.95,3.33,0,6.02-.45,8.64-1.28l1.28,6.59c-3.2,1.28-7.1,1.92-11.33,1.92-10.62,0-16.7-6.14-16.7-15.94,0-7.94,4.93-16.7,15.81-16.7,10.11,0,13.95,7.87,13.95,15.61,0,1.66-.19,3.14-.32,3.84h-20.16ZM217.48,32.13c0-2.37-1.02-6.34-5.5-6.34-4.1,0-5.76,3.71-6.02,6.34h11.52Z"/>
+    <path class="st1" d="M252.62,50.56c-1.73.77-4.99,1.41-8.7,1.41-10.11,0-16.57-6.14-16.57-16,0-9.15,6.27-16.64,17.92-16.64,2.56,0,5.38.45,7.42,1.22l-1.54,7.23c-1.15-.51-2.88-.96-5.44-.96-5.12,0-8.45,3.65-8.38,8.77,0,5.76,3.84,8.77,8.58,8.77,2.3,0,4.1-.38,5.57-.96l1.15,7.17Z"/>
+  </g>
+  <path d="M25.37,18.54h0c-1.03,0-2,.4-2.73,1.13-.74.74-1.15,1.72-1.15,2.77v58.42c0,2.14,1.75,3.89,3.9,3.9,9.07.02,24.26,1.91,34.75,12.88v-61.14c0-.73-.19-1.41-.54-1.97-8.6-13.85-25.14-15.96-34.23-15.98Z"/>
+  <path d="M104.82,80.86V22.43c0-1.05-.41-2.03-1.15-2.77-.73-.73-1.7-1.13-2.73-1.13h0c-9.09.02-25.62,2.13-34.23,15.98-.35.56-.54,1.25-.54,1.97v61.14c10.48-10.97,25.68-12.86,34.75-12.88,2.15,0,3.9-1.75,3.9-3.89Z"/>
+  <path class="st2" d="M113.7,32.01h-2.83v48.85c0,5.47-4.46,9.93-9.94,9.94-7.69.02-20.38,1.52-29.36,10.02,15.54-3.8,31.91-1.33,41.25.8,1.17.27,2.37,0,3.3-.75.93-.74,1.46-1.85,1.46-3.04v-61.92c0-2.15-1.75-3.9-3.9-3.9Z"/>
+  <path class="st2" d="M15.43,80.86v-48.85h-2.83c-2.15,0-3.9,1.75-3.9,3.9v61.92c0,1.19.53,2.3,1.46,3.04.93.74,2.14,1.02,3.3.75,9.33-2.13,25.71-4.6,41.25-.8-8.98-8.5-21.67-10.01-29.36-10.02-5.48-.01-9.94-4.47-9.94-9.94Z"/>
+  <g>
+    <path class="st2" d="M131.67,55.5c2.63-.55,6.77-.97,10.99-.97,6.01,0,9.88,1.04,12.78,3.39,2.42,1.8,3.87,4.56,3.87,8.22,0,4.49-2.97,8.43-7.88,10.23v.14c4.42,1.11,9.6,4.77,9.6,11.68,0,4.01-1.59,7.05-3.94,9.33-3.25,2.97-8.5,4.35-16.1,4.35-4.15,0-7.32-.28-9.33-.55v-45.81ZM137.68,74.57h5.46c6.36,0,10.09-3.32,10.09-7.81,0-5.46-4.15-7.6-10.23-7.6-2.76,0-4.35.21-5.32.41v14.99ZM137.68,96.89c1.17.21,2.9.28,5.04.28,6.22,0,11.95-2.28,11.95-9.05,0-6.36-5.46-8.98-12.02-8.98h-4.97v17.76Z"/>
+    <path class="st2" d="M206.14,66.9c-9.26,0-16.58,6.56-16.58,17.75,0,.12.01.24.01.36h-.04c-.27,7.16-4.51,12.28-10.13,12.28-5.94,0-10.16-5.53-10.16-12.85,0-6.36,3.11-12.99,10.29-12.99,4.29,0,7.02,2.57,8.53,5.85.79-2.15,1.94-3.99,3.37-5.51-2.83-3.1-6.89-4.9-11.76-4.9-9.26,0-16.58,6.56-16.58,17.75,0,10.57,6.98,17.2,16.03,17.2,7.88,0,16.19-5.14,16.61-16.84h0c0-.19-.02-.38-.02-.57,0-6.36,3.11-12.99,10.29-12.99s10.02,7.19,10.02,12.85c0,7.53-4.35,12.99-10.15,12.99-4.05,0-7.29-2.57-8.94-6.51-.75,2.31-1.89,4.24-3.29,5.8,2.9,3.37,7.13,5.27,11.96,5.27,8.08,0,16.65-5.39,16.65-17.75,0-10.22-6.49-17.2-16.1-17.2Z"/>
+    <path class="st2" d="M230.65,83.76h.14c.83-1.17,2-2.63,2.97-3.8l9.81-11.54h7.32l-12.92,13.75,14.72,19.69h-7.39l-11.54-16.03-3.11,3.45v12.57h-6.01v-49.06h6.01v30.95Z"/>
+  </g>
+</svg>

package/dst/specbook-export-md.d.ts

@@ -0,0 +1,3 @@
+import type { Specification } from "./specbook-struct-spec.js";
+import type { SchemaSpecification } from "./specbook-struct-schema.js";
+export declare const renderMarkdown: (specification: Specification, config?: SchemaSpecification) => Promise<string>;

package/dst/specbook-export-md.js

@@ -0,0 +1,74 @@
+/*
+**  Specification Book (SpecBook)
+**  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import { specDiagrams } from "./specbook-diagram.js";
+/*  format a timestamp in the frontmatter format  */
+const formatTimestamp = (date) => {
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ` +
+        `${pad(date.getHours())}:${pad(date.getMinutes())}`;
+};
+/*  render the properties as a value-aligned key/value list  */
+const renderKeyValuesMd = (properties) => {
+    const width = Math.max(...properties.map((property) => property.key.length)) + 1;
+    return properties.map((property) => `-   ${`${property.key}:`.padEnd(width)} ${property.value}`).join("\n");
+};
+/*  render a description statement with its optional rationale  */
+const renderDescriptionMd = (description) => description.description + (description.rationale !== undefined ?
+    `, BECAUSE ${description.rationale}` : "");
+/*  render the "(*)" primary marker plus the implicit "(xxx)"
+    and/or explicit "{{xxx}}" anchor suffix  */
+const nameSuffixMd = (object) => (object.primary === true ? " (*)" : "") +
+    (object.paren !== undefined ? ` (${object.paren})` : "") +
+    (object.anchor !== undefined ? ` {{${object.anchor}}}` : "");
+/*  render an object in the Concise Format (level 4 and deeper),
+    with its childs as nested list items  */
+const renderConciseMd = (object, level) => {
+    const indent = " ".repeat((level - 4) * 4);
+    const segments = [`${object.kind}: ${object.name}${nameSuffixMd(object)}`];
+    segments.push(...object.properties.map((property) => `${property.key}: ${property.value}`));
+    if (object.description !== undefined)
+        segments.push(renderDescriptionMd(object.description));
+    const item = `${indent}-   ${segments.join("; ").replace(/\.?$/, ".")}`;
+    return [item, ...object.childs.map((child) => renderConciseMd(child, level + 1))].join("\n");
+};
+/*  render an object in the Complex Format (levels 1-3),
+    with childs from level 4 upwards in the Concise Format
+    and the optionally derived Gradia diagram spec embedded
+    as a "gradia" fenced code block below the heading  */
+const renderObjectMd = (object, level, diagrams) => {
+    const heading = level === 1 ?
+        `#   ${object.kind}: ${object.name}${nameSuffixMd(object)}` :
+        `${"#".repeat(level)}${" ".repeat(4 - level)}${object.kind}: ${object.name}${nameSuffixMd(object)}`;
+    const parts = [heading];
+    const spec = diagrams?.get(object);
+    if (spec !== undefined)
+        parts.push(`\`\`\`gradia\n${spec}\`\`\``);
+    if (object.properties.length > 0)
+        parts.push(renderKeyValuesMd(object.properties));
+    if (object.description !== undefined)
+        parts.push(renderDescriptionMd(object.description));
+    if (level >= 3)
+        parts.push(object.childs.map((child) => renderConciseMd(child, level + 1)).join("\n"));
+    else
+        parts.push(...object.childs.map((child) => renderObjectMd(child, level + 1, diagrams)));
+    return parts.filter((part) => part !== "").join("\n\n");
+};
+/*  render the entire specification into normalized Markdown  */
+export const renderMarkdown = async (specification, config) => {
+    /*  derive the Gradia specs of the diagram-configured objects
+        (an invalid diagram situation omits the diagram, as it is
+        already reported as a lint diagnostic)  */
+    const diagrams = new Map();
+    if (config !== undefined)
+        for (const [object, result] of specDiagrams(specification, config))
+            if (result.spec !== undefined)
+                diagrams.set(object, result.spec);
+    return specification.artifacts.map((artifact) => artifact.objects.map((object) => "---\n" +
+        `Created:  ${formatTimestamp(artifact.created)}\n` +
+        `Modified: ${formatTimestamp(artifact.modified)}\n` +
+        "---\n\n" +
+        renderObjectMd(object, 1, diagrams)).join("\n\n")).join("\n\n") + "\n";
+};

package/dst/specbook-export-pdf.d.ts

@@ -0,0 +1,7 @@
+import type { OutlineEntry } from "./specbook-export-html.js";
+import type { ThemeMapping } from "./specbook-theme.js";
+export declare const htmlToPdf: (renderHtmlPass: (tocPages?: Map<string, number>) => Promise<string>, heading: {
+    title: string;
+    subtitle?: string;
+    logo: string;
+}, outline: OutlineEntry[], verbose: (msg: string) => void, css: string, theme: ThemeMapping, paper?: string) => Promise<Buffer>;