@rse/specbook 0.9.6 → 0.9.8

package/dst/specbook-export-html.js

@@ -9,10 +9,11 @@ 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 { buildLinkIndex, resolveUnique, expandReferences, anchorPaths, plainText } from "./specbook-link.js";
 import { compileValueExpr, splitItems } from "./specbook-parse-value.js";
 import { embeddingRegex, embeddingMimeType, embeddingThemes, embeddingVariants } from "./specbook-parse-common.js";
 import { escapeHtml, stylesheet, searchScript, fallbackLogo, isTitleObject, titleObject, documentTitle, documentLang, documentThemeStyle } from "./specbook-export-common.js";
+import { collectSchemas } from "./specbook-parse-semantic.js";
 import { specDiagrams } from "./specbook-diagram.js";
 /*  ==== Templates ====  */
 /*  the built-in Nunjucks templates for the HTML export  */
@@ -117,7 +118,7 @@ const templates = {
         {%- 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 %}
+        {%- elif Description.description or Description.rationale %}
         <p class="description">{{ Description.description }}{% if Description.rationale %}
             <span class="rationale">&mdash; <span class="keyword">BECAUSE</span> {{ Description.rationale }}</span>{% endif %}</p>
         {%- endif %}
@@ -209,6 +210,18 @@ const marked = new Marked();
 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 switched-off text escaping of marked also leaves the angle
+    brackets of the inline text unescaped, which a browser then takes
+    for tags ("Map<String, Object>"), so they are escaped upfront in
+    the inline text tokenizer (registered after smartypants, as the
+    later-registered tokenizer takes precedence)  */
+marked.use({ tokenizer: { inlineText(src) {
+            const cap = this.rules.inline.text.exec(src);
+            if (cap === null)
+                return undefined;
+            return { type: "text", raw: cap[0], escaped: true,
+                text: cap[0].replace(/</g, "&lt;").replace(/>/g, "&gt;") };
+        } } });
 /*  the Nunjucks environment with the @rse/nunjucks-addons extensions  */
 const env = new nunjucks.Environment(null, { autoescape: true });
 nunjucksAddons(env);
@@ -231,28 +244,33 @@ const diagramCache = new WeakMap();
 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));
+const inline = (text) => safe(marked.parseInline(linker !== null ? linker(text) : text, { async: false }));
 /*  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));
+const block = (text) => safe(marked.parse(linker !== null ? linker(text) : text, { async: false }));
 /*  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 a single embedded image file into HTML (SVG inlined as-is,
-    PNG/JPEG placed onto an <img> tag)  */
-const renderImage = (content, alt) => content.startsWith("data:") ?
-    `<img src="${content}" alt="${escapeHtml(alt)}"/>` :
-    content.replace(/^\s*<\?xml[^>]*\?>\s*(?:<!DOCTYPE[^>]*>\s*)?/i, "");
+/*  render a single embedded image file onto an <img> tag with a
+    self-contained data: URL (converting the SVG text into one, as an
+    SVG inlined as-is would leak its document-global <style> rules
+    into all other inlined SVGs sharing the same class names)  */
+const renderImage = (content, alt) => {
+    const url = content.startsWith("data:") ? content :
+        `data:image/svg+xml;base64,${Buffer.from(content, "utf8").toString("base64")}`;
+    return `<img src="${url}" alt="${escapeHtml(alt)}"/>`;
+};
 /*  wrap the theme variants of an image into their layout-neutral theme
     containers, of which the stylesheet shows just the one matching the
     color theme currently active in the document  */
 const renderThemed = (images) => images.map((image, i) => `<span class="theme-${embeddingThemes[i]}-only">${image}</span>`).join("");
 /*  render the embedded image files of a text into HTML, taking the image
     alternate texts from the corresponding "![alt](file)" markups and
-    pairing up the consecutive theme variants of a "{theme}" markup  */
+    pairing up the consecutive theme variants of a "{theme}" markup
+    (the empty entries of unreadable files are skipped)  */
 const renderEmbeddings = (text, embedding) => {
     const result = new Array();
     let i = 0;
@@ -261,7 +279,8 @@ const renderEmbeddings = (text, embedding) => {
         if (embeddingMimeType(reference) === undefined)
             continue;
         const variants = embeddingVariants(reference);
-        const images = embedding.slice(i, i + variants.length)
+        const contents = embedding.slice(i, i + variants.length);
+        const images = contents.filter((content) => content !== "")
             .map((content) => renderImage(content, m[1].trim()));
         i += variants.length;
         if (variants.length > 1 && images.length === variants.length)
@@ -271,17 +290,20 @@ const renderEmbeddings = (text, embedding) => {
     }
     return result;
 };
+/*  the image embedding markup including the horizontal whitespace
+    before it, so that its removal leaves no double space behind  */
+const embeddingMarkup = new RegExp(`[ \\t]*${embeddingRegex.source}`, "g");
 /*  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();
+        .replace(embeddingMarkup, (markup, _alt, reference) => embeddingMimeType(reference.trim()) !== undefined ? "" : markup)
+        .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),
+            description: text !== "" ? (blocked ? block(text) : inline(text)) : "",
             rationale: description.rationale !== undefined ?
                 inline(description.rationale) : undefined,
             embeddings
@@ -289,8 +311,8 @@ const renderDescription = (description) => {
 };
 /*  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) {
+const collectMembers = (nodes, result) => {
+    for (const schema of nodes) {
         for (const property of schema.props ?? []) {
             if (property.value === undefined)
                 continue;
@@ -307,41 +329,26 @@ const collectMembers = (schemas, result) => {
     }
     return result;
 };
-/*  map the specification objects onto their schema configuration
-    nodes (the schema resolution mirrors the semantic validation)  */
-const collectSchemas = (specification, config) => {
-    const result = new Map();
-    const walk = (object, schema) => {
-        result.set(object, schema);
-        for (const child of object.childs) {
-            const childSchema = (schema.childs ?? []).find((c) => c.kind === child.kind);
-            if (childSchema !== undefined)
-                walk(child, childSchema);
-        }
-    };
-    for (const artifact of specification.artifacts) {
-        for (const object of artifact.objects) {
-            const schema = config.find((s) => (s.kind === object.kind && s.id === object.id) || `${s.kind}-${s.id}` === object.id) ??
-                config.find((s) => (s.name ?? "").toUpperCase() ===
-                    object.name.replace(/`/g, "").toUpperCase());
-            if (schema !== undefined)
-                walk(object, schema);
-        }
-    }
-    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) => {
+    "enum(...)" (a single member) or "tags(...)" (a member set) value
+    and moving its image embeddings behind the value, rendered from the
+    embedded image contents (as for a description), not from the markup  */
+const inlineValue = (kind, { key, value, embedding }) => {
     const member = members?.get(`${kind}${key}`);
-    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(" "));
+    const text = value
+        .replace(embeddingMarkup, (markup, _alt, reference) => embeddingMimeType(reference.trim()) !== undefined ? "" : markup)
+        .trim();
+    const embeddings = renderEmbeddings(value, embedding ?? [])
+        .map((content) => `<div class="embedding">${content}</div>`).join("");
+    if (member === undefined || text === "")
+        return safe(`${inline(text)}${embeddings}`);
+    const items = member === "tags" ?
+        splitItems(text).filter((item) => item !== "") : [text];
+    return safe(items.map((item) => `<span class="value-member">${inline(item)}</span>`).join(" ") + embeddings);
 };
 /*  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) }));
+    value: inlineValue(kind, property) }));
 /*  resolve the format configuration of an object  */
 const formatOf = (object) => schemas?.get(object)?.format;
 /*  determine the maximum table columns configured on an object (at
@@ -364,18 +371,11 @@ const effectiveProperties = (object) => {
     "withUnusedProps" injecting the defined but still unused schema
     properties (in schema order) as additional columns  */
 const tableShape = (childs) => {
-    let keys = new Array();
-    for (const child of childs)
-        for (const property of child.properties)
-            if (!keys.includes(property.key))
-                keys.push(property.key);
+    let keys = [...new Set(childs.flatMap((child) => child.properties.map((property) => property.key)))];
     const schema = schemas?.get(childs[0]);
     if (schema?.format?.withUnusedProps === true) {
-        const merged = (schema.props ?? []).flatMap((prop) => {
-            const present = keys.filter((key) => key === prop.name);
-            return present.length > 0 ? present : [prop.name];
-        });
-        keys = [...merged, ...keys.filter((key) => !merged.includes(key))];
+        const names = (schema.props ?? []).map((prop) => prop.name);
+        keys = [...names, ...keys.filter((key) => !names.includes(key))];
     }
     return { keys, desc: childs.some((child) => child.description !== undefined || child.childs.length > 0) };
 };
@@ -441,8 +441,8 @@ const renderTable = (childs, maxColumns) => {
                     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) : "";
+                        const property = child.properties.find((property) => property.key === key);
+                        return property !== undefined ? inlineValue(child.kind, property) : "";
                     }),
                     description: safe(renderCell(child))
                 }))
@@ -456,9 +456,9 @@ const renderTable = (childs, maxColumns) => {
             width: Math.round(100 / maxColumns),
             rows: childs.map((child) => {
                 const cells = keys.map((key) => {
-                    const value = child.properties.find((property) => property.key === key)?.value;
+                    const property = child.properties.find((property) => property.key === key);
                     return { key, desc: false, span: 1,
-                        value: value !== undefined ? inlineValue(child.kind, key, value) : safe("") };
+                        value: property !== undefined ? inlineValue(child.kind, property) : "" };
                 });
                 if (desc)
                     cells.push({ key: "Description", desc: true, span: 1,
@@ -481,6 +481,7 @@ const renderTable = (childs, maxColumns) => {
 /*  recursively render an object into HTML  */
 const renderObject = (object, level, concise) => {
     const properties = effectiveProperties(object);
+    const diagram = diagrams?.get(object);
     return render("Object", { Object: {
             level: Math.min(level, 6),
             kind: object.kind,
@@ -488,8 +489,7 @@ const renderObject = (object, level, concise) => {
             paren: object.paren,
             primary: object.primary,
             name: inline(object.name),
-            diagram: diagrams?.has(object) === true ?
-                safe(`<div class="diagram">${diagrams.get(object) ?? ""}</div>`) : "",
+            diagram: diagram !== undefined ? safe(`<div class="diagram">${diagram}</div>`) : "",
             properties: properties.length > 0 ?
                 safe(render("Properties", { Properties: inlineProperties(object.kind, properties) })) : "",
             description: object.description !== undefined ?
@@ -499,6 +499,11 @@ const renderObject = (object, level, concise) => {
                 safe(flowChilds(object).map((child) => renderObject(child, level + 1, concise)).join(""))
         } });
 };
+/*  format a timestamp as its calendar date in local time (the
+    frontmatter timestamps are parsed in local time, too, so the UTC
+    date of toISOString() could shift the day)  */
+const formatDate = (date) => `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-` +
+    String(date.getDate()).padStart(2, "0");
 /*  render the title object into a title page  */
 const renderTitlePage = (object, created, modified) => {
     const prop = (name) => object.properties.find((property) => property.key === name)?.value;
@@ -539,7 +544,7 @@ export const htmlOutline = (specification, config) => {
     const paths = anchorPaths(buildLinkIndex(specification));
     const schemaMap = config !== undefined ? collectSchemas(specification, config) : null;
     const entry = (object) => ({
-        title: (object.kind !== "" ? `${object.kind}: ` : "") + object.name,
+        title: (object.kind !== "" ? `${object.kind}: ` : "") + plainText(object.name),
         anchor: paths.get(object) ?? object.id,
         childs: conciseChilds(object, schemaMap, false) ? [] : flowChilds(object).map(entry)
     });
@@ -570,23 +575,23 @@ export const renderHtml = async (specification, config, tocPages, css) => {
         canvas and would dwarf the document text at 1:1  */
     const scale = 0.75;
     const cached = diagramCache.get(specification);
-    diagrams = null;
+    let rendered = null;
     if (cached !== undefined && cached.config === config)
-        diagrams = cached.diagrams;
+        rendered = cached.diagrams;
     else if (config !== undefined) {
-        diagrams = new Map();
+        rendered = 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}"`));
+                const svg = await Gradia.render(result.spec, { format: "svg:embedded", config: result.config });
+                rendered.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  */
             }
         }
-        diagramCache.set(specification, { config, diagrams });
+        diagramCache.set(specification, { config, diagrams: rendered });
     }
     /*  the document language selects the smart typography quote style  */
     const lang = documentLang(specification);
@@ -598,6 +603,7 @@ export const renderHtml = async (specification, config, tocPages, css) => {
     anchors = anchorPaths(index);
     members = config !== undefined ? collectMembers(config, new Map()) : null;
     schemas = config !== undefined ? collectSchemas(specification, config) : null;
+    diagrams = rendered;
     linker = (text) => expandReferences(text, (reference) => {
         const target = resolveUnique(index, reference).target;
         if (target === undefined)
@@ -612,18 +618,30 @@ export const renderHtml = async (specification, config, tocPages, css) => {
     const title = titlePageObject(specification);
     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()),
-            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)).join(""))
-        } });
+    try {
+        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()),
+                titlepage: title !== undefined ?
+                    safe(renderTitlePage(title, formatDate(created), formatDate(modified))) : "",
+                search: title !== undefined ? safe(searchScript()) : "",
+                toc: entries.length > 0 ? safe(render("Toc", { Toc: { entries } })) : "",
+                artifacts: safe(artifacts.map((artifact) => renderArtifact(artifact)).join(""))
+            } });
+    }
+    finally {
+        /*  release the per-document state (also on a rendering failure),
+            as it would otherwise retain the specification (and its
+            embedded images) until the next rendering  */
+        linker = null;
+        anchors = null;
+        members = null;
+        schemas = null;
+        diagrams = null;
+    }
 };

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

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

package/dst/specbook-export-md.js

@@ -4,17 +4,26 @@
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
 import { specDiagrams } from "./specbook-diagram.js";
+import { becauseRegex } from "./specbook-parse-common.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) => {
+/*  render the properties as a value-aligned key/value list, wrapping a
+    value carrying ";" onto a continuation line, as only a ";"-free first
+    line lets the item be recognized as a property again on re-parsing  */
+const renderKeyValuesMd = (properties, indent = "") => {
     const width = Math.max(...properties.map((property) => property.key.length)) + 1;
-    return properties.map((property) => `-   ${`${property.key}:`.padEnd(width)} ${property.value}`).join("\n");
+    return properties.map((property) => property.value.includes(";") ?
+        `${indent}-   ${property.key}:\n${indent}    ${property.value}` :
+        `${indent}-   ${`${property.key}:`.padEnd(width)} ${property.value}`.trimEnd()).join("\n");
 };
+/*  whether a property can be a Concise Format segment: a value carrying
+    a ";" would split the segment, and a value carrying the rationale
+    marker would not be taken for a property at all on re-parsing  */
+const segmentableMd = (property) => !property.value.includes(";") && !becauseRegex.test(property.value);
 /*  render a description statement with its optional rationale  */
 const renderDescriptionMd = (description) => description.description + (description.rationale !== undefined ?
     `, BECAUSE ${description.rationale}` : "");
@@ -23,28 +32,44 @@ const renderDescriptionMd = (description) => description.description + (descript
 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);
+/*  whether any descendant of an object carries a description which no
+    Concise Format item can carry -- a multi-line one (a fenced code
+    block, an ordered list, a blockquote, or multiple paragraphs) or one
+    carrying a ";", as only a ";"-free description stays a single segment
+    on re-parsing instead of splitting off a spurious property  */
+const complexBelowMd = (object) => object.childs.some((child) => (child.description !== undefined
+    && /[\n;]/.test(renderDescriptionMd(child.description))) || complexBelowMd(child));
+/*  render an object in the Concise Format as a list item of the
+    given nesting depth, with its childs as nested list items  */
+const renderConciseMd = (object, depth = 0) => {
+    const indent = " ".repeat(depth * 4);
     const segments = [`${object.kind}: ${object.name}${nameSuffixMd(object)}`];
-    segments.push(...object.properties.map((property) => `${property.key}: ${property.value}`));
+    /*  a property which cannot be a segment has to become a nested
+        key/value item below the item instead  */
+    const wrapped = object.properties.filter((property) => !segmentableMd(property));
+    const inline = object.properties.filter((property) => segmentableMd(property));
+    segments.push(...inline.map((property) => `${property.key}: ${property.value}`));
     if (object.description !== undefined)
         segments.push(renderDescriptionMd(object.description));
-    /*  a description terminates the item with ".", while without one the
-        ";" segment terminator has to remain, as only it lets the item be
-        recognized as a concise object again on re-parsing  */
+    /*  a description terminates the item with ".", which on re-parsing
+        marks the last segment as the description (even one shaped like
+        "<key>: <value>"), while without one the ";" segment terminator
+        has to remain, as only it lets the item be recognized as concise  */
     const item = object.description !== undefined ?
         `${indent}-   ${segments.join("; ").replace(/\.?$/, ".")}` :
         `${indent}-   ${segments.join("; ")};`;
-    return [item, ...object.childs.map((child) => renderConciseMd(child, level + 1))].join("\n");
+    return [item, renderKeyValuesMd(wrapped, `${indent}    `),
+        ...object.childs.map((child) => renderConciseMd(child, depth + 1))]
+        .filter((part) => part !== "").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
+/*  render an object in the Complex Format (levels 1-3), with childs from
+    level 4 upwards in the Concise Format -- unless a descendant carries
+    a description no concise item can carry, so all childs (as siblings
+    have to share the format) stay in the Complex Format down to heading
+    level 6 --, and the optionally derived Gradia diagram spec embedded
     as a "gradia" fenced code block below the heading  */
 const renderObjectMd = (object, level, diagrams) => {
-    const heading = `${"#".repeat(level)}${" ".repeat(4 - level)}` +
+    const heading = `${"#".repeat(level)}${" ".repeat(Math.max(1, 4 - level))}` +
         `${object.kind}: ${object.name}${nameSuffixMd(object)}`;
     const parts = [heading];
     const spec = diagrams?.get(object);
@@ -54,14 +79,16 @@ const renderObjectMd = (object, level, diagrams) => {
         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"));
+    /*  the childs share one format, as a concise item following
+        a heading would attach to the heading's object instead  */
+    if (level >= 3 && !complexBelowMd(object))
+        parts.push(object.childs.map((child) => renderConciseMd(child)).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) => {
+export const renderMarkdown = (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)  */
@@ -70,9 +97,15 @@ export const renderMarkdown = async (specification, config) => {
         for (const [object, result] of specDiagrams(specification, config))
             if (result.spec !== undefined)
                 diagrams.set(object, result.spec);
-    return specification.artifacts.map((artifact) => "---\n" +
-        `Created:  ${formatTimestamp(artifact.created)}\n` +
-        `Modified: ${formatTimestamp(artifact.modified)}\n` +
+    /*  the single frontmatter block (only recognized at the start of a
+        file on re-parse) carries the earliest creation and the latest
+        modification timestamp of all artifacts  */
+    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())));
+    return "---\n" +
+        `Created:  ${formatTimestamp(created)}\n` +
+        `Modified: ${formatTimestamp(modified)}\n` +
         "---\n\n" +
-        artifact.objects.map((object) => renderObjectMd(object, 1, diagrams)).join("\n\n")).join("\n\n") + "\n";
+        specification.artifacts.flatMap((artifact) => artifact.objects)
+            .map((object) => renderObjectMd(object, 1, diagrams)).join("\n\n") + "\n";
 };

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

@@ -1,7 +1,9 @@
 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: {
+type Heading = {
     title: string;
     subtitle?: string;
     logo: string;
-}, outline: OutlineEntry[], verbose: (msg: string) => void, css: string, theme: ThemeMapping, paper?: string) => Promise<Buffer>;
+};
+export declare const htmlToPdf: (renderHtmlPass: (tocPages?: Map<string, number>) => Promise<string>, heading: Heading, outline: OutlineEntry[], verbose: (msg: string) => void, css: string, theme: ThemeMapping, paper?: string) => Promise<Buffer>;
+export {};

package/dst/specbook-export-pdf.js

@@ -78,6 +78,49 @@ const addOutline = async (doc, entries) => {
     doc.catalog.set(PDFName.of("Outlines"), root);
     doc.catalog.set(PDFName.of("PageMode"), PDFName.of("UseOutlines"));
 };
+/*  render the header/footer templates for the page decoration: they
+    render in an isolated context, so they need their own inline styling,
+    the regular font face embedded as a data: URI, and the special
+    "pageNumber" class for the injected page number  */
+const decorationTemplates = (heading, css, theme, left, right) => {
+    const fontFace = css.match(/@font-face\s*\{[^}]*\}/)?.[0] ?? "";
+    const subtitle = heading.subtitle?.trim();
+    const headText = escapeHtml(heading.title) +
+        (subtitle !== undefined && subtitle !== "" ? ` — ${escapeHtml(subtitle)}` : "");
+    return {
+        headerTemplate: `<style>${fontFace}</style>` +
+            "<div style=\"width: 100%; margin-top: 0.8cm;\">" +
+            `<div style="margin: 0 ${right} 0 ${left}; ` +
+            "font-family: 'Source Sans 3', sans-serif; " +
+            `font-size: 8pt; color: ${theme.symbol}; border-bottom: 1px solid ${theme.border}; ` +
+            "padding-bottom: 1mm; display: flex; justify-content: space-between; " +
+            "align-items: flex-end;\">" +
+            `<span>${headText}</span>` +
+            `<img src="${escapeHtml(heading.logo)}" alt="" style="height: 3.5mm;"/>` +
+            "</div></div>",
+        footerTemplate: `<style>${fontFace}</style>` +
+            "<div style=\"width: 100%; margin-bottom: 0.8cm;\">" +
+            `<div style="margin: 0 ${right} 0 ${left}; ` +
+            "font-family: 'Source Sans 3', sans-serif; " +
+            `font-size: 8pt; color: ${theme.symbol}; display: flex; ` +
+            `justify-content: space-between; border-top: 1px solid ${theme.border}; ` +
+            "padding-top: 1mm;\">" +
+            `<span>${headText}</span>` +
+            `<span style="color: ${theme.muted}; font-weight: bold;" class="pageNumber"></span></div></div>`
+    };
+};
+/*  draw the vertical brand bar onto the left edge of the physical
+    paper of every page, as Chromium clips print content to the page
+    box (0.6rem at the 9pt print root)  */
+const drawBrandBar = async (doc, accent) => {
+    const { rgb } = await import("pdf-lib");
+    const hex = accent.match(/^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i);
+    const [r, g, b] = (hex !== null ? hex.slice(1) : ["00", "00", "00"])
+        .map((component) => parseInt(component, 16) / 255);
+    for (const page of doc.getPages())
+        page.drawRectangle({ x: 0, y: 0, width: 5.4,
+            height: page.getHeight(), color: rgb(r, g, b) });
+};
 /*  render a self-contained HTML document into a PDF via Playwright,
     re-rendering the HTML with the discovered ToC page numbers  */
 export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css, theme, paper = paperSizeDefault) => {
@@ -85,11 +128,6 @@ export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css,
     /*  the page geometry of the chosen paper size  */
     const setup = paperSetup(paper);
     const margin = setup.margin;
-    /*  the regular font face and the title/subtitle
-        text for the header/footer templates  */
-    const fontFace = css.match(/@font-face\s*\{[^}]*\}/)?.[0] ?? "";
-    const headText = escapeHtml(heading.title) +
-        (heading.subtitle !== undefined ? ` &mdash; ${escapeHtml(heading.subtitle)}` : "");
     /*  launch the Playwright Chromium browser, falling back to a
         system-installed Google Chrome if the Chromium download is missing  */
     let browser;
@@ -139,31 +177,10 @@ export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css,
             html = next;
             plain = await renderPdf(html);
         }
+        /*  render the final document, decorated with header/footer  */
         const decorated = await renderPdf(html, {
-            /*  the header/footer templates render in an isolated context,
-                so they need their own inline styling, the regular font face
-                embedded as a data: URI, and the special "title"/"pageNumber"
-                classes for the injected values  */
             displayHeaderFooter: true,
-            headerTemplate: `<style>${fontFace}</style>` +
-                "<div style=\"width: 100%; margin-top: 0.8cm;\">" +
-                `<div style="margin: 0 ${paperLength(setup, margin.left)}; ` +
-                "font-family: 'Source Sans 3', sans-serif; " +
-                `font-size: 8pt; color: ${theme.symbol}; border-bottom: 1px solid ${theme.border}; ` +
-                "padding-bottom: 1mm; display: flex; justify-content: space-between; " +
-                "align-items: flex-end;\">" +
-                `<span>${headText}</span>` +
-                `<img src="${escapeHtml(heading.logo)}" alt="" style="height: 3.5mm;"/>` +
-                "</div></div>",
-            footerTemplate: `<style>${fontFace}</style>` +
-                "<div style=\"width: 100%; margin-bottom: 0.8cm;\">" +
-                `<div style="margin: 0 ${paperLength(setup, margin.left)}; ` +
-                "font-family: 'Source Sans 3', sans-serif; " +
-                `font-size: 8pt; color: ${theme.text}; display: flex; ` +
-                `justify-content: space-between; border-top: 1px solid ${theme.border}; ` +
-                "padding-top: 1mm;\">" +
-                `<span style="color: ${theme.symbol}">${headText}</span>` +
-                `<span style="color: ${theme.muted}; font-weight: bold;" class="pageNumber"></span></div></div>`
+            ...decorationTemplates(heading, css, theme, paperLength(setup, margin.left), paperLength(setup, margin.right))
         });
         /*  a title page carries no header/footer: as Chromium decorates
             all pages unconditionally, swap the first page of the
@@ -171,7 +188,7 @@ export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css,
             the ToC page number iteration) into the decorated document
             *in place*, which keeps the decorated document's link
             destinations (and hence the internal hyperlinks) intact  */
-        const { PDFDocument, rgb } = await import("pdf-lib");
+        const { PDFDocument } = await import("pdf-lib");
         const merged = await PDFDocument.load(decorated);
         if (html.includes("class=\"titlepage\"")) {
             const source = await PDFDocument.load(plain);
@@ -182,15 +199,8 @@ export const htmlToPdf = async (renderHtmlPass, heading, outline, verbose, css,
         /*  attach the document outline for the viewer side-bar  */
         verbose("attaching PDF outline (bookmarks)");
         await addOutline(merged, outline);
-        /*  draw the vertical brand bar onto the left edge of the
-            physical paper of every page, as Chromium clips print
-            content to the page box (0.6rem at the 9pt print root)  */
-        const hex = theme.accent.match(/^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i);
-        const [r, g, b] = (hex !== null ? hex.slice(1) : ["00", "00", "00"])
-            .map((component) => parseInt(component, 16) / 255);
-        for (const pdfPage of merged.getPages())
-            pdfPage.drawRectangle({ x: 0, y: 0, width: 5.4,
-                height: pdfPage.getHeight(), color: rgb(r, g, b) });
+        /*  decorate every page with the vertical brand bar  */
+        await drawBrandBar(merged, theme.accent);
         return Buffer.from(await merged.save());
     }
     finally {