Skip to content
§5.1

Block Annotation

What counts as a block, and how many should a page have?

✅ NormativeSettled. The requirement holds as written.📄 Page ruleCan be applied from the page alone.Read §5.1 in the RFC ↗

The requirement

Every meaningful visible region of a page MUST be one element with one class, one position in the page's reading order and — when boxes are requested — one box. Printed content covered by no element is dropped content, and makes the output non-conforming.

When it applies

An element at region level is one coherent visual region — a paragraph, a heading, a list item, a picture, a table, a caption, a form area. This note fixes what gets an element and how its box is drawn; the class is chosen by Block Classes (§5.3) and the order by Reading Order (§5.9).

Reading the examples. Each one pairs a source page with the output the rule expects. ✅ Sample: the rule applies. ❌ Counter-sample: it looks like it applies and does not, or a rendering got it wrong. A non-conforming output, in red, is shown only for contrast. … marks content left out of an excerpt.

The point, in a small example

Similar rectangular regions can be tables, forms or pictures. Choose the class from the content and role before choosing the output syntax; these samples omit optional boxes. These pages are made up to isolate the rule.

01

✅ SampleConstructedThe rule applies

A pictured table stays a table

The image contains a two-column table. Preserve both rows and the printed headers; a prose summary loses the cell relationships.

Source page
Block Annotation — A pictured table stays a table. Source page.
Non-conforming output

What the rule rules out.

Markdown
A table listing stationery supplies.
Expected output
Markdown
<table>
<tr><th>Item</th><th>Count</th></tr>
<tr><td>Pencils</td><td>12</td></tr>
<tr><td>Pens</td><td>7</td></tr>
</table>
Block Annotation · Source page

A pictured table stays a table

Block Annotation — A pictured table stays a table. Source page.
02

✅ SampleConstructedThe rule applies

Keep values verbatim and blank fields explicit

These are labeled fill-in fields, not a table. Keep leading zeros and the ambiguous date exactly as printed; do not infer a currency or expand the date. The third answer line is empty.

Source page
Block Annotation — Keep values verbatim and blank fields explicit. Source page.
Non-conforming output

What the rule rules out.

Markdown
- **Amount:** $12.50
- **Date:** March 4, 2026
Expected output
Markdown
- \[1\] **Amount:** 0012.50
- \[2\] **Date:** 03/04/26
- \[3\] **Reference:** [blank]
Block Annotation · Source page

Keep values verbatim and blank fields explicit

Block Annotation — Keep values verbatim and blank fields explicit. Source page.
03

✅ SampleConstructedThe rule applies

A flow image becomes a diagram

Keep all three printed labels and both directed connections. This simple flow fits Mermaid; other faithful supported diagram languages are valid.

Source page
Block Annotation — A flow image becomes a diagram. Source page.
Non-conforming output

What the rule rules out.

Markdown
[A three-step process diagram]
Expected output
Markdown
```diagram/mermaid
flowchart LR
  A[Receive] --> B[Review]
  B --> C[Archive]
```
Block Annotation · Source page

A flow image becomes a diagram

Block Annotation — A flow image becomes a diagram. Source page.

What an element is not

Printed lines, table cells, rows, columns and words MUST NOT be region-level elements. A table is one Table element around the whole table; a picture or chart is one Picture element around the unified graphic. Finer boxes exist only at the granularity that was requested — see Boxes and Granularity (§3.3). Going finer at region level is not more thorough; it is the wrong layer.

Completeness

  • Every region carrying printed content MUST be covered by an element, except the narrow exclusions of Ignoring and Rejecting (§5.6).
  • Duplicate elements for one region, and elements for regions that print nothing, MUST NOT appear.

The box

  • A box MUST be the smallest rectangle that contains the complete element.
  • A box MUST include all of the element's visible ink: borders, diacritics, superscripts, meaningful shadows. Slight extra whitespace is better than clipped content: where the two conflict, the box SHOULD err towards whitespace.
  • A box MUST NOT extend beyond the page, and boxes SHOULD NOT substantially overlap one another.

Splitting

  • Each paragraph MUST be its own Text element. Separate paragraphs, columns, list items, captions or unrelated labels MUST NOT be merged into one element.
  • An element MUST be split at a page boundary and at a column boundary.
  • A displayed Formula, Picture or Table that interrupts prose MUST split the surrounding prose into separate Text elements above and below it.
  • Where prose wraps around a picture, the prose MUST be split into the fewest elements whose non-overlapping boxes each keep complete lines.

A paragraph continued in the next column

The layout boxes stay split: one box per column piece, as above. A Markdown-attribution ground truth (the markdown_attribution rule) records the paragraph as the one element it is in the Markdown, with a box budget:

  • The reference's regions MUST be the pieces, one per column (or page), with exception: "multi_column" (or "cross_page").
  • expected_bbox_count MUST equal the number of pieces. It is an integer of at least 1, and 1 is the default: an engine that claims more boxes than the count scores 0 for that element.
  • Each piece SHOULD also be a spans entry with its own text and box, so an output that keeps the pieces as two paragraphs is still matched.
  • Set it only when the text really runs on (no paragraph break at the column foot). Separate paragraphs, list items, table rows and formulas keep one box each and the default count.

More

Rule id layout-block-annotation · rule layout blocks