Skip to main content

docling_core/
document.rs

1//! The unified document representation.
2
3use crate::markdown::{to_markdown, to_markdown_images};
4use crate::ImageMode;
5
6/// The unified, format-agnostic document produced by every backend.
7///
8/// This is the heart of docling: backends parse their source format into a
9/// `DoclingDocument`, and serializers turn it back into Markdown, HTML, JSON,
10/// etc. Phase 0 uses a flat sequence of [`Node`]s; the production schema will
11/// match docling-core's body-tree-with-references layout.
12#[derive(Debug, Clone, PartialEq)]
13pub struct DoclingDocument {
14    /// Logical document name (usually the input file stem).
15    pub name: String,
16    /// Top-level content, in reading order.
17    pub nodes: Vec<Node>,
18    /// Default Markdown export mode for [`Self::export_to_markdown`]. `false`
19    /// (the default) reproduces docling's legacy output byte-for-byte; `true`
20    /// emits cleaner, more conformant Markdown. Set by `DocumentConverter`.
21    pub strict_markdown: bool,
22    /// Emit tables in the compact `| a | b |` / `| - | - |` form rather than
23    /// docling-core's width-padded GitHub serializer. The PDF backend sets this
24    /// (its committed groundtruth corpus predates the padded serializer); DOCX/HTML
25    /// leave it `false` to match current published docling.
26    pub compact_tables: bool,
27    /// Render a picture's author-written alt text (#676: the `descr` /
28    /// `title` of an OOXML picture's non-visual properties, carried as a
29    /// [`PictureDescription`] whose provenance is
30    /// [`PictureDescription::ALT_TEXT`]) in the Markdown and HTML exports
31    /// (the `![alt](…)` of an image line or the line above a placeholder;
32    /// the `<img alt>` and the description text). `false` (the default)
33    /// keeps it to the JSON (and DCLX) output, so the default Markdown and
34    /// HTML stay byte-for-byte docling's; strict Markdown renders it
35    /// regardless. Set by `DocumentConverter::picture_alt_text`.
36    pub picture_alt_text: bool,
37    /// What the file says about itself (#679): an EPUB's Dublin Core, an
38    /// Office package's properties, a photo's EXIF, an audio file's tags —
39    /// see [`crate::metadata`]. Read by the converter when
40    /// [`metadata_output`](Self::metadata_output) asks for it (a document
41    /// read from docling JSON keeps the `metadata` the JSON carried).
42    pub metadata: crate::metadata::DocumentMetadata,
43    /// Where [`metadata`](Self::metadata) goes in the exports: nowhere (the
44    /// default — every export stays docling's), the JSON's `metadata`
45    /// object, or that and YAML front matter at the top of the Markdown.
46    /// Set by `DocumentConverter::metadata_output`.
47    pub metadata_output: crate::metadata::MetadataOutput,
48    /// Text the Markdown export inserts between two pages — docling-core's
49    /// `MarkdownParams.page_break_placeholder` (e.g. `"<!-- page break -->"`).
50    /// `None` (the default) omits page breaks from Markdown, as docling does.
51    /// Set by `DocumentConverter::page_break_placeholder`. See
52    /// [`crate::markdown`] for where a break lands (only between two rendered
53    /// blocks that sit on different pages, never leading or trailing).
54    pub page_break_placeholder: Option<String>,
55    /// Hyperlinks recovered from the source, as `(anchor_text, href)` pairs in
56    /// document order. docling's standard pipeline drops PDF link annotations, so
57    /// these are rendered as Markdown `[anchor](href)` **only in strict mode**
58    /// (legacy/docling output is left byte-for-byte unchanged). The PDF backend
59    /// populates this from pdfium link annotations; other backends leave it empty.
60    pub links: Vec<(String, String)>,
61    /// Conversion-confidence report (#183), populated by the PDF/image ML
62    /// pipeline; `None` for declarative conversions. Deliberately **not**
63    /// part of any document export (docling keeps it on the conversion
64    /// result, outside the document schema) — docling-serve surfaces it in
65    /// the HTTP response instead.
66    pub confidence: Option<crate::confidence::ConfidenceReport>,
67    /// docling's item tree, when the backend built one (the HTML backend
68    /// does): the JSON export serializes it instead of deriving a tree from
69    /// `nodes`, so the JSON carries upstream's exact parent/child structure,
70    /// item numbering, inline groups, formatting and content layers. Every
71    /// other serializer reads `nodes`. See [`crate::tree`].
72    pub tree: Option<crate::tree::ItemTree>,
73    /// Rendered page images by 1-based page number — docling's
74    /// `PageItem.image`, filled by the PDF/image pipeline only when page
75    /// images are requested (docling's `generate_page_images`, #520). The
76    /// JSON export writes each as the page's `image`, so docling-core's
77    /// `TableItem.get_image` / `FormulaItem.get_image` can crop from it.
78    /// Empty otherwise; no other export reads it.
79    pub page_images: std::collections::BTreeMap<usize, PictureImage>,
80}
81
82/// A single piece of document content.
83#[derive(Debug, Clone, PartialEq)]
84pub enum Node {
85    /// A heading. `level` is 1-6.
86    Heading { level: u8, text: String },
87    /// A run of body text.
88    Paragraph { text: String },
89    /// A form checkbox (docling's `checkbox_selected`/`checkbox_unselected`): its
90    /// clean label `text` with the checked state. DocLang emits a `<checkbox>`
91    /// element head; Markdown/JSON render the task-list form (`- [x] `/`- [ ] `).
92    CheckboxItem { checked: bool, text: String },
93    /// A single list item at the given nesting `level` (0 = top). For ordered
94    /// items, `number` is the display number (honoring the list's `start`); it
95    /// is unused for unordered items. `first_in_list` marks the first item of a
96    /// list so the serializer can blank-line-separate adjacent sibling lists.
97    ///
98    /// `marker` is the DocLang enumeration marker (`"1."`, `"1.1."`, …) when the
99    /// backend provides one — HTML and DOCX set it for enumerated items, so
100    /// DocLang emits `<ldiv><marker>…</marker></ldiv>`; Markdown and the other
101    /// declarative backends leave it `None`, giving a bare `<ldiv/>` (matching
102    /// docling, whose Markdown backend passes no marker).
103    ListItem {
104        ordered: bool,
105        number: u64,
106        first_in_list: bool,
107        text: String,
108        level: u8,
109        marker: Option<String>,
110        /// Optional layout provenance (`x0,y0,x1,y1`, normalized to 0–511): the
111        /// four DocLang `<location>` values emitted inside the `<list>` right
112        /// after the item's `<ldiv>`. Set only by backends with real geometry
113        /// (e.g. PPTX shapes); `None` for the declarative backends. Kept on the
114        /// item itself (rather than a [`Node::Located`] wrapper) so consecutive
115        /// items still group into one `<list>`.
116        location: Option<[u16; 4]>,
117        /// DocLang-only override for items whose DocLang form diverges from their
118        /// flat Markdown `text`. Markdown/JSON always render the fields above; the
119        /// DocLang serializer, when this is `Some`, takes the list kind, marker,
120        /// and content from here instead. Used for docx multilevel numbering
121        /// (Markdown shows `- 1.1. x`, DocLang an ordered `<marker>1.1.</marker>`
122        /// with clean text) and inline equations/formatting in list items.
123        dclx: Option<ListItemDclx>,
124        /// The item's hyperlink target, when its content is a link — docling's
125        /// HTML backend emits it as an `<href uri=…/>` in the item head, and the
126        /// anchor's Markdown link markup is stripped from the rendered content.
127        /// `None` for a plain item; ignored by Markdown/JSON.
128        href: Option<String>,
129        /// Non-body content layer (docling's HTML site chrome before the first
130        /// heading → `furniture`). DocLang emits a `<layer value=…/>` in the item
131        /// head; Markdown/JSON drop a non-body item entirely.
132        layer: Option<ContentLayer>,
133    },
134    /// A fenced code block.
135    Code {
136        language: Option<String>,
137        text: String,
138        /// The original (pre-enrichment) text when the CodeFormula model
139        /// rewrote `text`: docling keeps the raw extraction in the JSON `orig`
140        /// field while `text` carries the model output. `None` → `orig == text`.
141        orig: Option<String>,
142        /// A line-preserving rendering, when the backend can reconstruct one
143        /// but docling's own output for the format cannot. The PDF pipeline
144        /// sets it (docling-parse joins code lines with single spaces, so
145        /// `text` carries that flat docling-parity form): **strict** Markdown
146        /// prefers `pretty`, every byte-conformance surface (legacy Markdown,
147        /// JSON, DocLang, chunks) serializes `text`.
148        pretty: Option<String>,
149    },
150    /// A table. The first row is treated as the header.
151    Table(Table),
152    /// A picture/figure, with an optional caption and (when a backend extracts
153    /// it) the embedded image itself.
154    Picture {
155        caption: Option<String>,
156        /// Hyperlink annotation on the caption (docling's caption text item
157        /// `hyperlink`): the HTML backend sets it when an `<a href>` wraps the
158        /// image whose `alt` became the caption. DocLang emits the block-form
159        /// `<caption>` with an `<href uri=…/>` head; JSON puts `hyperlink` on
160        /// the caption item; Markdown and LaTeX print the plain caption text,
161        /// as docling does.
162        caption_href: Option<String>,
163        image: Option<PictureImage>,
164        /// DocumentPictureClassifier predictions (all classes, descending
165        /// confidence), when the picture-classification enrichment ran.
166        /// Serialized as docling's `classification` annotation + `meta` field
167        /// on the JSON picture item; Markdown/DocLang output is unaffected.
168        classification: Option<Vec<PictureClass>>,
169        /// Text read off the embedded image by the picture-OCR enrichment
170        /// (#645) — docling's `PictureDescriptionData` annotation /
171        /// `meta.description`, which is where upstream's picture-description
172        /// models (VLM captioning) put their text too. JSON and DCLX carry it
173        /// structurally; Markdown prints it between the caption and the
174        /// image placeholder, where docling's picture serializer renders
175        /// annotations. `None` when the enrichment did not run or read no
176        /// text, so every default export stays unchanged.
177        description: Option<PictureDescription>,
178        /// Where the caption item hangs in the JSON tree (#390); see
179        /// [`CaptionParent`]. Markdown, DocLang and LaTeX ignore it.
180        caption_parent: CaptionParent,
181        /// The caption's own box on the picture's page (0–511 grid, like
182        /// [`Node::Located`]) — the PDF pipeline's caption layout region. The
183        /// JSON export writes it as the caption item's `prov` (#609), as
184        /// docling's `ReadingOrderModel._add_caption_or_footnote` does; `None`
185        /// (every declarative backend) leaves the caption without one.
186        caption_location: Option<[u16; 4]>,
187    },
188    /// A display-math formula item decoded by the CodeFormula enrichment:
189    /// `latex` is the model's LaTeX (no `$$` wrapping), `orig` the raw glyph
190    /// text extracted from the PDF. Markdown renders `$$latex$$`; JSON emits a
191    /// `formula` text item (docling's un-enriched pipeline instead emits a
192    /// placeholder paragraph — see the PDF assembler).
193    Formula {
194        latex: String,
195        orig: String,
196        location: Option<[u16; 4]>,
197    },
198    /// A standalone caption item (docling's `DocItemLabel.CAPTION` text that
199    /// no picture or table claims): the HTML backend emits a `<figure>`'s
200    /// `<figcaption>` this way when the figure produced no picture and its
201    /// first item is not a table (docling#4050). `href` is the caption's
202    /// hyperlink annotation (the first link inside the figcaption); Markdown
203    /// renders it as `[text](href)`, JSON puts `hyperlink` on the caption
204    /// item, DocLang emits the block-form `<caption>` with an `<href>` head.
205    Caption { text: String, href: Option<String> },
206    /// A body text item with a docling label of its own and an optional
207    /// hyperlink — the PDF pipeline's `footnote` regions, whose item docling
208    /// keeps as a `footnote` text with the link annotation covering it as its
209    /// `hyperlink` (`PageAssembleModel._match_hyperlink`). The JSON writes
210    /// exactly that (label, raw text, `hyperlink`); every other serializer
211    /// renders it as the paragraph [`Self::labeled_markdown`] spells —
212    /// docling's Markdown wraps a linked item's whole text, `[text](uri)`.
213    LabeledText {
214        label: String,
215        text: String,
216        href: Option<String>,
217    },
218    /// A chart (docling's `PictureItem` classified as a chart, carrying a
219    /// `PictureTabularChartData` annotation). Markdown and JSON render it exactly
220    /// like a [`Node::Picture`] placeholder (an `<!-- image -->` / `picture`
221    /// item); the DocLang serializer emits `<picture class="chart">` with a
222    /// `<label value="{kind}"/>` and the data `table` as a `<tabular>`.
223    Chart {
224        /// docling's classification label, e.g. `bar_chart`, `line_chart`.
225        kind: String,
226        /// The chart's data grid (row 0 is the header band).
227        table: Table,
228        /// The chart title (docling's caption item on the picture).
229        caption: Option<String>,
230        /// DocLang `<location>` provenance for the picture element.
231        location: Option<[u16; 4]>,
232    },
233    /// A logical grouping of child nodes (e.g. a list, a section, a spreadsheet
234    /// sheet). `name` is docling's group name when it differs from the label —
235    /// an xlsx sheet group is `label: "sheet"`, `name: Some("Sheet1")`. `layer`
236    /// puts the group *and* everything it contains on a non-body content layer
237    /// (a hidden sheet is `invisible`), which is how the serializers that only
238    /// render body content know to skip it; DocLang stamps each child with the
239    /// layer token, exactly as a [`Node::Furniture`] wrapper on each would.
240    /// DocLang has no group element, so a group is transparent there.
241    Group {
242        label: String,
243        name: Option<String>,
244        layer: Option<ContentLayer>,
245        children: Vec<Node>,
246    },
247    /// A form key-value region (docling's `field_region`): a set of form fields,
248    /// each pairing an optional marker, key, and value. Backends detect these
249    /// from form structure (e.g. HTML's `keyN` / `keyN_valueM` / `keyN_marker`
250    /// `id`-convention); the serializers render each item's parts as separate
251    /// labelled texts (`marker` / `field_key` / `field_value`).
252    FieldRegion { items: Vec<FieldItem> },
253    /// docling's `KeyValueItem`: a graph of key and value cells and the links
254    /// between them (docling-core's `GraphData`). The XBRL backend builds one
255    /// from an instance's numeric facts and the presentation and calculation
256    /// hierarchies of its taxonomy. Only the JSON export carries the graph:
257    /// docling's Markdown serializer has no rendering for the item and writes
258    /// its `<!-- missing-key-value-item -->` placeholder, which the Markdown
259    /// export reproduces; the other serializers omit it.
260    KeyValueGraph {
261        cells: Vec<GraphCell>,
262        links: Vec<GraphLink>,
263    },
264    /// Rich inline content — docling's `InlineGroup`: a run of styled text
265    /// segments that a backend captured with formatting (`<bold>`, `<italic>`,
266    /// `<underline>`, `<strikethrough>`, sub/superscript, inline `<code>`) the
267    /// flat Markdown text cannot represent. Markdown/JSON render this exactly
268    /// like `Paragraph { text: md_text }` (so their output is unchanged); the
269    /// DocLang serializer uses the structured `runs`. `unwrapped` is set when the
270    /// group's docling parent is a heading/text (no enclosing `<text>` wrapper).
271    InlineGroup {
272        unwrapped: bool,
273        runs: Vec<InlineRun>,
274        md_text: String,
275    },
276    /// A node in a non-body content layer — `furniture` (page headers/footers,
277    /// the HTML `<title>`, site navigation/chrome) or `notes` (docx comments).
278    /// Markdown and JSON omit these layers by default; DocLang renders the wrapped
279    /// node with a `<layer value="{layer}"/>` head.
280    Furniture {
281        layer: ContentLayer,
282        inner: Box<Node>,
283    },
284    /// One reviewer comment: docling's notes-layer `comment_section` group
285    /// holding a single text item. `name` is docling's own — `comment-{id}` for
286    /// a docx `w:comment`, `comment-{sheet}-{cell}` for a spreadsheet cell note.
287    /// JSON emits the group plus its notes-layer text; DocLang emits the flat
288    /// `<text><layer value="notes"/>…</text>` upstream writes (its DocLang
289    /// carries no group for comments); Markdown and LaTeX omit the notes layer.
290    ///
291    /// `refs_note_text` picks what a [`Node::Commented`] annotation points at,
292    /// mirroring an upstream asymmetry: docling-core's `add_comment` appends the
293    /// **note text**'s ref to each target (which is what the xlsx backend gets),
294    /// while the docx backend overwrites that with the **group**'s ref so a
295    /// comment's replies group together.
296    ///
297    /// `grouped` is whether docling wraps the note in a `comment_section`
298    /// group at all: the docx and spreadsheet backends do, while backends that
299    /// call docling-core's `add_comment` directly (Pages, #383) get a bare
300    /// notes-layer text item under the body — JSON then emits no group and
301    /// `name` is unused.
302    CommentSection {
303        name: String,
304        text: String,
305        refs_note_text: bool,
306        grouped: bool,
307    },
308    /// A body item annotated by reviewer comments: `comments` are indices into
309    /// the document's [`Node::CommentSection`] nodes, in document order. JSON
310    /// emits docling's `comments: [{"$ref": …}]` on the item, each ref pointing
311    /// where the section says (see [`Node::CommentSection::refs_note_text`]);
312    /// every other serializer renders `inner` unchanged.
313    Commented {
314        comments: Vec<usize>,
315        inner: Box<Node>,
316    },
317    /// A text node taken from a time-based track — an ASR segment (#614):
318    /// A link destination (#852: a `.doc` bookmark; the DOCX item tree
319    /// keeps its own, #849): the identifier the document's internal links
320    /// (`#id`) point at. Rendered by nothing but the JSON builder, which
321    /// hands it to the next text item for the Pandoc AST (`_anchors`).
322    Anchor { id: String },
323    /// docling's `TrackSource`. The JSON writes docling's ASR text item — `cue`
324    /// (the segment's words) as its text, `track` as its `source: [{"kind":
325    /// "track", …}]` — which the WebVTT export makes a cue of; every other
326    /// serializer renders `inner` (the `[time: start-end] words` paragraph)
327    /// unchanged.
328    Track {
329        track: crate::tree::TreeTrack,
330        cue: String,
331        inner: Box<Node>,
332    },
333    /// A node carrying layout provenance — the four DocLang `<location>` values
334    /// (`x0,y0,x1,y1`, normalized to 0–511) docling attaches to elements from
335    /// backends with real geometry (e.g. the slide shapes in PPTX). Markdown and
336    /// JSON render the wrapped node unchanged; DocLang emits the `<location>`
337    /// tokens as the element's first children.
338    Located {
339        location: [u16; 4],
340        inner: Box<Node>,
341    },
342    /// Exact page provenance for a backend whose geometry already *is* the
343    /// page's coordinate system — an XLSX item's cell-index box on its sheet,
344    /// which docling writes verbatim (`bbox` in a top-left origin, the
345    /// `charspan` the backend chose) and sizes the page from. The 0–511 grid
346    /// of a [`Node::Located`] cannot round-trip such integers exactly, so the
347    /// JSON export reads this wrapper; every other serializer renders `inner`
348    /// unchanged (DocLang keeps taking its `<location>` tokens from the grid).
349    Prov {
350        page_no: usize,
351        /// `[l, t, r, b]`, page units, top-left origin.
352        bbox: [f32; 4],
353        /// docling's `charspan` for the item (`[0, 0]` for an XLSX table).
354        charspan: [usize; 2],
355        /// The bbox's origin: docling's `BOTTOMLEFT` (a PDF page's
356        /// provenance, as a docling-JSON input carries it — #899) or
357        /// `TOPLEFT` (an XLSX sheet's cell box).
358        bottom_left: bool,
359        /// The item's creation rank among its siblings, when that differs
360        /// from the node order: docling numbers `#/tables/N` / `#/texts/N` /
361        /// `#/pictures/N` in the order it *creates* items (a sheet's tables,
362        /// then its images, then its charts) and only afterwards sorts the
363        /// container's children by position. The JSON export adds siblings in
364        /// this order and lays their refs out in node order; `None` when the
365        /// two orders coincide.
366        seq: Option<usize>,
367        inner: Box<Node>,
368    },
369    /// A PDF page header or footer (docling's `page_header`/`page_footer`
370    /// furniture): DocLang emits `<page_header>`/`<page_footer>` with a
371    /// `<layer value="furniture"/>` head, the four `<location>` tokens, then the
372    /// text. The JSON writes it as a body-parented `page_header`/`page_footer`
373    /// text item on the furniture layer; Markdown omits it.
374    PageFurniture {
375        footer: bool,
376        location: [u16; 4],
377        text: String,
378    },
379    /// A furniture-layer text item with an explicit docling label — a page
380    /// header / footer paragraph (`page_header` / `page_footer`) or a note
381    /// body (`footnote`) from a backend that builds no item tree (#535: the
382    /// Word 97 `.doc` stories). The JSON writes a body-parented item of that
383    /// label on the furniture layer; DocLang `<{label}>` with a `<layer
384    /// value="furniture"/>` head (docling-core's own shape); Markdown, LaTeX
385    /// and the chunker leave it out like any furniture.
386    FurnitureText { label: String, text: String },
387    /// The text a PDF picture contains, kept the way docling keeps it: every
388    /// regular layout cluster > 80 % inside a picture cluster is that
389    /// `PictureItem`'s child (`LayoutPostprocessor._set_cluster_children`,
390    /// `ReadingOrderModel._add_child_elements`). Emitted right after its
391    /// picture node. The JSON export writes these nodes as items parented to
392    /// that picture, after its caption; docling's Markdown and LaTeX picture
393    /// serializers print only the caption and the image, so every other
394    /// serializer skips it — except the Markdown export asked to
395    /// `traverse_pictures` ([`MarkdownExportOptions`], #599), which renders
396    /// them after the picture like upstream's item walk does.
397    PictureChildren(Vec<Node>),
398    /// A page boundary — docling's implicit page break between pages. The PPTX
399    /// backend emits one between consecutive slides. DocLang renders it as
400    /// `<page_break/>`; Markdown and JSON omit it (matching docling's default
401    /// exports, which carry page breaks only in the document model).
402    PageBreak,
403    /// A text item docling hangs in a *list group*, after the item before it
404    /// (an AsciiDoc paragraph still pending when a list opened is flushed into
405    /// the list's group): docling-core's list serializer prints it as one more
406    /// line of the list, indented to the group's depth `level` — or, `glue`,
407    /// when it is an inline group, appended to the line before it with no
408    /// separator at all. `text` is Markdown, like a paragraph's. Every other
409    /// serializer reads it as a paragraph.
410    ListText { level: u8, text: String, glue: bool },
411    /// An invisible page marker — the first node of every page the PDF paths
412    /// assemble: the 1-based page number and the page size in PDF points. It
413    /// carries exactly what the JSON export needs to populate docling's
414    /// `pages` map and to denormalize the 0–511 `<location>` grid back into
415    /// BOTTOMLEFT point bboxes for per-item `prov` (#171). Every other
416    /// serializer skips it, so Markdown / DocLang / DocTags output is
417    /// byte-for-byte unchanged.
418    PageInfo {
419        /// 1-based page number (0 = "not yet numbered": the assembler emits
420        /// the marker, the document-level collector stamps the real number).
421        page_no: usize,
422        /// Page width in PDF points.
423        width: f32,
424        /// Page height in PDF points.
425        height: f32,
426    },
427    /// A node docling keeps in the document model (and DocLang) but leaves out
428    /// of the Markdown and JSON exports — e.g. an ODF *presentation*'s pictures
429    /// and charts, which appear in the `.dclx` body but not in its `.md`/`.json`.
430    /// DocLang renders the wrapped node in place; Markdown and JSON skip it.
431    DoclangOnly(Box<Node>),
432    /// A verbatim plain-text dump — docling's plain-text backend emits the whole
433    /// file as a single text item (used for legacy USPTO APS `.txt` grants, which
434    /// docling routes to plain text rather than its APS parser). The stored string
435    /// is the file body, one record per line. Markdown/JSON render it as one text
436    /// block; the DocLang serializer reproduces minidom's per-line layout, CDATA-
437    /// escaping only the lines that need it (see `emit_text_dump`).
438    TextDump(String),
439}
440
441/// Vertical text position of an [`InlineRun`] — docling's `Script`.
442#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
443pub enum Script {
444    #[default]
445    Baseline,
446    Sub,
447    Super,
448}
449
450/// One styled segment of a [`Node::InlineGroup`] — the docling.rs analogue of a
451/// `TextItem` inside an `InlineGroup`, carrying the ancestor formatting docling
452/// tracks. `text` is already whitespace-normalized/trimmed (one segment per
453/// source text node). A hyperlink is intentionally not stored: DocLang drops the
454/// target inside inline scope, keeping only the anchor text.
455#[derive(Debug, Clone, PartialEq, Eq, Default)]
456pub struct InlineRun {
457    pub text: String,
458    pub bold: bool,
459    pub italic: bool,
460    pub underline: bool,
461    pub strike: bool,
462    pub script: Script,
463    pub code: bool,
464    /// An inline equation (`text` holds LaTeX): DocLang renders `<formula>…`,
465    /// Markdown/JSON keep the `$…$` already baked into the group's `md_text`.
466    pub formula: bool,
467}
468
469/// A DocLang content layer other than the default `body` (see [`Node::Furniture`]).
470#[derive(Debug, Clone, Copy, PartialEq, Eq)]
471pub enum ContentLayer {
472    /// Page headers/footers, HTML `<title>`, site navigation/chrome.
473    Furniture,
474    /// Editorial notes (docx reviewer comments).
475    Notes,
476    /// Invisible content (hidden spreadsheet sheets).
477    Invisible,
478}
479
480impl ContentLayer {
481    /// The `<layer value="…"/>` token value.
482    pub fn value(self) -> &'static str {
483        match self {
484            ContentLayer::Furniture => "furniture",
485            ContentLayer::Notes => "notes",
486            ContentLayer::Invisible => "invisible",
487        }
488    }
489}
490
491/// A set of content layers, `body` included — docling-core's
492/// `set[ContentLayer]` (`HTMLParams.layers`,
493/// `export_to_html(included_content_layers=…)`), where `body` is a member
494/// like any other. [`Default`] is docling's `DEFAULT_CONTENT_LAYERS`: body
495/// only, so an export built with it is unchanged from before layers could
496/// be chosen (#499).
497#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
498pub struct ContentLayers {
499    /// The main content (items without an explicit layer).
500    pub body: bool,
501    /// [`ContentLayer::Furniture`]: page headers/footers, navigation chrome.
502    pub furniture: bool,
503    /// [`ContentLayer::Notes`]: reviewer comments and other editorial notes.
504    pub notes: bool,
505    /// [`ContentLayer::Invisible`]: hidden content (hidden sheets, …).
506    pub invisible: bool,
507}
508
509impl Default for ContentLayers {
510    fn default() -> Self {
511        Self::BODY
512    }
513}
514
515impl ContentLayers {
516    /// Body only — docling's `DEFAULT_CONTENT_LAYERS`.
517    pub const BODY: Self = Self {
518        body: true,
519        furniture: false,
520        notes: false,
521        invisible: false,
522    };
523    /// Every layer — Python's `set(ContentLayer)`.
524    pub const ALL: Self = Self {
525        body: true,
526        furniture: true,
527        notes: true,
528        invisible: true,
529    };
530    /// No layer at all (nothing renders); build a set from it with
531    /// [`with`](Self::with) / [`with_body`](Self::with_body).
532    pub const NONE: Self = Self {
533        body: false,
534        furniture: false,
535        notes: false,
536        invisible: false,
537    };
538
539    /// The set plus `layer`.
540    pub const fn with(mut self, layer: ContentLayer) -> Self {
541        match layer {
542            ContentLayer::Furniture => self.furniture = true,
543            ContentLayer::Notes => self.notes = true,
544            ContentLayer::Invisible => self.invisible = true,
545        }
546        self
547    }
548
549    /// The set plus the body layer.
550    pub const fn with_body(mut self) -> Self {
551        self.body = true;
552        self
553    }
554
555    /// Whether `layer` is in the set; `None` is the body layer.
556    pub fn contains(&self, layer: Option<ContentLayer>) -> bool {
557        match layer {
558            None => self.body,
559            Some(ContentLayer::Furniture) => self.furniture,
560            Some(ContentLayer::Notes) => self.notes,
561            Some(ContentLayer::Invisible) => self.invisible,
562        }
563    }
564
565    /// Whether the layer spelled `name` (`body`, `furniture`, `notes`,
566    /// `invisible` — the JSON `content_layer` values) is in the set; an
567    /// unknown name is not.
568    pub fn contains_name(&self, name: &str) -> bool {
569        match name {
570            "body" => self.body,
571            "furniture" => self.furniture,
572            "notes" => self.notes,
573            "invisible" => self.invisible,
574            _ => false,
575        }
576    }
577
578    /// Parse a comma-separated list of layer names (`body,furniture`;
579    /// whitespace around a name is ignored, `all` is every layer). An
580    /// unknown name is the error. docling-core 2.99's `background` layer
581    /// (watermarks) has no items in this model, so the name is accepted and
582    /// adds nothing — a set written for Python keeps parsing.
583    pub fn parse_list(list: &str) -> Result<Self, String> {
584        let mut set = Self::NONE;
585        for name in list.split(',').map(str::trim).filter(|n| !n.is_empty()) {
586            match name {
587                "body" => set.body = true,
588                "furniture" => set.furniture = true,
589                "notes" => set.notes = true,
590                "invisible" => set.invisible = true,
591                "background" => {}
592                "all" => set = Self::ALL,
593                other => {
594                    return Err(format!(
595                        "unknown content layer `{other}` (expected body, furniture, notes, invisible or all)"
596                    ))
597                }
598            }
599        }
600        Ok(set)
601    }
602}
603
604/// Options of the HTML export ([`DoclingDocument::export_to_html_with`]):
605/// docling-core's `HTMLParams` subset the port honours. [`Default`] is
606/// upstream's default export — placeholder images, `artifacts` as the
607/// referenced-image directory, the body layer only.
608#[derive(Debug, Clone, PartialEq, Eq)]
609pub struct HtmlExportOptions {
610    /// How pictures render (`HTMLParams.image_mode`): nothing but captions
611    /// and meta for [`ImageMode::Placeholder`], `data:` URIs when embedded,
612    /// `<img src>` paths under [`artifacts_dir`](Self::artifacts_dir) when
613    /// referenced.
614    pub image_mode: ImageMode,
615    /// The directory referenced images are named under, the Markdown
616    /// export's convention (`<artifacts_dir>/image_NNNNNN.<ext>`).
617    pub artifacts_dir: String,
618    /// The content layers rendered (`HTMLParams.layers`, #499): an item on a
619    /// layer outside the set is skipped, its children still walked — exactly
620    /// how docling-core's `get_excluded_refs` reads the set.
621    pub layers: ContentLayers,
622}
623
624impl Default for HtmlExportOptions {
625    fn default() -> Self {
626        Self {
627            image_mode: ImageMode::Placeholder,
628            artifacts_dir: "artifacts".to_string(),
629            layers: ContentLayers::BODY,
630        }
631    }
632}
633
634/// Options of the Markdown export
635/// ([`DoclingDocument::export_to_markdown_with_options`], #599): the
636/// docling-core `MarkdownParams` the port honours beyond the image mode.
637/// [`Default`] is upstream's default export — placeholder images,
638/// `artifacts` as the referenced-image directory, the body layer only, no
639/// picture traversal, HTML and underscore escaping on, `<!-- image -->` —
640/// so a document exported with it is byte-identical to
641/// [`DoclingDocument::export_to_markdown`].
642#[derive(Debug, Clone, PartialEq, Eq)]
643pub struct MarkdownExportOptions {
644    /// How pictures render (`MarkdownParams.image_mode`): the placeholder,
645    /// `data:` URIs when embedded, `![Image](<artifacts_dir>/image_NNNNNN.<ext>)`
646    /// when referenced (the bytes come back for the caller to write).
647    pub image_mode: ImageMode,
648    /// The directory referenced images are named under.
649    pub artifacts_dir: String,
650    /// The content layers rendered (`MarkdownParams.layers`,
651    /// `export_to_markdown(included_content_layers=…)`): an item on a layer
652    /// outside the set is skipped, its children still walked. The default
653    /// body-only set drops page headers/footers (`furniture`), reviewer
654    /// comments (`notes`) and hidden sheets (`invisible`), as upstream does; a
655    /// scanned form's running header reads out with
656    /// `ContentLayers::BODY.with(ContentLayer::Furniture)`. The extra items
657    /// render through the body's serializers — a page header is a paragraph.
658    pub layers: ContentLayers,
659    /// `CommonParams.traverse_pictures`: render the text items nested in a
660    /// picture (the PDF pipeline's picture children — a bordered form laid
661    /// out as one picture holds every field as a child) after the picture's
662    /// own caption and image, as upstream yields them. Off, a picture prints
663    /// only its caption and image.
664    pub traverse_pictures: bool,
665    /// `MarkdownParams.escape_html`: `&`, `<` and `>` in text as `&amp;`,
666    /// `&lt;`, `&gt;` (Python's `html.escape(quote=False)`). Off, `R&D` stays
667    /// `R&D`.
668    pub escape_html: bool,
669    /// `MarkdownParams.escape_underscores`: `_` in text as `\_`. Off, the
670    /// text keeps its underscores.
671    pub escape_underscores: bool,
672    /// `MarkdownParams.image_placeholder`: what a picture prints as when it
673    /// renders no image data (the placeholder mode, or a picture without a
674    /// payload); upstream's `<!-- image -->`.
675    pub image_placeholder: String,
676    /// docling-core's `PlainTextDocSerializer` (#613, `export_to_text`,
677    /// docling's `--to text`): the Markdown walk with the decoration turned
678    /// off — headings without `#`, bold/italic/strikethrough markers and
679    /// inline code backticks dropped, a hyperlink reduced to its label, code
680    /// blocks unfenced, no GFM hard line breaks. List bullets/numbers,
681    /// checkbox marks and table grids stay. [`Self::plain_text`] pairs it
682    /// with upstream's `PlainTextParams` (no escaping, an empty image
683    /// placeholder).
684    pub plain_text: bool,
685}
686
687impl MarkdownExportOptions {
688    /// docling-core's `PlainTextParams` defaults (#613): [`Self::plain_text`]
689    /// on, HTML and underscore escaping off, pictures print nothing (their
690    /// captions still do), body layer only, no picture traversal — what
691    /// `DoclingDocument.export_to_text()` and docling's `--to text` write.
692    pub fn plain_text() -> Self {
693        Self {
694            escape_html: false,
695            escape_underscores: false,
696            image_placeholder: String::new(),
697            plain_text: true,
698            ..Self::default()
699        }
700    }
701}
702
703impl Default for MarkdownExportOptions {
704    fn default() -> Self {
705        Self {
706            image_mode: ImageMode::Placeholder,
707            artifacts_dir: "artifacts".to_string(),
708            layers: ContentLayers::BODY,
709            traverse_pictures: false,
710            escape_html: true,
711            escape_underscores: true,
712            image_placeholder: "<!-- image -->".to_string(),
713            plain_text: false,
714        }
715    }
716}
717
718/// DocLang-only content for a [`Node::ListItem`] whose DocLang form differs from
719/// its flat Markdown `text` (see [`Node::ListItem::dclx`]). `ordered` picks the
720/// enclosing `<list>` kind, `marker` the `<ldiv><marker>`; content is `runs`
721/// (structured equations/formatting) when non-empty, else `text` re-parsed for
722/// inline markers.
723#[derive(Debug, Clone, PartialEq, Eq, Default)]
724pub struct ListItemDclx {
725    pub ordered: bool,
726    pub marker: Option<String>,
727    pub text: String,
728    pub runs: Vec<InlineRun>,
729}
730
731impl Node {
732    /// The paragraph a [`Node::LabeledText`] renders as outside the JSON:
733    /// its text, wrapped as `[text](uri)` when it carries a hyperlink. Any
734    /// other node is returned unchanged.
735    pub fn labeled_as_paragraph(&self) -> std::borrow::Cow<'_, Node> {
736        match self {
737            Node::LabeledText { text, href, .. } => std::borrow::Cow::Owned(Node::Paragraph {
738                text: match href {
739                    Some(uri) => crate::hyperlink::markdown_link(text, uri),
740                    None => text.clone(),
741                },
742            }),
743            other => std::borrow::Cow::Borrowed(other),
744        }
745    }
746}
747
748impl InlineRun {
749    /// A run with no active formatting (renders as bare inline text).
750    pub fn is_plain(&self) -> bool {
751        !self.bold
752            && !self.italic
753            && !self.underline
754            && !self.strike
755            && !self.code
756            && !self.formula
757            && self.script == Script::Baseline
758    }
759}
760
761/// Build the [`Node`] for a paragraph of inline content from its structured
762/// `runs` and Markdown text, applying docling's `InlineGroup` boundary:
763///
764/// * a single plain run (or none) → a plain [`Node::Paragraph`] (which the
765///   serializers render as `<text>…</text>`, and a lone hyperlink via `<href>`);
766/// * a single uniformly-formatted run, or two or more runs → a
767///   [`Node::InlineGroup`]. `unwrapped` (the group's docling parent is a
768///   heading, so no enclosing `<text>`) only applies to multi-run groups.
769///
770/// Markdown/JSON render the group's `md_text`, so their output is identical to
771/// emitting a `Paragraph` — the structured runs are DocLang-only.
772pub fn inline_paragraph_node(md_text: String, runs: Vec<InlineRun>, unwrapped: bool) -> Node {
773    let single_plain = runs.len() <= 1 && runs.first().is_none_or(|r| r.is_plain());
774    if single_plain {
775        Node::Paragraph { text: md_text }
776    } else {
777        Node::InlineGroup {
778            unwrapped: unwrapped && runs.len() >= 2,
779            runs,
780            md_text,
781        }
782    }
783}
784
785/// One entry of a [`Node::FieldRegion`]: a marker/key/value triple, any of which
786/// may be absent. Mirrors docling's `field_item` with its `marker` / `field_key`
787/// / `field_value` child texts.
788#[derive(Debug, Clone, PartialEq, Default)]
789pub struct FieldItem {
790    pub marker: Option<String>,
791    pub key: Option<String>,
792    pub value: Option<String>,
793    /// docling's `kind` on the `field_value` item — `read_only` or
794    /// `fillable` (the value is or holds a form control); JSON-only.
795    pub value_kind: Option<String>,
796}
797
798/// One node of a [`Node::KeyValueGraph`] — docling-core's `GraphCell`.
799#[derive(Debug, Clone, PartialEq)]
800pub struct GraphCell {
801    /// docling's `GraphCellLabel` value: `key` or `value` (it also knows
802    /// `unspecified` and `checkbox`).
803    pub label: String,
804    /// The cell's number within its graph, what the links refer to.
805    pub cell_id: usize,
806    pub text: String,
807    /// The text before any cleanup — for an XBRL fact key, the concept's
808    /// qualified name where `text` is its local name.
809    pub orig: String,
810}
811
812/// One edge of a [`Node::KeyValueGraph`] — docling-core's `GraphLink`.
813#[derive(Debug, Clone, PartialEq)]
814pub struct GraphLink {
815    /// docling's `GraphLinkLabel` value: `to_value`, `to_child`, `to_parent`
816    /// or `to_key`.
817    pub label: String,
818    pub source_cell_id: usize,
819    pub target_cell_id: usize,
820}
821
822/// One DocumentPictureClassifier prediction — docling-core's
823/// `PictureClassificationClass` (`class_name` + `confidence`).
824#[derive(Debug, Clone, PartialEq)]
825pub struct PictureClass {
826    /// e.g. `bar_chart`, `logo`, `signature` (the classifier's 26-label set).
827    pub class_name: String,
828    pub confidence: f32,
829}
830
831/// A picture's text annotation — docling-core's `PictureDescriptionData`
832/// (`text` + `provenance`), the one shape upstream uses for every model that
833/// writes prose about a picture. The picture-OCR enrichment (#645) fills it
834/// with the lines the OCR engine read off the image, `provenance` naming the
835/// engine (`ppocr` / `tesseract`) the way a VLM description names its model.
836#[derive(Debug, Clone, PartialEq, Eq)]
837pub struct PictureDescription {
838    pub text: String,
839    pub provenance: String,
840}
841
842impl PictureDescription {
843    /// The provenance of a picture's author-written alt text (#676): the
844    /// `descr` (else `title`) of an OOXML picture's non-visual properties
845    /// — what DOCX, PPTX and XLSX authors type into "Alt Text". JSON writes
846    /// it as `meta.description.created_by`; Markdown renders it under strict
847    /// Markdown or `DoclingDocument::picture_alt_text`, HTML under the latter.
848    pub const ALT_TEXT: &'static str = "alt_text";
849
850    /// An alt-text description, see [`Self::ALT_TEXT`].
851    pub fn alt_text(text: impl Into<String>) -> Self {
852        Self {
853            text: text.into(),
854            provenance: Self::ALT_TEXT.to_string(),
855        }
856    }
857
858    /// Whether this description is a picture's alt text.
859    pub fn is_alt_text(&self) -> bool {
860        self.provenance == Self::ALT_TEXT
861    }
862}
863
864/// An extracted picture's raw encoded bytes plus its mimetype and pixel size —
865/// the docling.rs analogue of docling-core's `ImageRef`.
866#[derive(Debug, Clone, PartialEq)]
867pub struct PictureImage {
868    /// e.g. `image/png`, `image/jpeg`.
869    pub mimetype: String,
870    pub width: u32,
871    pub height: u32,
872    /// The image file bytes, exactly as embedded (PNG/JPEG/…).
873    pub data: Vec<u8>,
874    /// Pixels per inch of the image relative to the page it came from —
875    /// docling-core's `ImageRef.dpi`, which consumers use to map pixels back
876    /// to points. A crop rendered from a PDF page at `s` px/pt is `72·s`
877    /// (docling: `int(72 * images_scale)`, #519); an image embedded in an
878    /// office file has no render scale and keeps docling's `72`
879    /// ([`Self::DEFAULT_DPI`]).
880    pub dpi: u32,
881    /// The size the picture is *displayed* at in its document, in inches
882    /// (`[width, height]`, #834): a DOCX drawing's `wp:extent`, an ODT
883    /// frame's `svg:width` / `svg:height` — not the bitmap's pixel size
884    /// above, which docling's `ImageRef.size` carries. `None` when the
885    /// format has no such extent (a PDF crop, a standalone image). The
886    /// Pandoc export writes it as the `Image`'s `width` / `height`
887    /// attributes, as Pandoc's own readers do; docling's JSON has no field
888    /// for it, so the JSON export leaves it out.
889    pub display_size: Option<[f32; 2]>,
890}
891
892impl PictureImage {
893    /// docling's `ImageRef` default when no render scale applies.
894    pub const DEFAULT_DPI: u32 = 72;
895
896    /// The `dpi` of an image rendered at `scale` pixels per PDF point
897    /// (`72·scale`, rounded — `int()` would floor 143.99… to 143).
898    pub fn dpi_for_scale(scale: f32) -> u32 {
899        (72.0 * scale).round().max(1.0) as u32
900    }
901
902    /// A `data:` URI for the image (`data:<mimetype>;base64,<…>`).
903    pub fn data_uri(&self) -> String {
904        format!(
905            "data:{};base64,{}",
906            self.mimetype,
907            crate::base64::encode(&self.data)
908        )
909    }
910}
911
912/// One table cell as a first-class object (#240) — the Rust counterpart of
913/// docling's `TableCell`: its text, page geometry, grid rectangle and header
914/// roles. Produced by the PDF TableFormer paths from the predicted OTSL
915/// structure; `bbox` is `[l, t, r, b]` in page points with a top-left origin.
916#[derive(Debug, Clone, PartialEq)]
917pub struct TableCell {
918    pub text: String,
919    /// `[l, t, r, b]`, page points, top-left origin; `None` without geometry.
920    pub bbox: Option<[f32; 4]>,
921    /// Anchor grid position (0-based row/column offsets).
922    pub start_row: usize,
923    pub start_col: usize,
924    /// Span extents (≥ 1); the covered grid positions repeat the cell's text
925    /// in [`Table::rows`].
926    pub row_span: usize,
927    pub col_span: usize,
928    /// OTSL `ched` — a column-header cell.
929    pub column_header: bool,
930    /// OTSL `rhed` — a row-header cell.
931    pub row_header: bool,
932    /// OTSL `srow` — a section-row cell.
933    pub row_section: bool,
934}
935
936/// Where a picture's or table's caption text item hangs in the docling-JSON
937/// tree (#390). docling's backends do not agree, and the JSON structure is
938/// the only surface that shows it (Markdown, DocLang and LaTeX place a
939/// caption by its item, whatever its parent): the PDF pipeline parents a
940/// layout caption to the picture or table it belongs to, while every
941/// declarative backend creates the caption with `doc.add_text(label=CAPTION)`
942/// and no parent — the document body — even when the item itself sits in a
943/// group or under a section header (JATS, LaTeX, HTML, Markdown, EPUB,
944/// AsciiDoc all do). The office backends hang a chart's title caption off the
945/// chart's container (the sheet group, the slide, docx's current parent,
946/// docling#4190) — that is [`Node::Chart`]'s own path, not this choice. A
947/// backend that adds a new captioned item picks the variant matching
948/// upstream's `add_text` call for that format; the default is upstream's
949/// default.
950#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
951pub enum CaptionParent {
952    /// `#/body`, listed after the enclosing top-level item — docling's
953    /// `add_text` default, which every declarative backend leaves alone.
954    #[default]
955    Body,
956    /// The item's own container (its `parent`), listed ahead of the item:
957    /// the caption is created first, as docling's office backends do.
958    Container,
959    /// The item's own container, listed *after* the item: docling's HTML
960    /// backend adds a `<figure>`-wrapped table, then its `<figcaption>` under
961    /// `self.parents[self.level]` (docling#4050).
962    ContainerAfter,
963    /// The item itself — the caption is the picture's or table's first
964    /// child, as docling's PDF pipeline attaches a layout caption.
965    Item,
966}
967
968/// A simple row-major table. By default `rows[0]` is the header row; a
969/// [`TableStructure`] overlay overrides that and adds column spans.
970#[derive(Debug, Clone, PartialEq, Default)]
971pub struct Table {
972    pub rows: Vec<Vec<String>>,
973    /// Optional layout provenance: the four DocLang `<location>` values
974    /// (`x0,y0,x1,y1`, each already normalized to the 0–511 resolution) emitted
975    /// before the table's cells. Set only by backends with real geometry (e.g.
976    /// the spreadsheet backend, whose cell grid yields a bounding box); left
977    /// `None` by declarative backends, which have no coordinates.
978    pub location: Option<[u16; 4]>,
979    /// Optional OTSL structure overlay for backends that parse real table
980    /// geometry (USPTO CALS): explicit header-row count and horizontal-span
981    /// continuations. `None` → the default (row 0 is the header, no spans).
982    /// `rows` still carries the full text grid (span text replicated) for
983    /// Markdown/JSON; DocLang uses this overlay to emit `<ched/>`/`<lcel/>`.
984    pub structure: Option<TableStructure>,
985    /// Optional per-cell block content, parallel to `rows`. A *rich* cell (an
986    /// ODF cell holding a list, several paragraphs, or a nested table) carries
987    /// its DocLang blocks here; the DocLang serializer emits them after the
988    /// cell token instead of the flat `rows` text. Markdown/JSON ignore this
989    /// and render `rows`, so their output is unchanged. `None` (or an empty
990    /// `Vec` for a given cell) → the flat text is used everywhere.
991    pub cell_blocks: Option<Vec<Vec<Vec<Node>>>>,
992    /// Optional caption (docling's `TableItem.captions`): the JATS
993    /// `<table-wrap>` label+caption, an HTML `<caption>`, etc. Markdown renders
994    /// it as a text line *before* the grid; JSON emits a caption text item the
995    /// table references; DocLang emits a `<caption>` as the table's first child.
996    /// `None` → the table has no caption.
997    pub caption: Option<String>,
998    /// Where the caption item hangs in the JSON tree (#390); see
999    /// [`CaptionParent`]. Only the JSON export reads it.
1000    pub caption_parent: CaptionParent,
1001    /// The caption's own box on the table's page (0–511 grid) — the PDF
1002    /// pipeline's caption layout region, written as the caption item's
1003    /// `prov` (#609); see [`Node::Picture`]'s field of the same name.
1004    pub caption_location: Option<[u16; 4]>,
1005    /// Optional per-cell bounding boxes, same shape as [`Self::rows`]: `[l, t,
1006    /// r, b]` in page points with a **top-left** origin (the PDF pipeline's
1007    /// native space). Set by the ML pipeline's TableFormer paths — a spanned
1008    /// cell repeats its anchor's box across the covered grid positions — and
1009    /// First-class cells (#240): the authoritative per-cell records —
1010    /// text, page geometry, spans and header roles — when the backend
1011    /// produces them (the PDF TableFormer paths do; declarative backends
1012    /// leave `None`). [`Self::rows`] stays the dense text grid every
1013    /// serializer renders (a spanning cell's text is replicated across its
1014    /// covered positions there); JSON serializes these cells verbatim when
1015    /// present, and the DocLang structure overlay is derived from them.
1016    pub cells: Option<Vec<TableCell>>,
1017}
1018
1019impl Table {
1020    /// A cell's text at a grid position, `None` outside the grid.
1021    pub fn cell_text(&self, row: usize, col: usize) -> Option<&str> {
1022        self.rows.get(row)?.get(col).map(String::as_str)
1023    }
1024
1025    /// Replace the text at a grid position; `false` (and no change) outside
1026    /// the grid. When a first-class cell covers the position, the whole
1027    /// cell is updated: its record text and every grid position its span
1028    /// covers, so the repair shows once in Markdown, not once per covered
1029    /// column.
1030    pub fn set_cell_text(&mut self, row: usize, col: usize, text: impl Into<String>) -> bool {
1031        if self.rows.get(row).and_then(|r| r.get(col)).is_none() {
1032            return false;
1033        }
1034        let text = text.into();
1035        let covering = self.cells.as_mut().and_then(|cells| {
1036            cells.iter_mut().find(|c| {
1037                (c.start_row..c.start_row + c.row_span).contains(&row)
1038                    && (c.start_col..c.start_col + c.col_span).contains(&col)
1039            })
1040        });
1041        if let Some(cell) = covering {
1042            cell.text = text.clone();
1043            let (r0, r1) = (cell.start_row, cell.start_row + cell.row_span);
1044            let (c0, c1) = (cell.start_col, cell.start_col + cell.col_span);
1045            for r in self.rows.iter_mut().take(r1).skip(r0) {
1046                for slot in r.iter_mut().take(c1).skip(c0) {
1047                    *slot = text.clone();
1048                }
1049            }
1050        } else {
1051            self.rows[row][col] = text;
1052        }
1053        true
1054    }
1055
1056    /// Derive first-class cells (#240) from the dense grid plus the
1057    /// [`TableStructure`] overlay — how declarative tables (DOCX/XLSX merged
1058    /// regions, HTML `th`/spans, ODF covered cells, USPTO CALS) get real
1059    /// `TableCell` records without page geometry. Anchors are the positions
1060    /// not marked as span continuations; extents scan the continuation grids
1061    /// right/down (matching the DocLang `lcel`/`ucel` reading). Header roles
1062    /// come from the per-cell `col_header`/`row_header` grids when present,
1063    /// else the `header_row` band, else docling's declarative default (row 0
1064    /// is the header). Without any overlay every position is a 1×1 cell.
1065    pub fn derive_cells(&self) -> Vec<TableCell> {
1066        let s = self.structure.as_ref();
1067        let flag = |grid: Option<&Vec<Vec<bool>>>, r: usize, c: usize| {
1068            grid.and_then(|g| g.get(r))
1069                .and_then(|row| row.get(c))
1070                .copied()
1071                .unwrap_or(false)
1072        };
1073        let col_cont = |r: usize, c: usize| flag(s.map(|s| &s.col_continuation), r, c);
1074        let row_cont = |r: usize, c: usize| flag(s.map(|s| &s.row_continuation), r, c);
1075        let is_col_header = |r: usize, c: usize| match s {
1076            Some(st) if !st.col_header.is_empty() => flag(Some(&st.col_header), r, c),
1077            Some(st) if !st.header_row.is_empty() => st.header_row.get(r).copied().unwrap_or(false),
1078            _ => r == 0,
1079        };
1080        let mut cells = Vec::new();
1081        for (r, row) in self.rows.iter().enumerate() {
1082            for (c, text) in row.iter().enumerate() {
1083                if col_cont(r, c) || row_cont(r, c) {
1084                    continue; // covered by a span anchor
1085                }
1086                let mut col_span = 1;
1087                while c + col_span < row.len() && col_cont(r, c + col_span) {
1088                    col_span += 1;
1089                }
1090                let mut row_span = 1;
1091                while r + row_span < self.rows.len() && row_cont(r + row_span, c) {
1092                    row_span += 1;
1093                }
1094                cells.push(TableCell {
1095                    text: text.clone(),
1096                    bbox: None,
1097                    start_row: r,
1098                    start_col: c,
1099                    row_span,
1100                    col_span,
1101                    column_header: is_col_header(r, c),
1102                    row_header: flag(s.map(|s| &s.row_header), r, c),
1103                    row_section: false,
1104                });
1105            }
1106        }
1107        cells
1108    }
1109
1110    /// The number of leading grid rows that form the column header block —
1111    /// docling-core's `TableData._count_column_header_rows` (docling-core#767,
1112    /// 2.102, #778), shared by the Markdown serializer
1113    /// ([`Self::header_row_count`]) and the chunker's dataframe view, which
1114    /// must agree on where the header ends. Uses the first-class
1115    /// [`Self::cells`] when present (the PDF pipeline's TableFormer flags),
1116    /// else the cells derived from the structure overlay.
1117    ///
1118    /// - A row counts only when a `column_header` cell *starts* on it
1119    ///   (docling-core#723): a header spanning several rows is replicated
1120    ///   into each row it covers, and counting those would pull the data rows
1121    ///   beneath it into the header block.
1122    /// - A row also stops the block when it *carries body text* (#604,
1123    ///   docling-core#766): a cell starting on it that is not a column
1124    ///   header, has non-blank text and does not start in the table's first
1125    ///   column, which holds row labels left unmarked even on header rows. A
1126    ///   scanned form flags its first-column labels `column_header` on every
1127    ///   row; without the check each such row folded its values into the
1128    ///   header.
1129    /// - Row 0 is exempt from that check — model-predicted header rows are
1130    ///   often only partly flagged — unless a later row flags a cell starting
1131    ///   in the first column: that marks a column of row headers, not a
1132    ///   partly flagged header row.
1133    ///
1134    /// No fallback: a table without flags has no header rows here.
1135    pub fn column_header_row_count(&self) -> usize {
1136        if self.rows.is_empty() {
1137            return 0;
1138        }
1139        let derived;
1140        let cells: &[TableCell] = match &self.cells {
1141            Some(c) if !c.is_empty() => c,
1142            _ => {
1143                derived = self.derive_cells();
1144                &derived
1145            }
1146        };
1147        let num_rows = self.rows.len();
1148        let first_col = cells.iter().map(|c| c.start_col).min().unwrap_or(0);
1149        let leading_col_flagged_below = cells.iter().any(|c| {
1150            c.column_header && c.start_col == first_col && (1..num_rows).contains(&c.start_row)
1151        });
1152        let is_header_row = |r: usize| {
1153            let check_body = r > 0 || leading_col_flagged_below;
1154            let mut flagged = false;
1155            for c in cells.iter().filter(|c| c.start_row == r) {
1156                if c.column_header {
1157                    flagged = true;
1158                } else if check_body && c.start_col != first_col && !c.text.trim().is_empty() {
1159                    return false;
1160                }
1161            }
1162            flagged
1163        };
1164        (0..num_rows).take_while(|&r| is_header_row(r)).count()
1165    }
1166
1167    /// The number of leading grid rows the Markdown serializer renders as the
1168    /// header — docling-core's `_count_header_rows`:
1169    /// [`Self::column_header_row_count`], plus upstream's row-0 fallback for
1170    /// GFM, which needs a header row: `1` when no flag sits on any grid row
1171    /// below the first (a spanning header cell counts on every row it
1172    /// covers), so tables from backends that never set the flag keep row 0
1173    /// as the header. When flags exist but none makes a header row, the
1174    /// count is `0` and every row stays in the body under an empty header.
1175    pub fn header_row_count(&self) -> usize {
1176        let count = self.column_header_row_count();
1177        if count > 0 || self.rows.is_empty() {
1178            return count;
1179        }
1180        let derived;
1181        let cells: &[TableCell] = match &self.cells {
1182            Some(c) if !c.is_empty() => c,
1183            _ => {
1184                derived = self.derive_cells();
1185                &derived
1186            }
1187        };
1188        if cells
1189            .iter()
1190            .any(|c| c.column_header && c.start_row + c.row_span.max(1) > 1)
1191        {
1192            0
1193        } else {
1194            1
1195        }
1196    }
1197
1198    /// For every grid position, the position of the cell that covers it — its
1199    /// anchor (top-left start): itself for an unmerged position, the merge's
1200    /// start for one a spanning cell covers. Uses the first-class
1201    /// [`Self::cells`] when present, else the cells derived from the
1202    /// structure overlay. A rich cell's blocks ([`Self::cell_blocks`]) live on
1203    /// its anchor only, so a serializer that repeats a merged cell in every
1204    /// position it covers (docling-core#857) reads them through this.
1205    pub fn span_anchors(&self) -> Vec<Vec<(usize, usize)>> {
1206        let num_cols = self.rows.iter().map(Vec::len).max().unwrap_or(0);
1207        let mut anchors: Vec<Vec<(usize, usize)>> = (0..self.rows.len())
1208            .map(|r| (0..num_cols).map(|c| (r, c)).collect())
1209            .collect();
1210        let derived;
1211        let cells: &[TableCell] = match &self.cells {
1212            Some(c) if !c.is_empty() => c,
1213            _ => {
1214                derived = self.derive_cells();
1215                &derived
1216            }
1217        };
1218        for cell in cells {
1219            let rows = cell.start_row..cell.start_row + cell.row_span.max(1);
1220            for row in anchors.iter_mut().take(rows.end).skip(rows.start) {
1221                let cols = cell.start_col..cell.start_col + cell.col_span.max(1);
1222                for pos in row.iter_mut().take(cols.end).skip(cols.start) {
1223                    *pos = (cell.start_row, cell.start_col);
1224                }
1225            }
1226        }
1227        anchors
1228    }
1229
1230    /// The first-class cell covering a grid position, if any.
1231    pub fn cell_at(&self, row: usize, col: usize) -> Option<&TableCell> {
1232        self.cells.as_ref()?.iter().find(|c| {
1233            (c.start_row..c.start_row + c.row_span).contains(&row)
1234                && (c.start_col..c.start_col + c.col_span).contains(&col)
1235        })
1236    }
1237
1238    /// A cell's bounding box (`[l, t, r, b]`, page points, top-left origin);
1239    /// `None` when no cell with geometry covers the position.
1240    pub fn cell_bbox(&self, row: usize, col: usize) -> Option<[f32; 4]> {
1241        self.cell_at(row, col)?.bbox
1242    }
1243
1244    /// Set (or replace) the bounding box of the cell covering a grid
1245    /// position; `false` outside the text grid. A table without first-class
1246    /// cells materializes them first (one 1×1 cell per grid position, texts
1247    /// from the grid), so declarative tables can be annotated too.
1248    pub fn set_cell_bbox(&mut self, row: usize, col: usize, bbox: [f32; 4]) -> bool {
1249        if self.rows.get(row).and_then(|r| r.get(col)).is_none() {
1250            return false;
1251        }
1252        let rows = &self.rows;
1253        let cells = self.cells.get_or_insert_with(|| {
1254            rows.iter()
1255                .enumerate()
1256                .flat_map(|(r, cols)| {
1257                    cols.iter().enumerate().map(move |(c, text)| TableCell {
1258                        text: text.clone(),
1259                        bbox: None,
1260                        start_row: r,
1261                        start_col: c,
1262                        row_span: 1,
1263                        col_span: 1,
1264                        column_header: false,
1265                        row_header: false,
1266                        row_section: false,
1267                    })
1268                })
1269                .collect()
1270        });
1271        match cells.iter_mut().find(|c| {
1272            (c.start_row..c.start_row + c.row_span).contains(&row)
1273                && (c.start_col..c.start_col + c.col_span).contains(&col)
1274        }) {
1275            Some(cell) => {
1276                cell.bbox = Some(bbox);
1277                true
1278            }
1279            None => {
1280                cells.push(TableCell {
1281                    text: self.rows[row][col].clone(),
1282                    bbox: Some(bbox),
1283                    start_row: row,
1284                    start_col: col,
1285                    row_span: 1,
1286                    col_span: 1,
1287                    column_header: false,
1288                    row_header: false,
1289                    row_section: false,
1290                });
1291                true
1292            }
1293        }
1294    }
1295
1296    /// The anchor position of the cell whose box overlaps `bbox` best
1297    /// (largest intersection-over-union), ties resolved in cell order.
1298    /// `None` when nothing overlaps or the table carries no geometry. This
1299    /// is the lookup half of the repair workflow: find the cell an external
1300    /// OCR box refers to, then [`Self::set_cell_text`] it.
1301    pub fn find_cell_by_bbox(&self, bbox: [f32; 4]) -> Option<(usize, usize)> {
1302        let area = |b: &[f32; 4]| ((b[2] - b[0]) * (b[3] - b[1])).max(0.0);
1303        let mut best: Option<(f32, (usize, usize))> = None;
1304        for cell in self.cells.as_deref()?.iter() {
1305            let Some(cb) = cell.bbox else { continue };
1306            let iw = (bbox[2].min(cb[2]) - bbox[0].max(cb[0])).max(0.0);
1307            let ih = (bbox[3].min(cb[3]) - bbox[1].max(cb[1])).max(0.0);
1308            let inter = iw * ih;
1309            if inter <= 0.0 {
1310                continue;
1311            }
1312            let iou = inter / (area(&bbox) + area(&cb) - inter).max(f32::EPSILON);
1313            if best.is_none_or(|(b, _)| iou > b) {
1314                best = Some((iou, (cell.start_row, cell.start_col)));
1315            }
1316        }
1317        best.map(|(_, pos)| pos)
1318    }
1319
1320    /// Locate the cell overlapping `bbox` best and replace its text — the
1321    /// one-call form of the OCR-repair loop. Returns the updated anchor.
1322    pub fn update_cell_by_bbox(
1323        &mut self,
1324        bbox: [f32; 4],
1325        text: impl Into<String>,
1326    ) -> Option<(usize, usize)> {
1327        let (row, col) = self.find_cell_by_bbox(bbox)?;
1328        self.set_cell_text(row, col, text);
1329        Some((row, col))
1330    }
1331}
1332
1333/// OTSL structure overlay for a [`Table`], parallel to [`Table::rows`].
1334#[derive(Debug, Clone, PartialEq, Default)]
1335pub struct TableStructure {
1336    /// Per-row: `true` if the row's non-empty cells are column headers
1337    /// (emitted as `<ched/>` rather than `<fcel/>`).
1338    pub header_row: Vec<bool>,
1339    /// Same shape as [`Table::rows`]; `true` where a cell continues a
1340    /// horizontal span from its left neighbour (emitted as `<lcel/>`).
1341    pub col_continuation: Vec<Vec<bool>>,
1342    /// Same shape as [`Table::rows`]; `true` where a cell continues a
1343    /// vertical span from the cell above (emitted as `<ucel/>`). Empty or all
1344    /// `false` when the backend has no vertical spans (e.g. USPTO CALS).
1345    pub row_continuation: Vec<Vec<bool>>,
1346    /// Same shape as [`Table::rows`]; `true` where a non-empty cell is a row
1347    /// header (emitted as `<rhed/>`) — a chart's category column. Empty when
1348    /// the table has no row headers.
1349    pub row_header: Vec<Vec<bool>>,
1350    /// Same shape as [`Table::rows`]; `true` where a cell is a *column header*
1351    /// cell (an HTML `<th>`). When non-empty this per-cell grid supersedes the
1352    /// per-row [`Self::header_row`] for `<ched/>` emission, matching docling's
1353    /// cell-level `column_header` flag; the chunker derives its header-row
1354    /// count from it.
1355    pub col_header: Vec<Vec<bool>>,
1356}
1357
1358/// [`for_each_picture_in_mut`], read-only: every picture in `nodes`, however
1359/// nested, for a pass that only looks (the DocLang asset digests, #898).
1360pub fn for_each_picture_in<'a>(nodes: &'a [Node], f: &mut dyn FnMut(&'a Node)) {
1361    for node in nodes {
1362        match node {
1363            Node::Picture { .. } => f(node),
1364            Node::Group { children, .. } | Node::PictureChildren(children) => {
1365                for_each_picture_in(children, f)
1366            }
1367            Node::Located { inner, .. }
1368            | Node::Prov { inner, .. }
1369            | Node::Track { inner, .. }
1370            | Node::Furniture { inner, .. }
1371            | Node::Commented { inner, .. }
1372            | Node::DoclangOnly(inner) => for_each_picture_in(std::slice::from_ref(inner), f),
1373            Node::Table(t) => {
1374                if let Some(blocks) = t.cell_blocks.as_ref() {
1375                    for row in blocks {
1376                        for cell in row {
1377                            for_each_picture_in(cell, f);
1378                        }
1379                    }
1380                }
1381            }
1382            _ => {}
1383        }
1384    }
1385}
1386
1387/// [`DoclingDocument::for_each_picture_mut`] over a node slice — every
1388/// picture in `nodes`, however nested (groups, wrappers, table cell blocks),
1389/// for a caller that holds page batches rather than a document (the
1390/// streaming PDF path, #896).
1391pub fn for_each_picture_in_mut(nodes: &mut [Node], f: &mut dyn FnMut(&mut Node)) {
1392    for node in nodes {
1393        match node {
1394            Node::Picture { .. } => f(node),
1395            Node::Group { children, .. } | Node::PictureChildren(children) => {
1396                for_each_picture_in_mut(children, f)
1397            }
1398            Node::Located { inner, .. }
1399            | Node::Prov { inner, .. }
1400            | Node::Track { inner, .. }
1401            | Node::Furniture { inner, .. }
1402            | Node::Commented { inner, .. }
1403            | Node::DoclangOnly(inner) => for_each_picture_in_mut(std::slice::from_mut(inner), f),
1404            Node::Table(t) => {
1405                if let Some(blocks) = t.cell_blocks.as_mut() {
1406                    for row in blocks {
1407                        for cell in row {
1408                            for_each_picture_in_mut(cell, f);
1409                        }
1410                    }
1411                }
1412            }
1413            _ => {}
1414        }
1415    }
1416}
1417
1418impl DoclingDocument {
1419    /// Create an empty document with the given name.
1420    pub fn new(name: impl Into<String>) -> Self {
1421        Self {
1422            name: name.into(),
1423            nodes: Vec::new(),
1424            strict_markdown: false,
1425            compact_tables: false,
1426            picture_alt_text: false,
1427            metadata: Default::default(),
1428            metadata_output: Default::default(),
1429            page_break_placeholder: None,
1430            links: Vec::new(),
1431            confidence: None,
1432            tree: None,
1433            page_images: std::collections::BTreeMap::new(),
1434        }
1435    }
1436
1437    /// Append a node.
1438    /// The document's top-level tables in reading order — the read half of
1439    /// the post-extraction table API (#238). [`Node::Located`] wrappers (the
1440    /// PDF pipeline attaches layout provenance that way) are looked through;
1441    /// tables nested inside rich table cells (`Table::cell_blocks`) are not
1442    /// traversed.
1443    pub fn tables(&self) -> impl Iterator<Item = &Table> {
1444        fn unwrap_table(n: &Node) -> Option<&Table> {
1445            match n {
1446                Node::Table(t) => Some(t),
1447                Node::Located { inner, .. }
1448                | Node::Prov { inner, .. }
1449                | Node::Track { inner, .. } => unwrap_table(inner),
1450                _ => None,
1451            }
1452        }
1453        self.nodes.iter().filter_map(unwrap_table)
1454    }
1455
1456    /// Mutable access to the document's top-level tables, for repair
1457    /// workflows (#238): locate a cell via [`Table::find_cell_by_bbox`], fix
1458    /// its text with [`Table::set_cell_text`], then re-export — every
1459    /// serializer reads the same grid.
1460    pub fn tables_mut(&mut self) -> impl Iterator<Item = &mut Table> {
1461        fn unwrap_table(n: &mut Node) -> Option<&mut Table> {
1462            match n {
1463                Node::Table(t) => Some(t),
1464                Node::Located { inner, .. }
1465                | Node::Prov { inner, .. }
1466                | Node::Track { inner, .. } => unwrap_table(inner),
1467                _ => None,
1468            }
1469        }
1470        self.nodes.iter_mut().filter_map(unwrap_table)
1471    }
1472
1473    pub fn push(&mut self, node: Node) {
1474        self.nodes.push(node);
1475    }
1476
1477    /// Visit every [`Node::Picture`] in the flat node stream, wherever it
1478    /// nests — group children, table cell blocks, a picture's own
1479    /// children, the located/prov/track/comment/furniture wrappers — so an
1480    /// enrichment that reads the embedded images (picture OCR, #645) reaches
1481    /// each one. The callback gets the picture node itself.
1482    pub fn for_each_picture_mut(&mut self, f: &mut dyn FnMut(&mut Node)) {
1483        for_each_picture_in_mut(&mut self.nodes, f);
1484    }
1485
1486    /// Convenience: append a heading.
1487    pub fn add_heading(&mut self, level: u8, text: impl Into<String>) {
1488        self.push(Node::Heading {
1489            level,
1490            text: text.into(),
1491        });
1492    }
1493
1494    /// Convenience: append a paragraph.
1495    pub fn add_paragraph(&mut self, text: impl Into<String>) {
1496        self.push(Node::Paragraph { text: text.into() });
1497    }
1498
1499    /// Serialize the document to Markdown.
1500    ///
1501    /// The Rust equivalent of docling-core's
1502    /// `DoclingDocument.export_to_markdown()`. Uses [`Self::strict_markdown`] to
1503    /// pick between docling-legacy output (default) and the cleaner, more
1504    /// conformant variant.
1505    pub fn export_to_markdown(&self) -> String {
1506        to_markdown(self, self.strict_markdown)
1507    }
1508
1509    /// Serialize to Markdown, explicitly choosing the mode regardless of
1510    /// [`Self::strict_markdown`]. `strict = true` produces cleaner, more
1511    /// conformant Markdown (code-fence languages preserved, no inline-run
1512    /// spacing artifacts); `strict = false` reproduces docling's legacy output.
1513    pub fn export_to_markdown_with(&self, strict: bool) -> String {
1514        to_markdown(self, strict)
1515    }
1516
1517    /// Markdown for this document as the *content of a rich table cell*
1518    /// (docling-core's `in_table_cell` serialization, docling-core#540):
1519    /// headings render as plain text since Markdown tables can't hold them.
1520    /// Backends build a sub-document per rich cell and flatten this into the
1521    /// cell text; no trailing newline.
1522    pub fn export_to_table_cell_markdown(&self) -> String {
1523        crate::markdown::to_markdown_table_cell(self, self.strict_markdown)
1524    }
1525
1526    /// Serialize to docling-core's native JSON wire format (`DoclingDocument`
1527    /// schema), pretty-printed — the Rust equivalent of
1528    /// `DoclingDocument.export_to_dict()` / `save_as_json()`. The output loads
1529    /// back into Python docling-core and round-trips to the same Markdown.
1530    pub fn export_to_json(&self) -> String {
1531        let mut out = Vec::new();
1532        self.write_json_pretty(&mut out)
1533            .expect("DoclingDocument JSON is always serializable");
1534        String::from_utf8(out).expect("serde_json writes UTF-8")
1535    }
1536
1537    /// The same JSON wire format as [`Self::export_to_json`], as a
1538    /// `serde_json::Value` — for callers that append response-level extras
1539    /// (docling-serve adds the confidence report, #183) before serializing.
1540    ///
1541    /// The `Value` is large — ~2.7 KB per text item — so on a long document
1542    /// prefer [`Self::write_json`], which writes the same JSON without it.
1543    pub fn export_to_json_value(&self) -> serde_json::Value {
1544        crate::json::to_json(self)
1545    }
1546
1547    /// Write the JSON of [`Self::export_to_json_value`] to `writer`, compact
1548    /// — byte for byte `serde_json::to_writer(writer, &doc.export_to_json_value())`
1549    /// — without building the `Value`: the export holds its text items in a
1550    /// compact form and serializes them straight to the writer. Wrap a file
1551    /// or socket in a `BufWriter`.
1552    pub fn write_json<W: std::io::Write>(&self, writer: W) -> std::io::Result<()> {
1553        crate::json::write_json(self, writer, false).map_err(std::io::Error::from)
1554    }
1555
1556    /// [`Self::write_json`], indented as [`Self::export_to_json`] is.
1557    pub fn write_json_pretty<W: std::io::Write>(&self, writer: W) -> std::io::Result<()> {
1558        crate::json::write_json(self, writer, true).map_err(std::io::Error::from)
1559    }
1560
1561    /// [`Self::write_json_pretty`] with `extras` appended to the top-level
1562    /// object after `pages` — byte for byte `serde_json::to_writer_pretty`
1563    /// of [`Self::export_to_json_value`] with each `value[key] = v` set (a
1564    /// key the document JSON does not have), without building that `Value`:
1565    /// docling-serve's response adds its `confidence` report this way.
1566    pub fn write_json_pretty_with<W: std::io::Write>(
1567        &self,
1568        writer: W,
1569        extras: &[(&str, &serde_json::Value)],
1570    ) -> std::io::Result<()> {
1571        crate::json::write_json_with(self, writer, true, extras).map_err(std::io::Error::from)
1572    }
1573
1574    /// Serialize to a complete LaTeX document — the Rust counterpart of
1575    /// docling-core's `LaTeXDocSerializer` with default parameters (docling
1576    /// 2.124's `--to latex`, #317). No trailing newline, like the upstream
1577    /// CLI's `<stem>.tex`.
1578    pub fn export_to_latex(&self) -> String {
1579        crate::latex::to_latex(self)
1580    }
1581
1582    /// Serialize to Pandoc's AST as JSON (`pandoc -f json`, #515) with the
1583    /// default options: pictures as captioned figures without image data,
1584    /// body layer only, the [`PANDOC_API_VERSION`](crate::pandoc::PANDOC_API_VERSION)
1585    /// API. One line, no trailing newline. See [`crate::pandoc`].
1586    pub fn export_to_pandoc_json(&self) -> String {
1587        crate::pandoc::to_pandoc(self, &crate::pandoc::PandocExportOptions::default())
1588            .expect("the default Pandoc API version is always supported")
1589            .0
1590    }
1591
1592    /// Pandoc JSON per `options` (image mode, artifacts directory, content
1593    /// layers, required API version). Returns the JSON and, for
1594    /// [`ImageMode::Referenced`], the `(path, bytes)` image files; an
1595    /// unsupported `api_version` is an error.
1596    pub fn export_to_pandoc_json_with(
1597        &self,
1598        options: &crate::pandoc::PandocExportOptions,
1599    ) -> Result<crate::pandoc::PandocOutput, crate::pandoc::PandocError> {
1600        crate::pandoc::to_pandoc(self, options)
1601    }
1602
1603    /// Serialize to DocLang XML (`<doclang version="0.7">…`), the markup that
1604    /// lives inside a `.dclx` archive — the Rust counterpart of docling-core's
1605    /// `export_to_doclang()` with default parameters. No trailing newline; the
1606    /// archive writer appends exactly one.
1607    pub fn export_to_doclang(&self) -> String {
1608        self.export_doclang(crate::doclang::Pictures::Referenced { collect: false })
1609            .0
1610    }
1611
1612    /// [`Self::export_to_doclang`] plus the picture assets its
1613    /// `<src uri="assets/image_….png"/>` references name, as `(path, bytes)`
1614    /// in document order — the parts docling's `save_as_doclang_archive`
1615    /// stores next to `document.xml`. PNG and JPEG pictures come back as PNG
1616    /// (a JPEG re-encoded from its libjpeg-decoded pixels); other encodings
1617    /// keep their own bytes for the archive writer to convert.
1618    pub fn export_to_doclang_with_assets(&self) -> (String, Vec<(String, Vec<u8>)>) {
1619        self.export_doclang(crate::doclang::Pictures::Referenced { collect: true })
1620    }
1621
1622    /// DocLang with docling's `image_mode` for pictures (#884):
1623    /// [`ImageMode::Placeholder`] writes no `<src>` — docling-core's own
1624    /// `export_to_doclang()` default, which upstream's `.dclg` fixtures hold
1625    /// — [`ImageMode::Embedded`] a `data:` URI of the PNG,
1626    /// [`ImageMode::Referenced`] is [`Self::export_to_doclang_with_assets`].
1627    pub fn export_to_doclang_with_images(
1628        &self,
1629        mode: ImageMode,
1630    ) -> (String, Vec<(String, Vec<u8>)>) {
1631        use crate::doclang::Pictures;
1632        self.export_doclang(match mode {
1633            ImageMode::Placeholder => Pictures::Placeholder,
1634            ImageMode::Embedded => Pictures::Embedded,
1635            ImageMode::Referenced => Pictures::Referenced { collect: true },
1636        })
1637    }
1638
1639    /// An opted-in item tree's DocLang ([`crate::tree::ItemTree::doclang`]),
1640    /// else — no such tree, or one the port does not cover — the nodes'.
1641    fn export_doclang(
1642        &self,
1643        pictures: crate::doclang::Pictures,
1644    ) -> (String, Vec<(String, Vec<u8>)>) {
1645        self.tree
1646            .as_ref()
1647            .filter(|t| t.doclang)
1648            .and_then(|t| crate::doclang_tree::export(t, pictures))
1649            .unwrap_or_else(|| crate::doclang::render(&self.nodes, pictures))
1650    }
1651
1652    /// Serialize to Markdown with an explicit picture [`ImageMode`] (mirrors
1653    /// docling's `image_mode`). Returns the Markdown and, for
1654    /// [`ImageMode::Referenced`], the `(relative-path, bytes)` of each image the
1655    /// caller should write next to the Markdown file. `artifacts_dir` is the
1656    /// directory name used in referenced links.
1657    pub fn export_to_markdown_with_images(
1658        &self,
1659        image_mode: ImageMode,
1660        artifacts_dir: &str,
1661    ) -> (String, Vec<(String, Vec<u8>)>) {
1662        to_markdown_images(self, self.strict_markdown, image_mode, artifacts_dir)
1663    }
1664
1665    /// Markdown per `options` (#599) — docling-core's
1666    /// `export_to_markdown(included_content_layers=…, image_mode=…,
1667    /// image_placeholder=…, escape_html=…, escape_underscores=…,
1668    /// traverse_pictures=…)`: the content layers rendered, whether a
1669    /// picture's nested text items print, HTML and underscore escaping, the
1670    /// image placeholder, and the image mode with its referenced-image
1671    /// directory. [`Self::strict_markdown`] still picks the Markdown flavour.
1672    /// Returns the Markdown and, for [`ImageMode::Referenced`], the
1673    /// `(path, bytes)` artifacts. With [`MarkdownExportOptions::default`]
1674    /// the Markdown is [`Self::export_to_markdown`]'s byte for byte.
1675    pub fn export_to_markdown_with_options(
1676        &self,
1677        options: &MarkdownExportOptions,
1678    ) -> (String, Vec<(String, Vec<u8>)>) {
1679        crate::markdown::to_markdown_with_options(self, self.strict_markdown, options)
1680    }
1681
1682    /// WebVTT (#614) — what docling's `--to vtt` writes
1683    /// (`DoclingDocument.save_as_vtt`): a cue per timed text item — a WebVTT
1684    /// input's cues, an audio/video transcript's segments — hours always
1685    /// written, the `</v>` of a lone voice span omitted. A document without
1686    /// timed text is the bare `WEBVTT` header. No trailing newline.
1687    pub fn export_to_vtt(&self) -> String {
1688        crate::vtt::to_vtt(self, &crate::vtt::VttExportOptions::default())
1689    }
1690
1691    /// [`Self::export_to_vtt`] with docling-core's `WebVTTParams`
1692    /// (`omit_hours_if_zero`, `omit_voice_end`).
1693    pub fn export_to_vtt_with_options(&self, options: &crate::vtt::VttExportOptions) -> String {
1694        crate::vtt::to_vtt(self, options)
1695    }
1696
1697    /// Plain text — docling-core's `DoclingDocument.export_to_text()` with
1698    /// its defaults (#613, docling's `--to text` / `<stem>.txt`): the
1699    /// Markdown export without decoration ([`MarkdownExportOptions::plain_text`]).
1700    /// Lists keep their bullets and numbers, tables their `|` grid. No
1701    /// trailing newline: upstream's `serialize().text`, which its CLI
1702    /// writes verbatim to `<stem>.txt`.
1703    pub fn export_to_text(&self) -> String {
1704        let (mut text, _) = crate::markdown::to_markdown_with_options(
1705            self,
1706            self.strict_markdown,
1707            &MarkdownExportOptions::plain_text(),
1708        );
1709        if text.ends_with('\n') {
1710            text.pop();
1711        }
1712        text
1713    }
1714
1715    /// A complete HTML document — docling-core's `HTMLDocSerializer` with its
1716    /// defaults (#492): pictures stay out (`ImageRefMode.PLACEHOLDER`, only
1717    /// their captions and meta render). See [`export_to_html_with_images`]
1718    /// for the embedded / referenced modes and [`crate::html`]'s module docs
1719    /// for what is reproduced.
1720    ///
1721    /// [`export_to_html_with_images`]: Self::export_to_html_with_images
1722    pub fn export_to_html(&self) -> String {
1723        crate::html::to_html(self, &HtmlExportOptions::default()).0
1724    }
1725
1726    /// HTML with pictures per `image_mode`: `data:` URIs when embedded, and
1727    /// when referenced `<img src>` paths under `artifacts_dir` whose bytes come
1728    /// back as `(path, bytes)` for the caller to write — the Markdown export's
1729    /// contract and file names.
1730    pub fn export_to_html_with_images(
1731        &self,
1732        image_mode: ImageMode,
1733        artifacts_dir: &str,
1734    ) -> (String, Vec<(String, Vec<u8>)>) {
1735        crate::html::to_html(
1736            self,
1737            &HtmlExportOptions {
1738                image_mode,
1739                artifacts_dir: artifacts_dir.to_string(),
1740                ..HtmlExportOptions::default()
1741            },
1742        )
1743    }
1744
1745    /// HTML rendering the content `layers` — docling-core's
1746    /// `export_to_html(included_content_layers=…)` (#499). The default export
1747    /// is body only; `ContentLayers::BODY.with(ContentLayer::Furniture)` adds
1748    /// page headers/footers, `.with(ContentLayer::Notes)` reviewer comments,
1749    /// [`ContentLayers::ALL`] is Python's `set(ContentLayer)`. An item on a
1750    /// layer outside the set is skipped while its children are still walked,
1751    /// and the items that do render go through the same serializers as the
1752    /// body (a page header is a `<p>`, a comment a `<p>`, a header table a
1753    /// `<table>`), exactly as upstream's `HTMLParams.layers` behaves. Pictures
1754    /// stay placeholders; see [`export_to_html_with`] for the full option set.
1755    ///
1756    /// [`export_to_html_with`]: Self::export_to_html_with
1757    pub fn export_to_html_with_layers(&self, layers: ContentLayers) -> String {
1758        crate::html::to_html(
1759            self,
1760            &HtmlExportOptions {
1761                layers,
1762                ..HtmlExportOptions::default()
1763            },
1764        )
1765        .0
1766    }
1767
1768    /// HTML per `options` — image mode, referenced-image directory and content
1769    /// layers in one call; the other `export_to_html*` methods are
1770    /// shorthands for it. Returns the HTML and, for
1771    /// [`ImageMode::Referenced`], the `(path, bytes)` artifacts.
1772    pub fn export_to_html_with(
1773        &self,
1774        options: &HtmlExportOptions,
1775    ) -> (String, Vec<(String, Vec<u8>)>) {
1776        crate::html::to_html(self, options)
1777    }
1778}
1779
1780#[cfg(test)]
1781mod table_api_tests {
1782    use super::*;
1783
1784    fn cell(
1785        text: &str,
1786        bbox: [f32; 4],
1787        (start_row, start_col): (usize, usize),
1788        (row_span, col_span): (usize, usize),
1789    ) -> TableCell {
1790        TableCell {
1791            text: text.into(),
1792            bbox: Some(bbox),
1793            start_row,
1794            start_col,
1795            row_span,
1796            col_span,
1797            column_header: false,
1798            row_header: false,
1799            row_section: false,
1800        }
1801    }
1802
1803    fn table() -> Table {
1804        Table {
1805            rows: vec![
1806                vec!["Year".into(), "Ducks".into()],
1807                vec!["2019".into(), "120".into()],
1808            ],
1809            cells: Some(vec![
1810                cell("Year", [0.0, 0.0, 50.0, 10.0], (0, 0), (1, 1)),
1811                cell("Ducks", [50.0, 0.0, 100.0, 10.0], (0, 1), (1, 1)),
1812                cell("2019", [0.0, 10.0, 50.0, 20.0], (1, 0), (1, 1)),
1813                cell("120", [50.0, 10.0, 100.0, 20.0], (1, 1), (1, 1)),
1814            ]),
1815            ..Default::default()
1816        }
1817    }
1818
1819    /// Declarative tables derive first-class cells from the structure
1820    /// overlay: continuation grids become span extents, `col_header` (or the
1821    /// row-0 fallback) becomes the header role — the XLSX/DOCX/HTML merge
1822    /// path into real `TableCell`s (#240).
1823    #[test]
1824    fn derive_cells_reads_spans_and_headers_from_structure() {
1825        let t = Table {
1826            rows: vec![
1827                vec!["Wide".into(), "Wide".into(), "C".into()],
1828                vec!["a".into(), "b".into(), "c".into()],
1829            ],
1830            structure: Some(TableStructure {
1831                header_row: vec![true, false],
1832                col_continuation: vec![vec![false, true, false], vec![false; 3]],
1833                row_continuation: vec![vec![false; 3], vec![false; 3]],
1834                row_header: Vec::new(),
1835                col_header: Vec::new(),
1836            }),
1837            ..Default::default()
1838        };
1839        let cells = t.derive_cells();
1840        assert_eq!(cells.len(), 5, "two anchors in row 0, three in row 1");
1841        let wide = &cells[0];
1842        assert_eq!((wide.col_span, wide.row_span), (2, 1));
1843        assert!(wide.column_header, "header_row band");
1844        assert!(cells.iter().skip(2).all(|c| !c.column_header));
1845
1846        // Without any overlay: every position 1x1, row 0 the header
1847        // (docling's declarative default — the old JSON synthesis).
1848        let plain = Table {
1849            rows: vec![vec!["h".into()], vec!["x".into()]],
1850            ..Default::default()
1851        };
1852        let cells = plain.derive_cells();
1853        assert_eq!(cells.len(), 2);
1854        assert!(cells[0].column_header && !cells[1].column_header);
1855    }
1856
1857    /// A spanning cell updates once: the record text and every covered grid
1858    /// position — a repair shows once in Markdown, not once per column.
1859    #[test]
1860    fn span_repair_updates_the_whole_cell() {
1861        let mut t = Table {
1862            rows: vec![
1863                vec!["Wide".into(), "Wide".into(), "C".into()],
1864                vec!["a".into(), "b".into(), "c".into()],
1865            ],
1866            cells: Some(vec![
1867                cell("Wide", [0.0, 0.0, 100.0, 10.0], (0, 0), (1, 2)),
1868                cell("C", [100.0, 0.0, 150.0, 10.0], (0, 2), (1, 1)),
1869            ]),
1870            ..Default::default()
1871        };
1872        // Update through the covered (non-anchor) position.
1873        assert!(t.set_cell_text(0, 1, "Fixed"));
1874        assert_eq!(
1875            t.rows[0],
1876            vec!["Fixed".to_string(), "Fixed".into(), "C".into()]
1877        );
1878        assert_eq!(t.cell_at(0, 1).unwrap().text, "Fixed");
1879        assert_eq!(t.cell_at(0, 1).unwrap().col_span, 2);
1880    }
1881
1882    /// The OCR-repair loop (#238): locate a cell by an external box (best
1883    /// IoU), replace its text, and see the fix in the export — the grid is
1884    /// the single source of truth for every serializer.
1885    #[test]
1886    fn bbox_lookup_and_repair_flow_into_exports() {
1887        let mut doc = DoclingDocument::new("t");
1888        doc.push(Node::Table(table()));
1889        assert_eq!(doc.tables().count(), 1);
1890
1891        let t = doc.tables_mut().next().unwrap();
1892        // A slightly-off OCR box still lands on the (1,1) cell.
1893        assert_eq!(t.find_cell_by_bbox([52.0, 11.0, 98.0, 19.0]), Some((1, 1)));
1894        assert_eq!(
1895            t.update_cell_by_bbox([52.0, 11.0, 98.0, 19.0], "125"),
1896            Some((1, 1))
1897        );
1898        assert_eq!(t.cell_text(1, 1), Some("125"));
1899        assert!(doc.export_to_markdown().contains("125"));
1900
1901        // No overlap → no match, nothing changed.
1902        let t = doc.tables_mut().next().unwrap();
1903        assert_eq!(t.find_cell_by_bbox([500.0, 500.0, 600.0, 600.0]), None);
1904    }
1905
1906    #[test]
1907    fn cell_accessors_bound_check_and_geometry_materializes() {
1908        let mut t = table();
1909        assert_eq!(t.cell_text(0, 0), Some("Year"));
1910        assert_eq!(t.cell_text(5, 0), None);
1911        assert!(!t.set_cell_text(0, 9, "x"), "outside the grid");
1912        assert_eq!(t.cell_bbox(1, 0), Some([0.0, 10.0, 50.0, 20.0]));
1913
1914        // A geometry-less table materializes its box grid on first set.
1915        let mut plain = Table {
1916            rows: vec![vec!["a".into(), "b".into()]],
1917            ..Default::default()
1918        };
1919        assert_eq!(plain.cell_bbox(0, 1), None);
1920        assert!(!plain.set_cell_bbox(0, 5, [0.0; 4]), "outside the grid");
1921        assert!(plain.set_cell_bbox(0, 1, [1.0, 2.0, 3.0, 4.0]));
1922        assert_eq!(plain.cell_bbox(0, 1), Some([1.0, 2.0, 3.0, 4.0]));
1923        assert_eq!(plain.find_cell_by_bbox([1.5, 2.5, 2.5, 3.5]), Some((0, 1)));
1924    }
1925}