@dogsbay/format-dita 0.2.0-beta.114 → 0.2.0-beta.116

package/dist/blocks.js

@@ -1,4 +1,7 @@
-import { convertInline, trimInline, textOf, inlineSafeSnippet, conrefLedgerDetail, } from "./inline.js";
+import { inlineToDogsbayMd } from "@dogsbay/format-dogsbay-md";
+import { convertInline, elementName, idAnchor, publishImage, trimInline, textOf, inlineSafeSnippet, conrefLedgerDetail, } from "./inline.js";
+import { publishHref, publishLabel, publishLanguage, publishString } from "./types.js";
+import { anchorId } from "./anchors.js";
 const isElement = (node) => node.type === "tag";
 const isNonEmptyText = (node) => node.type === "text" && node.data.trim().length > 0;
 /** DITA note @type → callout type in the dogsbay-md vocabulary. */
@@ -14,6 +17,10 @@ const NOTE_TYPE_MAP = {
     restriction: "important",
     trouble: "warning",
 };
+/** Publishing: more DITA note types, as the closest callout dogsbay-md renders. */
+const PUBLISH_NOTE_TYPE_MAP = { notice: "important", fastpath: "tip", other: "note" };
+/** Callout types dogsbay-md renders, kept as authored when publishing. */
+const PUBLISH_CALLOUT_TYPES = new Set(["note", "tip", "important", "warning", "caution", "danger"]);
 /** Containers whose children are spliced through without a wrapper node. */
 const TRANSPARENT_CONTAINERS = new Set([
     "body", "conbody", "refbody", "taskbody", "glossdef", "abstract", "bodydiv", "sectiondiv", "div",
@@ -51,6 +58,26 @@ const noteFilterAttrs = (el, ctx) => {
         }
     }
 };
+/**
+ * A caption is inline Markdown: the title's formatting (code, emphasis,
+ * and in publishing DITA-OT's generated markup such as `<plugin>`) is kept.
+ */
+const captionText = (titleEl, ctx, owner) => {
+    // Publishing with numbering: DITA-OT's "Table 1. " / "Figure 2. " label first
+    const label = ctx.numberLabels?.get(owner);
+    const inline = trimInline(convertInline(titleEl.children, ctx));
+    return inlineToDogsbayMd(label ? [{ type: "text", text: label }, ...inline] : inline);
+};
+/**
+ * Whether a child element converts as a block. Publishing: an image is inline
+ * unless its placement is "break" (DITA's default placement is inline).
+ */
+const isBlockChild = (el, ctx) => {
+    const name = blockName(el, ctx);
+    if (ctx.publish && name === "image")
+        return el.attribs?.placement === "break";
+    return BLOCK_ELEMENTS.has(name);
+};
 const paragraphFrom = (nodes, ctx) => {
     const inline = trimInline(convertInline(nodes, ctx));
     if (inline.length === 0)
@@ -82,13 +109,15 @@ const mixedContent = (el, ctx) => {
         }
     };
     for (const child of el.children) {
-        if (isElement(child) && BLOCK_ELEMENTS.has(child.name.toLowerCase())) {
+        if (isElement(child) && (isBlockChild(child, ctx) || TRANSPARENT_CONTAINERS.has(blockName(child, ctx)))) {
             flushRun();
             sawBlock = true;
             blockNodes.push(...convertBlock(child, ctx));
             continue;
         }
-        if (isElement(child) || isNonEmptyText(child)) {
+        // Whitespace between two inline elements is a word space; at the edges
+        // of a run it is trimmed
+        if (isElement(child) || isNonEmptyText(child) || (child.type === "text" && run.length > 0)) {
             run.push(child);
         }
     }
@@ -186,7 +215,8 @@ const convertListItems = (el, ctx, itemTag) => el.children
     const viaConref = itemConref(li, ctx, "list-item") ?? definingItemNode(li, ctx, "list-item");
     if (viaConref)
         return withProvenance(viaConref, li);
-    const { inline, children } = mixedContent(li, { ...ctx, constrained: true });
+    const { inline: content, children: blocks } = mixedContent(li, { ...ctx, constrained: true });
+    const { inline, children } = withItemAnchor(content, blocks, [li.attribs?.id], ctx);
     const item = { type: "list-item" };
     if (inline)
         item.inline = inline;
@@ -205,6 +235,7 @@ const convertDefList = (el, ctx, tags = { entry: "dlentry", term: "dt", def: "dd
             const ref = entry.attribs.conref ?? entry.attribs.conkeyref;
             ctx.note(entry.attribs.conref ? "@conref" : "@conkeyref", `<${tags.entry}> pulls content from "${ref}" — ${conrefLedgerDetail(entry.attribs, undefined, ctx.conref !== undefined)}`);
         }
+        let entryAnchored = false;
         for (const part of entry.children.filter(isElement)) {
             const name = part.name.toLowerCase();
             if (name === tags.term) {
@@ -213,8 +244,10 @@ const convertDefList = (el, ctx, tags = { entry: "dlentry", term: "dt", def: "dd
                 const viaConref = constrainedConrefInline(part, ctx);
                 children.push({
                     type: "dt",
-                    inline: viaConref ?? trimInline(convertInline(part.children, ctx)),
+                    // The entry's id anchors its first term only (several terms would repeat it)
+                    inline: withInlineAnchor(viaConref ?? trimInline(convertInline(part.children, ctx)), [entryAnchored ? undefined : entry.attribs?.id, part.attribs?.id], ctx),
                 });
+                entryAnchored = true;
             }
             else if (name === tags.def) {
                 const viaConref = constrainedConrefInline(part, ctx);
@@ -223,6 +256,9 @@ const convertDefList = (el, ctx, tags = { entry: "dlentry", term: "dt", def: "dd
                     continue;
                 }
                 const { inline, children: blocks } = mixedContent(part, { ...ctx, constrained: true });
+                // Publishing: an empty definition (all its content filtered out) renders nothing
+                if (ctx.publish && !inline && blocks.length === 0)
+                    continue;
                 const dd = { type: "dd" };
                 if (inline)
                     dd.inline = inline;
@@ -234,31 +270,85 @@ const convertDefList = (el, ctx, tags = { entry: "dlentry", term: "dt", def: "dd
     }
     return { type: "deflist", children };
 };
+/**
+ * A CALS entry's column and row spans: `morerows`, and the columns from
+ * `namest` to `nameend` by their `colspec` positions. DITA-OT's
+ * preprocessing also writes the column span as `dita-ot:morecols`.
+ */
+const cellSpans = (cellEl, rowEl) => {
+    const spans = {};
+    const morerows = Number(cellEl.attribs?.morerows);
+    if (morerows > 0)
+        spans.rowspan = morerows + 1;
+    const morecols = Number(cellEl.attribs?.["dita-ot:morecols"]);
+    if (morecols > 0) {
+        spans.colspan = morecols + 1;
+    }
+    else if (cellEl.attribs?.namest && cellEl.attribs?.nameend) {
+        const tgroup = rowEl.parent?.parent;
+        const columns = new Map();
+        (tgroup?.children ?? [])
+            .filter((c) => isElement(c) && c.name.toLowerCase() === "colspec")
+            .reduce((previous, spec) => {
+            // A colspec without colnum is the column after the previous one (CALS)
+            const colnum = Number(spec.attribs?.colnum) || previous + 1;
+            if (spec.attribs?.colname)
+                columns.set(spec.attribs.colname, colnum);
+            return colnum;
+        }, 0);
+        const start = columns.get(cellEl.attribs.namest);
+        const end = columns.get(cellEl.attribs.nameend);
+        if (start && end && end > start)
+            spans.colspan = end - start + 1;
+    }
+    return spans.colspan || spans.rowspan ? spans : undefined;
+};
+const TABLE_PARTS = new Set([
+    "tgroup", "thead", "tbody", "row", "entry", "sthead", "strow", "stentry", "chhead", "chrow", "colspec", "title",
+]);
+const hasClassToken = (el, token) => ` ${el.attribs?.class ?? ""} `.includes(` ${token} `);
+const elementChildren = (el) => el.children.filter(isElement);
+const PROPERTY_KINDS = ["proptype", "propvalue", "propdesc"];
+/** A properties table cell's column: `proptype`, or with suffix "hd" a header cell (`proptypehd`). */
+const propertyKind = (cell, suffix = "") => PROPERTY_KINDS.find((k) => hasClassToken(cell, `reference/${k}${suffix}`));
+/** A properties table's columns in use, its properties that have cells, and its header row. */
+const propertiesColumns = (el) => {
+    const header = elementChildren(el).find((c) => hasClassToken(c, "reference/prophead"));
+    const propertyRows = elementChildren(el).filter((c) => hasClassToken(c, "reference/property") && elementChildren(c).some((cell) => !!propertyKind(cell)));
+    const used = PROPERTY_KINDS.filter((k) => propertyRows.some((r) => elementChildren(r).some((c) => propertyKind(c) === k)) ||
+        (header ? elementChildren(header).some((c) => propertyKind(c, "hd") === k) : false));
+    return { used, propertyRows, ...(header ? { header } : {}) };
+};
 /** CALS <table> and <simpletable> → table/tr/td tree. */
 const convertTable = (el, ctx) => {
     const rows = [];
     const headRows = [];
-    const convertRow = (rowEl, cellTags) => {
+    // Header cells: every cell of a header row; publishing also marks the key
+    // column of a simple table (@keycol, 1-based) or the first column of a
+    // CALS table with rowheader="firstcol", as DITA-OT's HTML does
+    const keycol = ctx.publish ? Number(el.attribs?.keycol ?? (el.attribs?.rowheader === "firstcol" ? 1 : 0)) || 0 : 0;
+    const convertRow = (rowEl, cellTags, header = false) => {
         // Row-level conref: a whole row can't splice as an include — ledger it
         if (rowEl.attribs?.conref || rowEl.attribs?.conkeyref) {
             const ref = rowEl.attribs.conref ?? rowEl.attribs.conkeyref;
             ctx.note(rowEl.attribs.conref ? "@conref" : "@conkeyref", `<${rowEl.name.toLowerCase()}> pulls content from "${ref}" — ${conrefLedgerDetail(rowEl.attribs, undefined, ctx.conref !== undefined)}`);
         }
         const cells = rowEl.children
-            .filter((c) => isElement(c) && cellTags.has(c.name.toLowerCase()))
-            .map((cellEl) => {
-            for (const attr of ["namest", "nameend", "morerows"]) {
-                if (cellEl.attribs?.[attr]) {
-                    ctx.note(`@${attr}`, "table cell spans are not converted — cell emitted without span");
-                }
+            .filter((c) => isElement(c) && cellTags.has(elementName(c, ctx, (n) => cellTags.has(n))))
+            .map((cellEl, index) => {
+            const cellType = header || index + 1 === keycol ? "th" : "td";
+            const spans = cellSpans(cellEl, rowEl);
+            if (cellEl.attribs?.namest && cellEl.attribs?.nameend && !spans?.colspan) {
+                ctx.note("@namest", `column span ${cellEl.attribs.namest}–${cellEl.attribs.nameend} has no matching colspec — cell emitted without its column span`);
             }
             // Cell-level conref: single-line snippets splice as an inline
             // include; anything else is ledgered
             const cellConref = constrainedConrefInline(cellEl, ctx);
             if (cellConref) {
                 return {
-                    type: "td",
+                    type: cellType,
                     children: [{ type: "paragraph", inline: cellConref }],
+                    ...(spans ? { props: spans } : {}),
                 };
             }
             // Cell content always lives in children (leading inline wrapped as a
@@ -269,9 +359,11 @@ const convertTable = (el, ctx) => {
             if (inline)
                 cellChildren.push({ type: "paragraph", inline });
             cellChildren.push(...children);
-            const cell = { type: "td" };
+            const cell = { type: cellType };
             if (cellChildren.length > 0)
                 cell.children = cellChildren;
+            if (spans)
+                cell.props = spans;
             return cell;
         });
         return { type: "tr", children: cells };
@@ -282,7 +374,8 @@ const convertTable = (el, ctx) => {
     const CHOICE_ROW_CELLS = new Set(["choption", "chdesc"]);
     const walk = (node) => {
         for (const child of node.children.filter(isElement)) {
-            const name = child.name.toLowerCase();
+            // Specialized table parts (a properties table's prophead and property rows) by @class
+            const name = elementName(child, ctx, (n) => TABLE_PARTS.has(n));
             // Row-set reuse (conref on tgroup/thead/tbody) can't splice into a
             // markdown table — ledger it so the pulled rows are never silently
             // an empty table body
@@ -295,24 +388,24 @@ const convertTable = (el, ctx) => {
                 walk(child);
             else if (name === "thead") {
                 for (const row of child.children.filter(isElement)) {
-                    if (row.name.toLowerCase() === "row")
-                        headRows.push(convertRow(row, CALS_CELLS));
+                    if (elementName(row, ctx, (n) => n === "row") === "row")
+                        headRows.push(convertRow(row, CALS_CELLS, true));
                 }
             }
             else if (name === "tbody") {
                 for (const row of child.children.filter(isElement)) {
-                    if (row.name.toLowerCase() === "row")
+                    if (elementName(row, ctx, (n) => n === "row") === "row")
                         rows.push(convertRow(row, CALS_CELLS));
                 }
             }
             else if (name === "sthead") {
-                headRows.push(convertRow(child, SIMPLE_CELLS));
+                headRows.push(convertRow(child, SIMPLE_CELLS, true));
             }
             else if (name === "strow") {
                 rows.push(convertRow(child, SIMPLE_CELLS));
             }
             else if (name === "chhead") {
-                headRows.push(convertRow(child, CHOICE_HEAD_CELLS));
+                headRows.push(convertRow(child, CHOICE_HEAD_CELLS, true));
             }
             else if (name === "chrow") {
                 rows.push(convertRow(child, CHOICE_ROW_CELLS));
@@ -326,16 +419,63 @@ const convertTable = (el, ctx) => {
         }
     };
     walk(el);
+    // Publishing: a properties table's columns are the type, value and description columns
+    // its header or any property uses (DITA-OT's hasType, hasValue, hasDesc); each row
+    // aligns its cells to them, a property with no cells is dropped, and a header cell
+    // missing for a column in use is DITA-OT's generated label ("Type", "Value", "Description")
+    if (ctx.publish && hasClassToken(el, "reference/properties")) {
+        const { used, propertyRows, header } = propertiesColumns(el);
+        rows.length = 0;
+        for (const row of propertyRows) {
+            const converted = convertRow(row, SIMPLE_CELLS);
+            const cellEls = elementChildren(row).filter((c) => !!propertyKind(c));
+            rows.push({
+                type: "tr",
+                children: used.map((k) => {
+                    const i = cellEls.findIndex((c) => propertyKind(c) === k);
+                    return i >= 0 ? converted.children[i] : { type: "td" };
+                }),
+            });
+        }
+        const lang = publishLanguage(el, ctx.publish);
+        const label = {
+            proptype: publishString(ctx.publish, lang, "Type"),
+            propvalue: publishString(ctx.publish, lang, "Value"),
+            propdesc: publishString(ctx.publish, lang, "Description"),
+        };
+        const authored = header ? convertRow(header, SIMPLE_CELLS, true) : undefined;
+        const headerCells = header ? elementChildren(header).filter((c) => !!propertyKind(c, "hd")) : [];
+        headRows.length = 0;
+        headRows.push({
+            type: "tr",
+            children: used.map((k) => {
+                const i = headerCells.findIndex((c) => propertyKind(c, "hd") === k);
+                return i >= 0 && authored ? authored.children[i] : { type: "th", children: [{ type: "paragraph", inline: [{ type: "text", text: label[k] }] }] };
+            }),
+        });
+    }
+    // Publishing: DITA-OT generates the "Option | Description" header of a
+    // choice table that has none
+    if (ctx.publish && el.name.toLowerCase() === "choicetable" && headRows.length === 0) {
+        const th = (text) => ({
+            type: "th",
+            children: [{ type: "paragraph", inline: [{ type: "text", text }] }],
+        });
+        const lang = publishLanguage(el, ctx.publish);
+        headRows.push({ type: "tr", children: [th(publishString(ctx.publish, lang, "Option")), th(publishString(ctx.publish, lang, "Description"))] });
+    }
     const table = {
         type: "table",
         children: [
             ...(headRows.length > 0 ? [{ type: "thead", children: headRows }] : []),
             { type: "tbody", children: rows },
         ],
+        // Publishing: a table without a header row has none (DITA-OT does not promote a row)
+        ...(ctx.publish && headRows.length === 0 ? { meta: { headerless: true } } : {}),
     };
     const titleEl = el.children
         .filter(isElement)
-        .find((c) => c.name.toLowerCase() === "title");
+        .find((c) => blockName(c, ctx) === "title");
     if (titleEl) {
         // Caption is a plain-string prop — a conref'd title can't carry an
         // include directive, so ledger it instead of emitting empty text
@@ -343,7 +483,7 @@ const convertTable = (el, ctx) => {
             const ref = titleEl.attribs.conref ?? titleEl.attribs.conkeyref;
             ctx.note(titleEl.attribs.conref ? "@conref" : "@conkeyref", `<title> (table caption) pulls content from "${ref}" — ${conrefLedgerDetail(titleEl.attribs, undefined, ctx.conref !== undefined)}`);
         }
-        table.props = { caption: textOf(titleEl.children).trim() };
+        table.props = { caption: captionText(titleEl, ctx, el) };
     }
     return table;
 };
@@ -395,16 +535,36 @@ const convertSteps = (el, ctx, type) => {
         const viaConref = itemConref(stepEl, ctx, "step") ?? definingItemNode(stepEl, ctx, "step");
         if (viaConref)
             return withProvenance(viaConref, stepEl);
-        const { inline, children: blocks } = convertStepContent(stepEl, { ...ctx, constrained: true });
+        const { inline: content, children: blocks } = convertStepContent(stepEl, { ...ctx, constrained: true });
+        // Publishing: DITA-OT labels optional and required steps
+        const importance = stepEl.attribs?.importance;
+        const stepLabel = ctx.publish && (importance === "optional" || importance === "required")
+            ? publishLabel(ctx.publish, publishLanguage(stepEl, ctx.publish), importance === "optional" ? "Optional" : "Required")
+            : undefined;
+        const labelled = stepLabel
+            ? [{ type: "text", text: stepLabel, bold: true }, { type: "text", text: " " }, ...(content ?? [])]
+            : content;
+        const { inline, children } = withItemAnchor(labelled, blocks, [stepEl.attribs?.id], ctx);
         const step = { type: "step" };
         if (inline)
             step.inline = inline;
-        if (blocks.length > 0)
-            step.children = blocks;
+        if (children.length > 0)
+            step.children = children;
         return withProvenance(step, stepEl);
     });
     return { type, children };
 };
+/**
+ * Publishing: a task with one step renders it as a paragraph and its
+ * content, not a one-item list, as DITA-OT's HTML does.
+ */
+const publishSteps = (el, ctx, type) => {
+    const steps = convertSteps(el, ctx, type);
+    const only = steps.children?.length === 1 ? steps.children[0] : undefined;
+    if (!ctx.publish || type !== "steps" || !only || only.type !== "step")
+        return [withProvenance(steps, el)];
+    return [...(only.inline ? [{ type: "paragraph", inline: only.inline }] : []), ...(only.children ?? [])];
+};
 /**
  * Standalone content of an item-level element (<li>, <step>, …) for
  * conref snippet extraction: leading inline as a paragraph, block
@@ -426,16 +586,186 @@ const TASK_SECTION_HEADINGS = {
     postreq: "What to do next",
     tasktroubleshooting: "Troubleshooting",
 };
+/** Publishing: where a topic's related links go (see publishDitaTemp). */
+export const PUBLISH_RELATED_LINKS_MARKER = "<!-- dogsbay:related-links -->";
+/** Publishing: where a topic's required links go, at the start of its body (see publishDitaTemp). */
+export const PUBLISH_PREREQUISITES_MARKER = /<!-- dogsbay:prerequisites:([^ ]*) -->/g;
+const prerequisitesMarker = (topicId) => `<!-- dogsbay:prerequisites:${topicId} -->`;
+/** DITA-OT's string ids for the task labels. */
+const TASK_LABEL_IDS = {
+    prereq: "task_prereq", context: "task_context", steps: "task_procedure",
+    "steps-unordered": "task_procedure_unordered", result: "task_results", postreq: "task_postreq",
+};
+const publishTaskLabel = (name, ctx, el) => ctx.publish?.taskLabels && TASK_LABEL_IDS[name]
+    ? [{ type: "heading", props: { level: ctx.headingLevel }, inline: [{ type: "text", text: publishString(ctx.publish, publishLanguage(el ?? null, ctx.publish), TASK_LABEL_IDS[name]) }] }]
+    : [];
 /** Block-level DITA elements (used to split mixed content). */
 const BLOCK_ELEMENTS = new Set([
     "p", "shortdesc", "note", "codeblock", "pre", "screen", "msgblock", "ul", "ol", "sl", "dl", "parml", "table", "simpletable",
     "fig", "image", "section", "example", "steps", "steps-unordered", "substeps", "lq", "object",
-    "prereq", "context", "result", "postreq", "tasktroubleshooting", "choices", "choicetable",
+    "prereq", "context", "result", "postreq", "tasktroubleshooting", "choices", "choicetable", "syntaxdiagram",
 ]);
+const SYNTAX_GROUPS = new Set(["groupseq", "groupchoice", "groupcomp"]);
+/**
+ * Publishing: a syntax diagram's inline form, as DITA-OT's HTML writes it
+ * (syntax-braces.xsl): keywords bold code, operators code, variables
+ * italic, `[ ]` around optional parts, `{ a | b }` for choices.
+ */
+const syntaxInline = (el, ctx) => {
+    const out = [];
+    const text = (t) => void out.push({ type: "text", text: t });
+    for (const child of el.children) {
+        if (child.type === "text") {
+            text(child.data.replace(/\s+/g, " "));
+            continue;
+        }
+        if (!isElement(child))
+            continue;
+        const name = blockName(child, ctx) === "syntaxdiagram" ? "syntaxdiagram" : elementName(child, ctx, (n) => SYNTAX_GROUPS.has(n) || ["kwd", "var", "oper", "delim", "sep", "fragref", "repsep", "synnote", "synnoteref", "title"].includes(n));
+        const inChoice = elementName(el, ctx, (n) => SYNTAX_GROUPS.has(n)) === "groupchoice";
+        const hasPreceding = (child.prev ? el.children.slice(0, el.children.indexOf(child)).some(isElement) : false);
+        const optional = child.attribs?.importance === "optional";
+        const choiceBar = inChoice && hasPreceding ? " | " : "";
+        const value = collapseText(child);
+        if (SYNTAX_GROUPS.has(name)) {
+            text(`${choiceBar ? " |" : ""}${optional ? " [" : ""}${name === "groupchoice" ? " {" : ""} `);
+            out.push(...syntaxInline(child, ctx));
+            text(` ${name === "groupchoice" ? "} " : ""}${optional ? "] " : ""}`);
+        }
+        else if (name === "kwd") {
+            text(choiceBar);
+            out.push({ type: "code", text: `${optional ? "[" : ""}${value}${optional ? "]" : ""}`, bold: true });
+            text(" ");
+        }
+        else if (name === "var") {
+            // DITA-OT writes the choice bar and brackets inside the variable's italics
+            text(" ");
+            out.push({ type: "text", text: `${choiceBar ? "| " : ""}${optional ? "[" : ""}${value}${optional ? "]" : ""}`, italic: true });
+            text(" ");
+        }
+        else if (name === "oper") {
+            text(choiceBar);
+            out.push({ type: "code", text: value });
+        }
+        else if (name === "fragref") {
+            // DITA-OT links a fragment reference to the fragment by its title text
+            out.push({ type: "link", href: `#${fragmentSlug(value)}`, children: [{ type: "code", text: `<${value}>` }] });
+        }
+        else if (name === "synnote" && ctx.publish && ctx.footnotes) {
+            // A syntax diagram note is a footnote (DITA-OT lists them at the end of the page)
+            const label = String(ctx.footnotes.filter((f) => !f.callout).length + 1);
+            ctx.footnotes.push({ label, el: child });
+            out.push({ type: "footnote-ref", label });
+        }
+        else if (name === "delim" || name === "sep") {
+            text(value);
+        }
+    }
+    return out;
+};
+/** The anchor of a syntax diagram fragment, from its title text (what a fragref names). */
+const fragmentSlug = (title) => `fragment-${title.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")}`;
+const collapseText = (el) => textOf(el.children).replace(/\s+/g, " ").trim();
+const convertSyntaxDiagram = (el, ctx) => {
+    const out = [];
+    const groupName = (c) => elementName(c, ctx, (n) => SYNTAX_GROUPS.has(n) || n === "fragment" || n === "title");
+    for (const child of el.children.filter(isElement)) {
+        const name = groupName(child);
+        if (name === "title") {
+            out.push({ type: "heading", props: { level: Math.min(6, ctx.headingLevel + 1) }, inline: trimInline(convertInline(child.children, ctx)) });
+        }
+        else if (name === "fragment") {
+            for (const part of child.children.filter(isElement)) {
+                if (groupName(part) === "title") {
+                    out.push({ type: "heading", props: { level: Math.min(6, ctx.headingLevel + 2), id: fragmentSlug(collapseText(part)) }, inline: trimInline(convertInline(part.children, ctx)) });
+                }
+                else if (SYNTAX_GROUPS.has(groupName(part))) {
+                    const inline = trimInline(syntaxInline({ ...child, children: [part] }, ctx));
+                    if (inline.length)
+                        out.push({ type: "blockquote", children: [{ type: "paragraph", inline }] });
+                }
+            }
+        }
+        else if (SYNTAX_GROUPS.has(name)) {
+            const inline = trimInline(syntaxInline({ ...el, children: [child] }, ctx));
+            if (inline.length)
+                out.push({ type: "paragraph", inline });
+        }
+    }
+    return out;
+};
+/** Element names convertBlock handles, for publishing's `@class` fallback. */
+const isKnownBlock = (name) => BLOCK_ELEMENTS.has(name) || TRANSPARENT_CONTAINERS.has(name) || name === "foreign" || name === "unknown" || name === "required-cleanup" ||
+    ["title", "prolog", "related-links", "draft-comment", "data", "indexterm", "substeps", "sli", "li", "dlentry", "dt", "dd", "syntaxdiagram"].includes(name);
+/** The name to convert a block as (see elementName). */
+const blockName = (el, ctx) => elementName(el, ctx, isKnownBlock);
 /** Whether an element name converts as a standalone block (conref-extractable). */
 export const isBlockTarget = (name) => BLOCK_ELEMENTS.has(name);
+/** Elements whose @id already becomes an anchor (a heading id) or never is a link target. */
+const ANCHORED_ELSEWHERE = new Set(["title", "related-links", "prolog", "data", "indexterm", "draft-comment", "required-cleanup", "foreign", "unknown"]);
+/**
+ * Publishing: an element with an @id gets an anchor before its blocks, so
+ * cross-references to paragraphs, notes, tables and figures land, as they do on
+ * DITA-OT's pages. (Headings carry their own id.)
+ */
 export function convertBlock(el, ctx) {
-    const name = el.name.toLowerCase();
+    const out = convertBlockContent(el, ctx);
+    const id = el.attribs?.id;
+    if (!ctx.publish || !id || ANCHORED_ELSEWHERE.has(blockName(el, ctx)))
+        return out;
+    const anchor = anchorId(ctx, id);
+    // An empty paragraph or division still keeps its id (DITA-OT writes the empty element)
+    if (out.length === 0)
+        return KEEPS_EMPTY.has(blockName(el, ctx)) ? [{ type: "html", html: idAnchor(anchor) }] : out;
+    // A titled section's heading carries the id
+    if (out.some((n) => n.type === "heading" && n.props?.id === anchor))
+        return out;
+    // Before a paragraph, the anchor is the start of its text (a separate block would be a paragraph of its own)
+    if (out[0].type === "paragraph" && out[0].inline) {
+        return [{ ...out[0], inline: [{ type: "html-inline", html: idAnchor(anchor) }, ...out[0].inline] }, ...out.slice(1)];
+    }
+    return [{ type: "html", html: idAnchor(anchor) }, ...out];
+}
+/** Elements DITA-OT's HTML writes, with their id, even when they have no content. */
+const KEEPS_EMPTY = new Set(["p", "div", "bodydiv", "sectiondiv", "section", "example"]);
+/** Publishing: the anchor elements for ids (none outside publishing). */
+const anchorNodes = (ids, ctx) => ctx.publish ? ids.filter((id) => !!id).map((id) => ({ type: "html-inline", html: idAnchor(anchorId(ctx, id)) })) : [];
+/** Inline anchors for an item's @id (terms), first in its text. */
+const withInlineAnchor = (inline, ids, ctx) => {
+    const anchors = anchorNodes(ids, ctx);
+    return anchors.length ? [...anchors, ...(inline ?? [])] : inline;
+};
+/** Anchors at the start of the first paragraph in blocks (inside a note or quotation too), or undefined when none starts them. */
+const prependToFirstParagraph = (blocks, anchors) => {
+    const [first, ...rest] = blocks;
+    if (!first)
+        return undefined;
+    if (first.type === "paragraph" && first.inline)
+        return [{ ...first, inline: [...anchors, ...first.inline] }, ...rest];
+    if ((first.type === "callout" || first.type === "blockquote") && first.children) {
+        const inner = prependToFirstParagraph(first.children, anchors);
+        return inner && [{ ...first, children: inner }, ...rest];
+    }
+    return undefined;
+};
+/**
+ * Anchors for an item's @id (list items, steps, definitions): first in its text, or, when
+ * the item has only blocks, in its first paragraph (an anchor alone would add an empty
+ * paragraph to the item).
+ */
+const withItemAnchor = (inline, children, ids, ctx) => {
+    const anchors = anchorNodes(ids, ctx);
+    if (anchors.length === 0)
+        return { inline, children };
+    if (!inline?.length) {
+        const anchored = prependToFirstParagraph(children, anchors);
+        if (anchored)
+            return { inline, children: anchored };
+    }
+    return { inline: [...anchors, ...(inline ?? [])], children };
+};
+function convertBlockContent(el, ctx) {
+    const name = blockName(el, ctx);
     noteFilterAttrs(el, ctx);
     // Defining site: this element was extracted into a reuse snippet — emit
     // the include here too, so exactly ONE copy of the text survives
@@ -487,8 +817,16 @@ export function convertBlock(el, ctx) {
         }
     }
     if (TRANSPARENT_CONTAINERS.has(name)) {
+        // Publishing: a topic body starts with the topic's "Prerequisites" links, when it has any
+        const topicId = el.parent?.attribs?.id;
+        if (ctx.publish && name.endsWith("body") && topicId && !name.includes("div")) {
+            return [{ type: "html", html: prerequisitesMarker(topicId) }, ...convertChildren(el, ctx)];
+        }
         return convertChildren(el, ctx);
     }
+    // Publishing: DITA-OT's HTML shows none of these (MathML needs a plugin; cleanup needs args.draft)
+    if (ctx.publish && (name === "foreign" || name === "unknown" || name === "required-cleanup"))
+        return [];
     switch (name) {
         case "p":
         case "shortdesc": {
@@ -504,7 +842,11 @@ export function convertBlock(el, ctx) {
             return out;
         }
         case "note": {
-            const type = NOTE_TYPE_MAP[el.attribs?.type ?? "note"] ?? "note";
+            const authored = el.attribs?.type ?? "note";
+            // Publishing keeps every type dogsbay-md renders (caution, danger)
+            const type = ctx.publish && PUBLISH_CALLOUT_TYPES.has(authored)
+                ? authored
+                : NOTE_TYPE_MAP[authored] ?? (ctx.publish ? PUBLISH_NOTE_TYPE_MAP[authored] : undefined) ?? "note";
             if (el.attribs?.type && !NOTE_TYPE_MAP[el.attribs.type]) {
                 ctx.note("@type", `<note type="${el.attribs.type}"> mapped to plain note callout`);
             }
@@ -521,7 +863,12 @@ export function convertBlock(el, ctx) {
         case "pre":
         case "screen":
         case "msgblock": {
-            const language = el.attribs?.outputclass ?? "";
+            const outputclass = el.attribs?.outputclass ?? "";
+            // Publishing: DITA-OT's language classes (language-xml, syntax-bash)
+            // name the language; other output classes are not languages
+            const language = ctx.publish
+                ? (/(?:^|\s)(?:language|syntax)-(\S+)/.exec(outputclass)?.[1] ?? "")
+                : outputclass;
             const content = textOf(el.children).replace(/^\n/, "").replace(/\s+$/, "");
             // Content in BOTH html and props.code: the serializer's block path
             // reads html, its HTML-table path (code inside cells) reads props.code
@@ -558,14 +905,35 @@ export function convertBlock(el, ctx) {
             return [withProvenance(convertDefList(el, ctx, { entry: "plentry", term: "pt", def: "pd" }), el)];
         case "table":
         case "simpletable":
+            // Publishing: DITA-OT drops a properties table none of whose properties has a cell
+            if (ctx.publish && hasClassToken(el, "reference/properties") && propertiesColumns(el).propertyRows.length === 0)
+                return [];
             return [withProvenance(convertTable(el, ctx), el)];
+        case "syntaxdiagram":
+            if (ctx.publish)
+                return convertSyntaxDiagram(el, ctx);
+            // Migration: as any unrecognized block
+            {
+                const children = convertChildren(el, ctx);
+                ctx.note(`<${name}>`, children.length > 0
+                    ? "unrecognized block element — children kept, wrapper dropped"
+                    : "unrecognized block element dropped");
+                return children;
+            }
         case "fig": {
             const titleEl = el.children
                 .filter(isElement)
-                .find((c) => c.name.toLowerCase() === "title");
+                .find((c) => blockName(c, ctx) === "title");
             const imageEl = el.children
                 .filter(isElement)
                 .find((c) => c.name.toLowerCase() === "image");
+            // Publishing: every figure converts its content (an image with its size, and anything else in it)
+            if (ctx.publish) {
+                const body = convertChildren(el, ctx, new Set(["title"]));
+                return titleEl
+                    ? [withProvenance({ type: "figure", props: { caption: captionText(titleEl, ctx, el) }, children: body }, el)]
+                    : body;
+            }
             if (imageEl) {
                 const figure = {
                     type: "figure",
@@ -581,7 +949,7 @@ export function convertBlock(el, ctx) {
                         },
                     ],
                     ...(titleEl
-                        ? { props: { caption: textOf(titleEl.children).trim() } }
+                        ? { props: { caption: captionText(titleEl, ctx, el) } }
                         : {}),
                 };
                 return [withProvenance(figure, el)];
@@ -609,6 +977,10 @@ export function convertBlock(el, ctx) {
                 }
                 return [];
             }
+            if (ctx.publish) {
+                const { alt, attrs } = publishImage(el, ctx.publish);
+                return [withProvenance({ type: "image", props: { src, alt: alt ?? "", ...(attrs ?? {}) } }, el)];
+            }
             const node = {
                 type: "image",
                 props: {
@@ -623,7 +995,7 @@ export function convertBlock(el, ctx) {
             const out = [];
             const titleEl = el.children
                 .filter(isElement)
-                .find((c) => c.name.toLowerCase() === "title");
+                .find((c) => blockName(c, ctx) === "title");
             if (titleEl) {
                 // <title conref=…/> — heading text pulled from elsewhere
                 const titleConref = constrainedConrefInline(titleEl, ctx);
@@ -633,16 +1005,17 @@ export function convertBlock(el, ctx) {
                     // cross-topic xref fragments (renamed to #elementid) must land
                     props: {
                         level: ctx.headingLevel,
-                        ...(el.attribs?.id ? { id: el.attribs.id } : {}),
+                        ...(el.attribs?.id ? { id: anchorId(ctx, el.attribs.id) } : {}),
                     },
                     inline: titleConref ?? trimInline(convertInline(titleEl.children, ctx)),
                 }, el));
             }
-            else if (name === "example") {
+            else if (name === "example" && (!ctx.publish || (ctx.publish.taskLabels && el.parent && isElement(el.parent) && el.parent.name.toLowerCase() === "taskbody"))) {
+                // Publishing: DITA-OT labels only an untitled task example, and only with task labels on
                 out.push({
                     type: "heading",
                     props: { level: ctx.headingLevel },
-                    inline: [{ type: "text", text: "Example" }],
+                    inline: [{ type: "text", text: ctx.publish ? publishString(ctx.publish, publishLanguage(el, ctx.publish), "task_example") : "Example" }],
                 });
             }
             const inner = { ...ctx, headingLevel: Math.min(6, ctx.headingLevel + 1) };
@@ -651,15 +1024,24 @@ export function convertBlock(el, ctx) {
         }
         case "steps":
         case "steps-unordered":
-            return [withProvenance(convertSteps(el, ctx, "steps"), el)];
+            // Publishing: unordered steps are a bulleted list, as DITA-OT renders them
+            if (ctx.publish && name === "steps-unordered") {
+                const steps = convertSteps(el, ctx, "steps");
+                const items = (steps.children ?? []).map((step) => ({ ...step, type: "list-item" }));
+                return [...publishTaskLabel(name, ctx, el), withProvenance({ type: "unordered-list", children: items }, el)];
+            }
+            return [...publishTaskLabel(name, ctx, el), ...publishSteps(el, ctx, "steps")];
         case "substeps":
             return [withProvenance(convertSteps(el, ctx, "substeps"), el)];
         case "context":
-            return convertChildren(el, ctx);
+            return [...publishTaskLabel(name, ctx, el), ...convertChildren(el, ctx)];
         case "prereq":
         case "result":
         case "postreq":
         case "tasktroubleshooting": {
+            // Publishing: DITA-OT's HTML titles these sections only with task labels on
+            if (ctx.publish)
+                return [...publishTaskLabel(name, ctx, el), ...convertChildren(el, ctx)];
             const heading = {
                 type: "heading",
                 props: { level: ctx.headingLevel },
@@ -678,13 +1060,28 @@ export function convertBlock(el, ctx) {
             if (inline)
                 body.push({ type: "paragraph", inline });
             body.push(...children);
+            // Publishing: DITA-OT cites the quote's source (@reftitle, linked to @href)
+            const cite = el.attribs?.reftitle ?? el.attribs?.href;
+            if (ctx.publish && cite) {
+                const text = { type: "text", text: cite, italic: true };
+                // A link to a DITA topic goes to its page, as an xref does
+                const href = el.attribs?.href;
+                const external = !!href && (el.attribs?.scope === "external" || /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(href));
+                const target = href && !external && /\.(dita|xml)(#|$)/i.test(href) ? publishHref(ctx.publish, href) : href;
+                body.push({ type: "paragraph", inline: [target ? { type: "link", href: target, children: [text] } : text] });
+            }
             return [{ type: "blockquote", children: body }];
         }
         case "title":
             // Titles are handled by their parents (topic/section/fig/table)
             return [];
-        case "prolog":
         case "related-links":
+            // Publishing: a placeholder where DITA-OT renders the topic's related
+            // links (after its body, before nested topics); publishDitaTemp fills it
+            if (ctx.publish)
+                return [{ type: "html", html: PUBLISH_RELATED_LINKS_MARKER }];
+        // falls through
+        case "prolog":
             ctx.note(`<${name}>`, "metadata/related-links dropped — links belong in the topic map (reltable design pending)");
             return [];
         case "draft-comment":
@@ -712,10 +1109,10 @@ export function convertChildren(el, ctx, skip = new Set()) {
     };
     for (const child of el.children) {
         if (isElement(child)) {
-            const name = child.name.toLowerCase();
+            const name = blockName(child, ctx);
             if (skip.has(name))
                 continue;
-            if (BLOCK_ELEMENTS.has(name) || TRANSPARENT_CONTAINERS.has(name) || name === "title" ||
+            if (isBlockChild(child, ctx) || TRANSPARENT_CONTAINERS.has(name) || name === "title" ||
                 name === "prolog" || name === "related-links" || name === "draft-comment") {
                 flushInline();
                 out.push(...convertBlock(child, ctx));
@@ -724,7 +1121,7 @@ export function convertChildren(el, ctx, skip = new Set()) {
             // Inline element loose in a body: accumulate into a paragraph
             inlineRun.push(child);
         }
-        else if (isNonEmptyText(child)) {
+        else if (isNonEmptyText(child) || (child.type === "text" && inlineRun.length > 0)) {
             inlineRun.push(child);
         }
     }