Module content 

The content tree: semantic input.

The markdown frontend produces this; the element vocabulary is bounded by what a book needs — book/section, heading, paragraph, blockquote, thematic break, image, list, table, emphasis/strong/code, link, hard break.

This module is the input contract: everything downstream (style, box construction, layout) consumes these types, and nothing widens the vocabulary without a fixture and a test. It is a Rust type, and that is the seam a frontend of its own builds against: a docx or CMS reader constructs a Book directly, with the compiler checking the shape.

Reading a tree back

The tree serializes, internally tagged ({"type": "paragraph", …}) so the shape maps one-to-one onto mdast. It is mostly an output: it is how to see what a frontend made of a manuscript. It reads back too, which is the door a host with a structured source of its own comes in through, so what the engine writes is what a host may hand it again.

Naming a node

Every section, block and inline carries Attributes: any number of classes and at most one id, which is what a sheet reaches one element by. They are empty unless something set them, and a frontend is not the only thing that can: a host with a structured source of its own sets them on the tree it builds.

Node identity

NodeId is engine-assigned, never frontend-supplied: input can’t collide ids or forge diagnostic origins. Every node’s id field is #[serde(skip)], so a serialized tree has none. The ids in a tree built by hand are NodeId::UNASSIGNED until Book::assign_node_ids assigns dense ids from 1 in document order (pre-order: a node before its children, sections in reading order).

Source positions

Every node has an optional 1-based line/column into the markdown source the frontend read it from; the section’s source names the file. origin formats the pair for diagnostics (chapter-01.md:12:3). A missing position never fails a run.

Beside it every node has an optional span: the bytes of that source the node was read from, markup included. Book::node_at turns a byte of a source into the node written there and Book::source_of turns a node back into the bytes it was read from, which is how a host holding the manuscript maps a cursor onto a page and a run under the pointer back onto the file it was written in. A tree built rather than parsed has neither, and both questions answer with nothing.

Structs

Anchors

What the links in one book can reach: each source, the headings in it, and every id a source writes.

Attributes

What a sheet names one node by: any number of classes, at most one id.

Book

The root of the content tree: one book.

Cell

One cell of a table row.

InvalidHeadingLevel

A heading level outside 1–6, with the offending value.

ListItem

One item of a list.

Metadata

Book metadata: everything about the work that isn’t content.

Names

The classes and the ids some part of a book carries, each once and in sorted order, as a sheet names them: without the . or the #.

NodeId

Identity of one node in the content tree, for diagnostics and incremental relayout.

Row

One row of a table.

Section

A chapter or file: the unit of markdown input and of source attribution for diagnostics.

SourcePos

A 1-based position in the frontend’s source document.

SourceRange

A stretch of one node’s text: the node it was written in, and the bytes of that node’s own text the stretch covers.

SourceSpan

The bytes of one source a node was read from: its extent in the file, markup included.

Enums

Alignment

The alignment a table’s delimiter row writes on a column.

Block

A block-level element: the unit of fragmentation input.

HeadingLevel

A heading level: 1 to 6, the range markdown defines.

Inline

An inline element: participates in line layout.

LinkTarget

What one link reaches.

PseudoElement

The pseudo-elements the engine styles.

Functions

block_attributes

What a sheet names one block by.

block_id

One block’s identity.

block_position

Where in its source one block was read from.

block_span

The bytes of its source one block was read from.

cell_blocks

The blocks of every cell of a table, row by row, the header rows first.

inline_attributes

The same, for one inline.

inline_id

One inline’s identity.

inline_position

The same, for one inline.

inline_span

The bytes of its source one inline was read from.

item_blocks

The blocks of every item of a list, in reading order.

notes_in_blocks

Every note written among these blocks, in reading order. A note written inside another note comes after it.

notes_in_inlines

The notes written directly among these inlines, in reading order. A note written inside another note is that note’s own.

origin

Formats a file name plus a position for diagnostics: chapter-01.md:12:3. Missing parts degrade: bare file name, bare position, empty string.

rows

Every row of a table, the header rows first.

text

The text of an inline tree, markup discarded: every inline run together and a hard break as a newline, as content() reads an element and as a frontend reads alt text.