Stable section indices matter more than translated heading text

The mapper uses encounter order, not a title slug, as a chapter identity. That decision avoids pretending that two translated words must match and makes repeated headings unambiguous.

The index contract

Recognized ATX headings receive indices 1, 2, 3 and so on, including nested headings. An empty heading such as # still receives an index and displays as “(untitled)” in the Markdown report. Two “Notes” headings are separate sections. Nonblank content before the first heading is section 0; a blank document has no sections. The default comparison pairs section 0 only with another section 0 and pairs the remaining headings in encounter order.

#
# Notes
# Notes

Indices: 1, 2, 3
Explicit map: [[1, 1], [3, 2]]

In explicit mode, only listed pairs are matched. Unlisted sections remain unpaired, including preambles. Repeated indices or unknown indices are errors, not guesses. If you insert a new heading, regenerate the chapter inventory and review the mapping.

What is counted

The supported subset is ATX headings with up to three leading spaces, backtick or tilde fences, standalone $$ blocks, and simple inline image/link destinations. Fenced code and equation content cannot create headings. Code languages, image targets and link targets are compared as multisets: repeated objects matter, but their order does not. Every recognized heading begins a new section; objects under a subheading belong to that subheading rather than being counted again in its parent.

What is deliberately not parsed

This is not a full CommonMark parser. Setext headings, reference-style links, nested-parenthesis destinations, raw HTML, inline math, tables and deeply nested Markdown constructs are outside the contract. Unclosed fences or equation blocks are not syntax-linted. Normalize those constructs or inspect them manually before relying on the report.

A changed URL can be a legitimate localized resource; equal block counts can conceal missing meaning. Use the output to choose what to read, never to score translation quality or certify completeness.

When the source is a PDF, the related KolmoPDF conversion workflow can supply upstream Markdown through a separate cloud service that uploads the document. Conversion and this limited structural comparison answer different questions; neither makes an equal block count a translation-quality verdict.