@dogsbay/format-dita 0.2.0-beta.124 → 0.2.0-beta.125

package/README.md

@@ -38,6 +38,11 @@ emit `{% include %}` so one canonical copy of reused text survives. Use
 `dogsbay import-dita --no-conref-includes` to keep conrefs on the ledger
 instead.
 
+**Lines.** Every conversion note carries `line`, the source line of the
+element that raised it (or of the block being converted), so a host can point
+at it. `{ sourceLines: true }` also puts each block's line on `meta.line`, which
+`@dogsbay/render-html` writes as `data-line` when asked (`dataLines: true`).
+
 **Specializations in raw source:** a file as authored has no `@class`, so
 an element is known only by its name, and a specialization the converter
 does not know by name (a `<troubleshooting>` topic, a hazard statement's

package/dist/blocks.js

@@ -1,5 +1,5 @@
 import { inlineToDogsbayMd } from "@dogsbay/format-dogsbay-md/browser";
-import { convertInline, elementName, idAnchor, publishImage, trimInline, textOf, inlineSafeSnippet, conrefLedgerDetail, } from "./inline.js";
+import { convertInline, elementName, isKnownInline, idAnchor, publishImage, trimInline, textOf, inlineSafeSnippet, conrefLedgerDetail, } from "./inline.js";
 import { publishHref, publishLabel, publishLanguage, publishString } from "./types.js";
 import { anchorId } from "./anchors.js";
 import { DB_QUALIFIERS, outputTokens, youtubeId } from "./qualifiers.js";
@@ -52,6 +52,13 @@ const withProvenance = (node, el) => {
     }
     return node;
 };
+/** A list item or step: its source line (ParseOptions.sourceLines), as convertBlock gives a block. */
+const atLine = (node, el, ctx) => {
+    const line = ctx.lineOf?.(el);
+    if (line !== undefined && node.meta?.line === undefined)
+        node.meta = { ...node.meta, line };
+    return node;
+};
 const noteFilterAttrs = (el, ctx) => {
     for (const attr of ["audience", "platform", "product", "props", "otherprops", "rev"]) {
         if (el.attribs?.[attr]) {
@@ -77,8 +84,29 @@ const isBlockChild = (el, ctx) => {
     const name = blockName(el, ctx);
     if (ctx.publish && name === "image")
         return el.attribs?.placement === "break";
-    return BLOCK_ELEMENTS.has(name);
+    return BLOCK_ELEMENTS.has(name) || (isUnknownElement(el, ctx) && holdsBlocks(el, ctx));
 };
+/**
+ * An element the converter knows by neither a block nor an inline name (a
+ * custom specialization). Both resolutions count: with @class, a
+ * specialization of <fn> or <ph> resolves to an inline name, not a block one.
+ */
+const isUnknownElement = (el, ctx) => !isKnownBlock(elementName(el, ctx, isKnownBlock)) && !isKnownInline(elementName(el, ctx, isKnownInline));
+/**
+ * Whether an unknown element holds block content (a <p>, a list), directly or
+ * through other unknown wrappers. Such an element is a block wrapper: read as
+ * inline, its paragraphs and lists were flattened into one run of text, with
+ * an "unrecognized inline element" note for each of them. An image does not
+ * count: it sits in a sentence as often as not (an icon in a UI label).
+ */
+const holdsBlocks = (el, ctx) => el.children.some((c) => {
+    if (!isElement(c))
+        return false;
+    const name = blockName(c, ctx);
+    if (name === "image")
+        return false;
+    return BLOCK_ELEMENTS.has(name) || TRANSPARENT_CONTAINERS.has(name) || (isUnknownElement(c, ctx) && holdsBlocks(c, ctx));
+});
 const paragraphFrom = (nodes, ctx) => {
     const inline = trimInline(convertInline(nodes, ctx));
     if (inline.length === 0)
@@ -221,7 +249,7 @@ const convertListItems = (el, ctx, itemTag) => el.children
     .map((li) => {
     const viaConref = itemConref(li, ctx, "list-item") ?? definingItemNode(li, ctx, "list-item");
     if (viaConref)
-        return withProvenance(viaConref, li);
+        return atLine(withProvenance(viaConref, li), li, ctx);
     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" };
@@ -229,7 +257,7 @@ const convertListItems = (el, ctx, itemTag) => el.children
         item.inline = inline;
     if (children.length > 0)
         item.children = children;
-    return withProvenance(item, li);
+    return atLine(withProvenance(item, li), li, ctx);
 });
 /** Components an `@outputclass` `db-*` token selects, per element. */
 const DB_COMPONENTS = {
@@ -966,7 +994,7 @@ const convertSteps = (el, ctx, type) => {
         .map((stepEl) => {
         const viaConref = itemConref(stepEl, ctx, "step") ?? definingItemNode(stepEl, ctx, "step");
         if (viaConref)
-            return withProvenance(viaConref, stepEl);
+            return atLine(withProvenance(viaConref, stepEl), stepEl, ctx);
         const { inline: content, children: blocks } = convertStepContent(stepEl, { ...ctx, constrained: true });
         // Publishing: DITA-OT labels optional and required steps
         const importance = stepEl.attribs?.importance;
@@ -982,7 +1010,7 @@ const convertSteps = (el, ctx, type) => {
             step.inline = inline;
         if (children.length > 0)
             step.children = children;
-        return withProvenance(step, stepEl);
+        return atLine(withProvenance(step, stepEl), stepEl, ctx);
     });
     return { type, children };
 };
@@ -1141,6 +1169,27 @@ const ANCHORED_ELSEWHERE = new Set(["title", "related-links", "prolog", "data",
  * DITA-OT's pages. (Headings carry their own id.)
  */
 export function convertBlock(el, ctx) {
+    // A note raised while converting this element takes its line
+    const outer = ctx.position?.el;
+    if (ctx.position)
+        ctx.position.el = el;
+    try {
+        const out = convertBlockThemed(el, ctx);
+        // Source lines: each node this element became starts at its line
+        // (nested blocks came through here first and keep their own)
+        const line = ctx.lineOf?.(el);
+        if (line !== undefined)
+            for (const node of out)
+                if (node.meta?.line === undefined)
+                    node.meta = { ...node.meta, line };
+        return out;
+    }
+    finally {
+        if (ctx.position)
+            ctx.position.el = outer;
+    }
+}
+function convertBlockThemed(el, ctx) {
     const out = convertBlockAnchored(el, ctx);
     // A scoped theme wraps the element's whole output, its anchor included
     const theme = /(^|\s)db-theme-/i.test(el.attribs?.outputclass ?? "") ? themeOf(el, ctx) : undefined;

package/dist/class-defaults-apply.d.ts

@@ -1,4 +1,4 @@
-import type { AnyNode } from "domhandler";
+import type { AnyNode, Element } from "domhandler";
 /** An element's DITA 1.3 default @class (`inMap`: inside a map document), or undefined for a name the DTDs do not declare. */
 export declare const classDefault: (name: string, inMap?: boolean) => string | undefined;
 /**
@@ -12,4 +12,4 @@ export declare const classDefault: (name: string, inMap?: boolean) => string | u
  * specialization: MathML, SVG), which are not DITA elements and are left
  * untouched. A DITA element inside one (`<mathmlref>`, `<svgref>`) is classed.
  */
-export declare function applyClassDefaults(nodes: AnyNode[]): string[];
+export declare function applyClassDefaults(nodes: AnyNode[], firstOf?: Map<string, Element>): string[];

package/dist/class-defaults-apply.js

@@ -14,7 +14,7 @@ export const classDefault = (name, inMap = false) => (inMap ? own(DITA_MAP_CLASS
  * specialization: MathML, SVG), which are not DITA elements and are left
  * untouched. A DITA element inside one (`<mathmlref>`, `<svgref>`) is classed.
  */
-export function applyClassDefaults(nodes) {
+export function applyClassDefaults(nodes, firstOf) {
     const root = nodes.find(isTag);
     const inMap = !!root && (["map", "bookmap", "subjectScheme"].includes(root.name) || ` ${root.attribs?.class ?? ""} `.includes(" map/map "));
     const unknown = new Set();
@@ -25,8 +25,10 @@ export function applyClassDefaults(nodes) {
             const value = classDefault(el.name, inMap);
             if (value)
                 el.attribs = { ...el.attribs, class: value };
-            else if (el.name !== "dita" && !inForeign)
+            else if (el.name !== "dita" && !inForeign && !unknown.has(el.name)) {
                 unknown.add(el.name);
+                firstOf?.set(el.name, el);
+            }
         }
         const foreign = inForeign || ` ${el.attribs?.class ?? ""} `.includes(" topic/foreign ");
         for (const child of el.children)

package/dist/inline.d.ts

@@ -11,6 +11,16 @@ export interface InlineContext {
     publish?: PublishContext;
     /** Every element carries @class (DTD defaults filled in): resolve unknown names by it, as publishing does. */
     classes?: boolean;
+    /**
+     * The element being converted, shared by every context derived from the
+     * topic's (a note takes its line from it). Set by convertBlock and, for each
+     * element, convertInline.
+     */
+    position?: {
+        el?: Element;
+    };
+    /** ParseOptions.sourceLines: an element's 1-based source line. */
+    lineOf?: (el: Element) => number | undefined;
     /** Publishing: trademarks already marked in this topic (DITA-OT marks only the first). */
     trademarks?: Set<string>;
     /** Publishing: the number label of each titled table and figure ("Table 1. "). */

package/dist/inline.js

@@ -216,6 +216,19 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
         }
         if (!isElement(node))
             continue;
+        const outer = ctx.position?.el;
+        if (ctx.position)
+            ctx.position.el = node;
+        try {
+            convertInlineElement(node);
+        }
+        finally {
+            if (ctx.position)
+                ctx.position.el = outer;
+        }
+    }
+    return mergeAdjacentText(out);
+    function convertInlineElement(node) {
         const name = elementName(node, ctx, isKnownInline);
         const children = node.children;
         // Publishing: an inline element with an @id gets an anchor, as DITA-OT's HTML keeps the id
@@ -238,7 +251,7 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
             const defining = ctx.conref.definingSnippet(node.attribs.id);
             if (defining && inlineSafeSnippet(defining)) {
                 pushText(`{% include "${ctx.conref.includePath(defining)}" %}`);
-                continue;
+                return;
             }
         }
         // Inline conrefs (<ph conref="…"/>) are the standard DITA reused-text
@@ -254,7 +267,7 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                 // Local children are the stale preview copy in DITA conref
                 // semantics — the include replaces the whole element
                 pushText(`{% include "${ctx.conref.includePath(snippet)}" %}`);
-                continue;
+                return;
             }
             ctx.note(node.attribs.conref ? "@conref" : "@conkeyref", `<${name}> pulls content from "${ref}" — ${conrefLedgerDetail(node.attribs, snippet, ctx.conref !== undefined)}`);
         }
@@ -275,7 +288,7 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                         noteOnce(ctx, `db-badge ${t}`, `"${t}" is not a tone (${DB_QUALIFIERS.tones.join(", ")}) — default badge`);
                 }
                 out.push({ type: "badge", text, ...(variant ? { variant } : {}) });
-                continue;
+                return;
             }
             // A content-less keyref falls through to the key's text ({{ key }}): the badge look is what is lost
             if (node.attribs?.keyref)
@@ -309,7 +322,7 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                         : [];
             // An unresolved key with no content renders nothing, as in DITA-OT's output
             if (content.length === 0)
-                continue;
+                return;
             const href = node.attribs?.href;
             if (href) {
                 // An external link keeps its href as written, even to a .dita file
@@ -319,14 +332,14 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
             else {
                 out.push(...content);
             }
-            continue;
+            return;
         }
         if (!ctx.publish && node.attribs?.keyref && name !== "xref" && name !== "link" && name !== "image") {
             const hasFallback = children.some((c) => isElement(c) || (isText(c) && c.data.trim().length > 0));
             if (!hasFallback) {
                 noteOnce(ctx, "@keyref", "content-less keyref emitted as {{ key }} minja variable — resolves only for TEXT keys (keys.yaml entries with text:); href-only keys need manual attention");
                 pushText(`{{ ${node.attribs.keyref} }}`);
-                continue;
+                return;
             }
             // Fallback content present: note the dropped indirection, then fall
             // through so the element converts normally (term stays italic, …)
@@ -334,12 +347,12 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
         }
         if (TRANSPARENT.has(name) && !isCodeLike(name, ctx)) {
             out.push(...convertInline(children, ctx, formatting));
-            continue;
+            return;
         }
         // Publishing: content DITA-OT's HTML does not show (foreign content such as MathML without
         // a plugin, and required-cleanup without args.draft)
         if (ctx.publish && (name === "foreign" || name === "unknown" || name === "required-cleanup"))
-            continue;
+            return;
         if ((name === "fn" || name === "synnote") && ctx.publish && ctx.footnotes) {
             // Publishing: a numbered footnote, listed at the end of the page as DITA-OT does. Only
             // footnotes without @callout are numbered; a callout is the label when it is a valid,
@@ -351,14 +364,14 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
             // Converted by parse.ts, which can convert block content (a list in a footnote)
             ctx.footnotes.push({ label, el: node, ...(callout ? { callout: true } : {}) });
             out.push({ type: "footnote-ref", label });
-            continue;
+            return;
         }
         if (name === "q" && ctx.publish) {
             // Publishing: a quotation in quotation marks, as a browser renders DITA-OT's <q>
             pushText("\u201C");
             out.push(...convertInline(children, ctx, formatting));
             pushText("\u201D");
-            continue;
+            return;
         }
         if (isCodeLike(name, ctx) && ctx.publish && children.some((c) => isElement(c) && ["xref", "link"].includes(c.name.toLowerCase()))) {
             // Publishing: a code phrase containing a link, as DITA-OT renders it: one code
@@ -374,7 +387,7 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
             out.push({ type: "html-inline", html: `<code>${collapseWhitespace(html).trim()}</code>` });
             if (raw.endsWith(" "))
                 pushText(" ");
-            continue;
+            return;
         }
         if (isCodeLike(name, ctx)) {
             if (name !== "codeph" && name !== "tt") {
@@ -394,7 +407,7 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
             });
             if (ctx.publish && raw.endsWith(" ") && raw.trim())
                 pushText(" ");
-            continue;
+            return;
         }
         if (name === "menucascade") {
             // "File > Save Project", as DITA-OT's HTML renders it: each step keeps
@@ -412,7 +425,7 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                 out.push(...converted);
                 any = true;
             }
-            continue;
+            return;
         }
         if (name === "shortcut") {
             // A keystroke (`<shortcut>Ctrl+S</shortcut>`) is a keycap. Inside a
@@ -424,21 +437,21 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                 out.push({ type: "kbd", keys });
             else
                 out.push(...convertInline(children, ctx, formatting));
-            continue;
+            return;
         }
         if (BOLD_LIKE.has(name)) {
             if (name !== "b" && name !== "strong") {
                 noteOnce(ctx, `<${name}>`, `rendered as bold — semantic identity not preserved`);
             }
             out.push(...convertInline(children, ctx, { ...formatting, bold: true }));
-            continue;
+            return;
         }
         if (ITALIC_LIKE.has(name)) {
             if (name !== "i" && name !== "em") {
                 noteOnce(ctx, `<${name}>`, `rendered as italic — semantic identity not preserved`);
             }
             out.push(...convertInline(children, ctx, { ...formatting, italic: true }));
-            continue;
+            return;
         }
         if (name === "tm" && ctx.publish) {
             // Publishing: the trademark symbol DITA-OT's HTML adds, on a trademark's first use in the topic
@@ -448,18 +461,18 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
             if (symbol && !ctx.trademarks?.has(trademark))
                 pushText(symbol);
             ctx.trademarks?.add(trademark);
-            continue;
+            return;
         }
         // Highlighting Markdown has no syntax for: inline HTML around the converted content
         if (name === "u" || name === "sub" || name === "sup" || name === "overline") {
             const open = name === "overline" ? '<span style="text-decoration: overline">' : `<${name}>`;
             const close = name === "overline" ? "</span>" : `</${name}>`;
             out.push({ type: "html-inline", html: open }, ...convertInline(children, ctx, formatting), { type: "html-inline", html: close });
-            continue;
+            return;
         }
         if (name === "line-through") {
             out.push(...convertInline(children, ctx, { ...formatting, strikethrough: true }));
-            continue;
+            return;
         }
         if (name === "xref" || name === "link") {
             const href = node.attribs?.href;
@@ -476,7 +489,7 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                     out.push(...linkChildren);
                 else if (text)
                     pushText(text);
-                continue;
+                return;
             }
             if (keyref && !ctx.publish) {
                 // Key-based links keep their indirection via the key: scheme
@@ -486,7 +499,7 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                     href: `key:${keyref}`,
                     children: linkChildren.length > 0 ? linkChildren : [{ type: "text", text: keyref }],
                 });
-                continue;
+                return;
             }
             if (href) {
                 // An external link keeps its href as written, even to a .dita file
@@ -498,11 +511,11 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                         ? linkChildren
                         : [{ type: "text", text: fallbackText || (ctx.publish ? ditaOtHrefText(href) : href) }],
                 });
-                continue;
+                return;
             }
             noteOnce(ctx, `<${name}>`, "xref without href/keyref — emitted as plain text");
             pushText(fallbackText);
-            continue;
+            return;
         }
         if (name === "image") {
             const imgHref = node.attribs?.href;
@@ -513,13 +526,13 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                 else {
                     noteOnce(ctx, "<image>", "image without href dropped");
                 }
-                continue;
+                return;
             }
             if (ctx.publish) {
                 // Publishing: size, alignment and the <alt> element, as DITA-OT's HTML renders them
                 const { alt, attrs } = publishImage(node, ctx.publish);
                 out.push({ type: "image", src: imgHref, ...(alt ? { alt } : {}), ...(attrs ? { attrs } : {}) });
-                continue;
+                return;
             }
             // The <alt> element (DITA 1.1+) wins over the deprecated @alt, as in publishing.
             const altEl = (children).find((c) => isElement(c) && c.name.toLowerCase() === "alt");
@@ -529,17 +542,16 @@ export const convertInline = (nodes, ctx, formatting = {}) => {
                 src: imgHref,
                 ...(alt ? { alt } : {}),
             });
-            continue;
+            return;
         }
         if (name === "indexterm" || name === "draft-comment" || name === "data") {
             noteOnce(ctx, `<${name}>`, "metadata element dropped from output");
-            continue;
+            return;
         }
         // Unknown inline element: keep the text, note the loss
         noteOnce(ctx, `<${name}>`, "unrecognized inline element — text kept, markup dropped");
         out.push(...convertInline(children, ctx, formatting));
     }
-    return mergeAdjacentText(out);
 };
 /** Merge neighbouring text spans with identical formatting (recursive calls
  * push whole runs, so pushText's local merging alone is not enough). */

package/dist/lines.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Offsets → 1-based line numbers, counting lines as checkWellFormed does:
+ * `\n`, `\r\n` and a lone `\r` each end one.
+ */
+export declare function lineLocator(text: string): (offset: number) => number;

package/dist/lines.js

@@ -0,0 +1,24 @@
+/**
+ * Offsets → 1-based line numbers, counting lines as checkWellFormed does:
+ * `\n`, `\r\n` and a lone `\r` each end one.
+ */
+export function lineLocator(text) {
+    const starts = [0];
+    for (let i = 0; i < text.length; i++) {
+        const c = text.charCodeAt(i);
+        if (c === 10 || (c === 13 && text.charCodeAt(i + 1) !== 10))
+            starts.push(i + 1);
+    }
+    return (offset) => {
+        let lo = 0;
+        let hi = starts.length - 1;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+            if (starts[mid] <= offset)
+                lo = mid;
+            else
+                hi = mid - 1;
+        }
+        return lo + 1;
+    };
+}

package/dist/parse.js

@@ -1,5 +1,6 @@
 import { checkWellFormed } from "./well-formed.js";
 import { applyClassDefaults } from "./class-defaults-apply.js";
+import { lineLocator } from "./lines.js";
 import { parseDocument } from "htmlparser2";
 import { convertChildren, convertItemContent } from "./blocks.js";
 import { textOf, convertInline, trimInline, collapseWhitespace } from "./inline.js";
@@ -89,6 +90,8 @@ const convertSecondaryTopic = (el, ctx, level, bindConrefSite) => {
     for (const child of el.children) {
         if (!isElement(child))
             continue;
+        if (ctx.position)
+            ctx.position.el = child;
         const name = child.name.toLowerCase();
         if (name === "title" || name === "glossterm") {
             out.push({
@@ -98,7 +101,9 @@ const convertSecondaryTopic = (el, ctx, level, bindConrefSite) => {
                     ...(el.attribs?.id ? { id: el.attribs.id } : {}),
                 },
                 inline: trimInline(convertInline(child.children, inner)),
-                ...(el.attribs?.id ? { meta: { dita: { id: el.attribs.id } } } : {}),
+                ...(el.attribs?.id || ctx.lineOf?.(child) !== undefined
+                    ? { meta: { ...(el.attribs?.id ? { dita: { id: el.attribs.id } } : {}), ...(ctx.lineOf?.(child) !== undefined ? { line: ctx.lineOf(child) } : {}) } }
+                    : {}),
             });
             headingEmitted = true;
             continue;
@@ -220,17 +225,23 @@ const extractProlog = (el, meta, ctx) => {
 export function ditaTopicToTree(xml, options = {}) {
     const topicPath = options.topicPath ?? "";
     const notes = [];
-    const note = (construct, detail) => notes.push({ topicPath, construct, detail });
+    // Every note carries the line of the element converting when it was raised
+    // (a shared holder: contexts are copied, the holder is not)
+    const lineOf = lineLocator(xml);
+    const position = {};
+    const lineAt = (el) => el?.startIndex != null ? lineOf(el.startIndex) : undefined;
+    const note = (construct, detail, line = lineAt(position.el)) => notes.push({ topicPath, construct, detail, ...(line ? { line } : {}) });
     // The parser repairs malformed XML silently: say so, with a line
     const malformed = checkWellFormed(xml);
     if (malformed)
-        note("<xml>", `not well-formed XML, line ${malformed.line}: ${malformed.message} — the converted content may be incomplete`);
-    const doc = parseDocument(xml, { xmlMode: true });
+        note("<xml>", `not well-formed XML, line ${malformed.line}: ${malformed.message} — the converted content may be incomplete`, malformed.line);
+    const doc = parseDocument(xml, { xmlMode: true, withStartIndices: true });
     // Raw source: fill in the @class the DTDs default, so specializations convert as their base
     if (options.classDefaults) {
-        const undeclared = applyClassDefaults(doc.children);
+        const firstOf = new Map();
+        const undeclared = applyClassDefaults(doc.children, firstOf);
         if (undeclared.length) {
-            note("@class", `no DITA 1.3 class default for ${undeclared.map((n) => `<${n}>`).join(", ")} — converted by name only`);
+            note("@class", `no DITA 1.3 class default for ${undeclared.map((n) => `<${n}>`).join(", ")} — converted by name only`, lineAt(firstOf.get(undeclared[0])));
         }
     }
     const byClass = !!options.publish || !!options.classDefaults;
@@ -283,7 +294,9 @@ export function ditaTopicToTree(xml, options = {}) {
         note,
         seenConstructs: new Set(),
         headingLevel: 2,
+        position,
         ...(options.classDefaults ? { classes: true } : {}),
+        ...(options.sourceLines ? { lineOf: lineAt } : {}),
         ...(bindConrefSite ? { conref: bindConrefSite(root.attribs?.id) } : {}),
         ...(options.publish
             ? { publish: options.publish, trademarks: new Set(), footnotes: [], topicId: root.attribs?.id, anchorIds: renamedElementIds(doc.children) }
@@ -297,6 +310,7 @@ export function ditaTopicToTree(xml, options = {}) {
     for (const child of root.children) {
         if (!isElement(child))
             continue;
+        position.el = child;
         const name = child.name.toLowerCase();
         if (name === "title" || name === "glossterm") {
             // The page title is plain text: a badge in it keeps only its words
@@ -351,9 +365,12 @@ export function ditaTopicToTree(xml, options = {}) {
     }
     // Sibling topics under a composite wrapper convert the same way
     for (const sibling of roots.slice(1)) {
+        position.el = sibling;
         // Publishing: DITA-OT titles sibling topics in one file like the first (h1)
         tree.push(...convertSecondaryTopic(sibling, ctx, options.publish ? 1 : 2, bindConrefSite));
     }
+    // Notes about the whole file (duplicate ids) are about no one element
+    position.el = undefined;
     // DITA element ids are unique per TOPIC, not per file — after inlining
     // multiple topics, colliding ids mean fragment links can mis-target.
     // Known loss, never silent loss: report every duplicate anchor.

package/dist/types.d.ts

@@ -10,6 +10,12 @@ export interface DitaConversionNote {
     /** Construct that triggered the note (element/attribute name). */
     construct: string;
     detail: string;
+    /**
+     * The 1-based source line the note is about: the element that raised it, or
+     * failing that the block being converted (absent when there is none, as for
+     * "no topic root").
+     */
+    line?: number;
 }
 /** Topic-level metadata extracted alongside the block tree. */
 export interface DitaTopicMeta {
@@ -162,6 +168,12 @@ export interface DitaParseOptions {
      * noted once. Off by default (it changes the output for such elements).
      */
     classDefaults?: boolean;
+    /**
+     * Put each block node's 1-based source line on `meta.line` (the line of the
+     * element it came from), so a host can map the rendered page back to the
+     * source; render-html writes it as `data-line` when asked. Off by default.
+     */
+    sourceLines?: boolean;
 }
 /** DITA topic root elements this importer understands. */
 export declare const DITA_TOPIC_TYPES: readonly ["concept", "task", "reference", "topic", "glossentry"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogsbay/format-dita",
-  "version": "0.2.0-beta.124",
+  "version": "0.2.0-beta.125",
   "description": "DITA topic XML → TreeNode importer with conversion-note ledger; composes with format-dogsbay-md for .dita → .md migration. Browser-safe: no Node built-ins",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
   "dependencies": {
     "domhandler": "^5.0.3",
     "htmlparser2": "^10.1.0",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.124",
-    "@dogsbay/types": "0.2.0-beta.124"
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.125",
+    "@dogsbay/types": "0.2.0-beta.125"
   },
   "license": "MIT",
   "repository": {