Skip to main content

docling_core/
markdown.rs

1//! Markdown serializer for [`DoclingDocument`].
2
3use crate::document::{
4    ContentLayer, ContentLayers, DoclingDocument, MarkdownExportOptions, Node, Table,
5};
6
7/// What docling's Markdown serializer writes for an item it has no component
8/// for — a `KeyValueItem` (the XBRL fact graph) is the one such item a backend
9/// produces.
10const MISSING_KEY_VALUE_ITEM: &str = "<!-- missing-key-value-item -->";
11
12/// How pictures are rendered (mirrors docling-core's `ImageRefMode`).
13#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
14pub enum ImageMode {
15    /// `<!-- image -->` (docling's default, and the only mode without image data).
16    #[default]
17    Placeholder,
18    /// `![Image](data:<mime>;base64,…)` — self-contained.
19    Embedded,
20    /// `![Image](<artifacts>/image_NNNNNN.<ext>)`; the bytes are returned for the
21    /// caller to write.
22    Referenced,
23}
24
25/// Serializer state threaded through the render walk.
26struct Ctx {
27    strict: bool,
28    /// Render pictures' alt text (#676): strict Markdown, or the document's
29    /// `picture_alt_text`.
30    alt_text: bool,
31    /// Emit compact `| a | b |` tables instead of the padded GitHub serializer.
32    compact_tables: bool,
33    images: ImageMode,
34    artifacts_dir: String,
35    /// (relative path, bytes) for each referenced image — written by the caller.
36    artifacts: Vec<(String, Vec<u8>)>,
37    pic_index: usize,
38    /// Rendering the block content of a rich table cell (docling-core 2.94's
39    /// `in_table_cell`, docling-core#540): a heading has no valid Markdown
40    /// form inside a table, so it renders as plain text without `#` markers.
41    in_table_cell: bool,
42    /// docling-core's `MarkdownParams.page_break_placeholder`: the text that
43    /// separates two pages ([`DoclingDocument::page_break_placeholder`]).
44    /// `None` omits page breaks, docling's default.
45    page_break: Option<String>,
46    /// A page boundary has been crossed since the last rendered block, so the
47    /// next block is preceded by the placeholder. docling yields its
48    /// `_PageBreakNode` between two *items* whose `prov.page_no` differ, so a
49    /// boundary before the first block or after the last one emits nothing,
50    /// and a run of empty pages collapses into a single break.
51    pending_page_break: bool,
52    /// Whether any block has been rendered yet — for a streamer, across every
53    /// earlier push too — which is what makes a boundary a *pending* break.
54    emitted_any: bool,
55    /// The content layers rendered ([`MarkdownExportOptions::layers`], #599).
56    layers: ContentLayers,
57    /// The layer the items being rendered sit on: `None` (body) at the
58    /// root, the group's or wrapper's layer inside a non-body group or a
59    /// [`Node::Furniture`] — what the layer gate compares against the set,
60    /// as every item of a hidden sheet carries that sheet's layer upstream.
61    current_layer: Option<ContentLayer>,
62    /// Render a picture's nested text items ([`MarkdownExportOptions::traverse_pictures`]).
63    traverse_pictures: bool,
64    /// Keep the backends' HTML-entity escaping (`&amp;` …) in the output;
65    /// off, it is undone ([`MarkdownExportOptions::escape_html`]).
66    escape_html: bool,
67    /// Keep the backends' `\_` escaping; off, it is undone.
68    escape_underscores: bool,
69    /// What a picture prints as without image data.
70    image_placeholder: String,
71    /// The plain-text export ([`MarkdownExportOptions::plain_text`], #613).
72    plain: bool,
73}
74
75impl Ctx {
76    /// Serializer state for `options` (the page-break setting is the
77    /// document's, the strictness the caller's).
78    fn new(doc: &DoclingDocument, strict: bool, options: &MarkdownExportOptions) -> Self {
79        Ctx {
80            strict,
81            alt_text: strict || doc.picture_alt_text,
82            compact_tables: doc.compact_tables,
83            images: options.image_mode,
84            artifacts_dir: options.artifacts_dir.clone(),
85            artifacts: Vec::new(),
86            pic_index: 0,
87            in_table_cell: false,
88            page_break: doc.page_break_placeholder.clone(),
89            pending_page_break: false,
90            emitted_any: false,
91            layers: options.layers,
92            current_layer: None,
93            traverse_pictures: options.traverse_pictures,
94            escape_html: options.escape_html,
95            escape_underscores: options.escape_underscores,
96            image_placeholder: options.image_placeholder.clone(),
97            plain: options.plain_text,
98        }
99    }
100
101    /// Whether an item on the layer being rendered is in the chosen set.
102    fn layer_visible(&self) -> bool {
103        self.layers.contains(self.current_layer)
104    }
105
106    /// The backends escape inline text for Markdown when they build the
107    /// nodes (`&` → `&amp;`, `_` → `\_`, what docling-core's `post_process`
108    /// does at serialization time); an export that turns an escaping off
109    /// undoes it here, the way the JSON export recovers the raw text. Code,
110    /// formulas and table cells never pass through — upstream leaves those
111    /// unescaped too.
112    fn unescape(&self, text: &str) -> String {
113        let mut out = std::borrow::Cow::Borrowed(text);
114        if !self.escape_html
115            && (out.contains("&amp;") || out.contains("&lt;") || out.contains("&gt;"))
116        {
117            out = std::borrow::Cow::Owned(
118                out.replace("&lt;", "<")
119                    .replace("&gt;", ">")
120                    .replace("&amp;", "&"),
121            );
122        }
123        if !self.escape_underscores && out.contains("\\_") {
124            out = std::borrow::Cow::Owned(out.replace("\\_", "_"));
125        }
126        out.into_owned()
127    }
128
129    /// A text item's inline text: the strict-mode cleanup, then the
130    /// escaping the options turn off undone.
131    fn text(&self, text: &str) -> String {
132        let text = strict_text(text, self.strict);
133        if self.plain {
134            self.unescape(&plain_inline(&self.drop_image_markers(&text)))
135        } else {
136            self.unescape(&text)
137        }
138    }
139
140    /// A caption's text (the backends escape it, but strict mode leaves it
141    /// alone): the escaping the options turn off undone, and, for the plain
142    /// export, its inline markup dropped.
143    fn caption(&self, text: &str) -> String {
144        if self.plain {
145            self.unescape(&plain_inline(text))
146        } else {
147            self.unescape(text)
148        }
149    }
150
151    /// docling-core's `_md_line_breaks` for the Markdown export; the plain
152    /// export's `PlainTextTextSerializer` keeps the text's own newlines.
153    fn breaks(&self, text: &str) -> String {
154        if self.plain {
155            text.to_string()
156        } else {
157            md_line_breaks(text)
158        }
159    }
160
161    /// A table for the plain export: a rich cell's text is its Markdown
162    /// serialization in our model (bold runs, links, hard line breaks),
163    /// where upstream serializes the cell with the plain serializer — so
164    /// the markup goes before the grid is laid out, which also lets a
165    /// once-bold number right-align like a plain one. A simple cell holds
166    /// raw text and passes through unchanged.
167    fn plain_table(&self, table: &Table) -> Table {
168        let mut plain = table.clone();
169        for cell in plain.rows.iter_mut().flatten() {
170            if cell.contains(['*', '~', '`', '[', '\n', '<']) {
171                let text = self.drop_image_markers(&strip_hard_breaks(cell));
172                *cell = plain_inline(&text);
173            }
174        }
175        plain
176    }
177
178    /// Pictures some backends fold into an item's text (an HTML `<img>`
179    /// inside a `<li>`, a LaTeX figure in a paragraph) arrive as baked
180    /// `<!-- image -->` lines — docling's picture *children* of the item,
181    /// which its serializer prints with the active image placeholder. The
182    /// plain export's placeholder is empty, so such a line goes, as a
183    /// picture item would.
184    fn drop_image_markers(&self, text: &str) -> String {
185        const MARKER: &str = "<!-- image -->";
186        if !text.contains(MARKER) && !text.contains("```") {
187            return text.to_string();
188        }
189        // Block by block (`\n\n`, the serializer's part delimiter): a block
190        // left empty goes with its delimiter, as docling joins only the parts
191        // that carry text.
192        text.split("\n\n")
193            .filter_map(|block| {
194                let lines: Vec<String> = block
195                    .split('\n')
196                    .filter_map(|line| {
197                        // A folded code block's fences go too: the plain
198                        // export prints code unfenced.
199                        if line.trim() == MARKER || is_fence_line(line.trim()) {
200                            return None;
201                        }
202                        Some(line.replace(MARKER, &self.image_placeholder))
203                    })
204                    .collect();
205                (!lines.is_empty()).then(|| lines.join("\n"))
206            })
207            .collect::<Vec<_>>()
208            .join("\n\n")
209    }
210}
211
212/// Render a document to a Markdown string (pictures as placeholders).
213///
214/// `strict` selects the serializer-level behaviours that differ between
215/// docling-legacy output and cleaner Markdown — currently the code-fence
216/// language (legacy drops it, strict keeps it).
217pub fn to_markdown(doc: &DoclingDocument, strict: bool) -> String {
218    to_markdown_images(doc, strict, ImageMode::Placeholder, "artifacts").0
219}
220
221/// Render to Markdown with an explicit picture [`ImageMode`]. Returns the
222/// Markdown and, for [`ImageMode::Referenced`], the `(path, bytes)` of each image
223/// the caller should write (relative to the Markdown file).
224pub fn to_markdown_images(
225    doc: &DoclingDocument,
226    strict: bool,
227    images: ImageMode,
228    artifacts_dir: &str,
229) -> (String, Vec<(String, Vec<u8>)>) {
230    to_markdown_with_options(
231        doc,
232        strict,
233        &MarkdownExportOptions {
234            image_mode: images,
235            artifacts_dir: artifacts_dir.to_string(),
236            ..MarkdownExportOptions::default()
237        },
238    )
239}
240
241/// Render to Markdown per `options` ([`MarkdownExportOptions`], #599):
242/// content layers, picture traversal, escaping, the image placeholder and
243/// the image mode. Returns the Markdown and the referenced-image artifacts.
244pub fn to_markdown_with_options(
245    doc: &DoclingDocument,
246    strict: bool,
247    options: &MarkdownExportOptions,
248) -> (String, Vec<(String, Vec<u8>)>) {
249    let mut ctx = Ctx::new(doc, strict, options);
250    let mut blocks: Vec<String> = Vec::new();
251    render(&doc.nodes, &mut blocks, &mut ctx);
252    let mut body = blocks.join("\n\n");
253    // Strict mode only: turn recovered source hyperlinks into Markdown links.
254    // docling's standard pipeline drops them, so doing this in legacy mode would
255    // diverge from docling — hence strict-only, leaving conformance output intact.
256    if strict && !options.plain_text && !doc.links.is_empty() {
257        body = apply_links(&body, &doc.links);
258    }
259    // The YAML front matter (#679) opens the document when its output mode
260    // asks for it; never in the plain-text export.
261    let front = if doc.metadata_output.front_matter() && !options.plain_text {
262        doc.metadata.to_front_matter()
263    } else {
264        String::new()
265    };
266    let md = match (front.is_empty(), body.is_empty()) {
267        (true, true) => String::new(),
268        (true, false) => format!("{body}\n"),
269        (false, true) => front,
270        (false, false) => format!("{front}\n{body}\n"),
271    };
272    (md, ctx.artifacts)
273}
274
275/// Render the block content of a *rich table cell* to Markdown — what
276/// docling-core's table serializer does for a `RichTableCell`
277/// (`doc_serializer.serialize(item, in_table_cell=True)`): the cell's
278/// paragraphs, lists and flattened nested tables render as in a document, but a
279/// heading loses its `#` markers (docling-core#540 — the Markdown spec has no
280/// headings inside tables). Pictures stay placeholders. The caller flattens the
281/// result into its cell text; the table serializer later turns the newlines
282/// into spaces.
283pub fn to_markdown_table_cell(doc: &DoclingDocument, strict: bool) -> String {
284    let mut ctx = Ctx::new(doc, strict, &MarkdownExportOptions::default());
285    ctx.in_table_cell = true;
286    ctx.artifacts_dir = String::new();
287    // A rich cell is one page's content; its sub-document carries no page
288    // boundaries and docling's `_iterate_items` runs the page-break scan
289    // over the document root only.
290    ctx.page_break = None;
291    let mut blocks: Vec<String> = Vec::new();
292    render(&doc.nodes, &mut blocks, &mut ctx);
293    blocks.join("\n\n")
294}
295
296/// Wrap each recovered link's anchor text in Markdown `[anchor](href)`. Anchors
297/// arrive cleaned (curly quotes/dashes already normalized) but un-escaped, so we
298/// match against the body's HTML-escaped (`&`/`<`/`>`) form, the way prose nodes
299/// were serialized. Links are consumed in document order from a moving cursor, so
300/// a repeated anchor (e.g. two "issues") links its successive occurrences rather
301/// than all pointing at the first. An anchor that can't be located is skipped
302/// (its text may have been split across a line wrap or table cell).
303fn apply_links(body: &str, links: &[(String, String)]) -> String {
304    let mut out = body.to_string();
305    let mut cursor = 0usize;
306    for (anchor, href) in links {
307        let anchor = anchor
308            .replace('&', "&amp;")
309            .replace('<', "&lt;")
310            .replace('>', "&gt;");
311        if anchor.is_empty() {
312            continue;
313        }
314        if let Some(rel) = out[cursor..].find(&anchor) {
315            let at = cursor + rel;
316            // Don't relink inside an already-emitted `](` Markdown link target.
317            // An unsafe destination (#860) leaves the anchor as prose.
318            let replacement = crate::hyperlink::markdown_link(&anchor, href);
319            out.replace_range(at..at + anchor.len(), &replacement);
320            cursor = at + replacement.len();
321        }
322    }
323    out
324}
325
326/// Like [`apply_links`] but over a single chunk, consuming from a shared queue so
327/// the same `[anchor](href)` rewriting can be applied incrementally as Markdown is
328/// streamed out. Each queued link is matched (in document order) against `chunk`
329/// and rewritten in place; a link whose anchor is not in this chunk is carried
330/// forward in the queue for a later chunk. Anchors are recovered in document
331/// order and a chunk is always a contiguous run of whole blocks, so this
332/// reproduces [`apply_links`]' single moving cursor: the link lands in whichever
333/// chunk contains its anchor, identically to the buffered path. (A link whose
334/// anchor never appears is carried to the end and dropped — the same no-op
335/// `apply_links` performs for an unlocatable anchor.)
336fn apply_links_chunk(chunk: &str, queue: &mut Vec<(String, String)>) -> String {
337    let mut out = chunk.to_string();
338    let mut cursor = 0usize;
339    let mut carried: Vec<(String, String)> = Vec::new();
340    for (anchor_raw, href) in std::mem::take(queue) {
341        let anchor = anchor_raw
342            .replace('&', "&amp;")
343            .replace('<', "&lt;")
344            .replace('>', "&gt;");
345        if anchor.is_empty() {
346            continue;
347        }
348        if let Some(rel) = out[cursor..].find(&anchor) {
349            let at = cursor + rel;
350            let replacement = crate::hyperlink::markdown_link(&anchor, &href);
351            out.replace_range(at..at + anchor.len(), &replacement);
352            cursor = at + replacement.len();
353        } else {
354            // Not in this chunk; try again when its block is flushed.
355            carried.push((anchor_raw, href));
356        }
357    }
358    *queue = carried;
359    out
360}
361
362/// Incremental Markdown serializer: feed finalized, in-document-order batches of
363/// [`Node`]s and receive Markdown chunks whose concatenation is **byte-identical**
364/// to [`to_markdown_images`] over the same nodes. This is the streaming
365/// counterpart of the buffered serializer — used to emit a document's Markdown in
366/// chunks (e.g. page by page, as the parallel PDF pipeline finishes pages) instead
367/// of building the whole string up front.
368///
369/// [`ImageMode::Placeholder`] and [`ImageMode::Embedded`] render inline.
370/// [`ImageMode::Referenced`] additionally hands each picture's bytes out through
371/// [`take_artifacts`](Self::take_artifacts) — construct with
372/// [`with_artifacts`](Self::with_artifacts) and drain after every push so the
373/// bytes can be written to disk as pages finish instead of accumulating for the
374/// whole document (issue #80's memory-bounded image handling).
375///
376/// Each [`push`](Self::push) must contain whole blocks in reading order: a caller
377/// must not split a run of list items across two pushes (the run would render as
378/// two separate lists). Finalized PDF page batches already satisfy this.
379pub struct MarkdownStreamer {
380    strict: bool,
381    images: ImageMode,
382    compact_tables: bool,
383    /// [`DoclingDocument::picture_alt_text`] (#676).
384    picture_alt_text: bool,
385    /// The YAML front matter (#679) still to be written, ahead of the first
386    /// chunk — or alone, from [`finish`](Self::finish), when nothing else
387    /// comes.
388    front_matter: Option<String>,
389    /// Whether any non-empty chunk has been emitted yet (drives `\n\n` joins and
390    /// the trailing newline).
391    emitted_any: bool,
392    /// Recovered links not yet placed (strict mode), consumed in document order.
393    links: Vec<(String, String)>,
394    /// Referenced mode: the link prefix, the not-yet-drained `(path, bytes)`
395    /// artifacts, and the running image number (continues across pushes so the
396    /// stream matches the buffered serializer's `image_000000…` numbering).
397    artifacts_dir: String,
398    artifacts: Vec<(String, Vec<u8>)>,
399    pic_index: usize,
400    /// [`DoclingDocument::page_break_placeholder`] and the boundary carried
401    /// over from the previous push (a page batch opens with its page marker,
402    /// so the break it implies is paid by that batch's first block).
403    page_break: Option<String>,
404    pending_page_break: bool,
405    /// Whether an earlier push rendered an *item* — the page-break scan's
406    /// state ([`Ctx`]'s `emitted_any`). It differs from `emitted_any` (text
407    /// written) only when every block of the earlier pushes was empty and
408    /// dropped (#605): a page break before the next item is still owed then,
409    /// exactly as in the buffered export.
410    items_emitted: bool,
411    /// A picture a push ended on, in the placeholder mode: whether its
412    /// marker prints depends on the item after it (#858, a `mermaid` code
413    /// item takes its place), which the next push brings — it joins that
414    /// push, or [`finish`](Self::finish) renders it.
415    held: Option<Node>,
416    /// The export options beyond the image mode (#599): layers, picture
417    /// traversal, escaping, the placeholder — [`with_export_options`](Self::with_export_options).
418    layers: ContentLayers,
419    traverse_pictures: bool,
420    escape_html: bool,
421    escape_underscores: bool,
422    image_placeholder: String,
423    plain: bool,
424}
425
426impl MarkdownStreamer {
427    /// Create a streamer. `compact_tables` mirrors [`DoclingDocument::compact_tables`].
428    /// For [`ImageMode::Referenced`] use [`with_artifacts`](Self::with_artifacts).
429    pub fn new(strict: bool, images: ImageMode, compact_tables: bool) -> Self {
430        debug_assert!(
431            images != ImageMode::Referenced,
432            "referenced image mode needs an artifacts dir; use with_artifacts"
433        );
434        Self::with_artifacts(strict, images, compact_tables, "artifacts")
435    }
436
437    /// Like [`new`](Self::new) but with the artifacts link prefix, allowing
438    /// [`ImageMode::Referenced`]: pictures render as
439    /// `![Image](<artifacts_dir>/image_NNNNNN.<ext>)` and each push's image
440    /// bytes wait in [`take_artifacts`](Self::take_artifacts) for the caller to
441    /// write. The concatenated chunks and the artifact list match the buffered
442    /// [`to_markdown_images`] byte-for-byte.
443    pub fn with_artifacts(
444        strict: bool,
445        images: ImageMode,
446        compact_tables: bool,
447        artifacts_dir: &str,
448    ) -> Self {
449        Self {
450            strict,
451            images,
452            compact_tables,
453            picture_alt_text: false,
454            front_matter: None,
455            emitted_any: false,
456            links: Vec::new(),
457            artifacts_dir: artifacts_dir.to_string(),
458            artifacts: Vec::new(),
459            pic_index: 0,
460            page_break: None,
461            pending_page_break: false,
462            items_emitted: false,
463            held: None,
464            layers: ContentLayers::BODY,
465            traverse_pictures: false,
466            escape_html: true,
467            escape_underscores: true,
468            image_placeholder: "<!-- image -->".to_string(),
469            plain: false,
470        }
471    }
472
473    /// Take every setting of `options` ([`MarkdownExportOptions`], #599):
474    /// the image mode and artifacts directory the constructors took, plus the
475    /// content layers, picture traversal, escaping and image placeholder.
476    /// The concatenated chunks match the buffered
477    /// [`to_markdown_with_options`] byte-for-byte. Set before the first
478    /// [`push`](Self::push).
479    pub fn with_export_options(mut self, options: &MarkdownExportOptions) -> Self {
480        self.images = options.image_mode;
481        self.artifacts_dir = options.artifacts_dir.clone();
482        self.layers = options.layers;
483        self.traverse_pictures = options.traverse_pictures;
484        self.escape_html = options.escape_html;
485        self.escape_underscores = options.escape_underscores;
486        self.image_placeholder = options.image_placeholder.clone();
487        self.plain = options.plain_text;
488        self
489    }
490
491    /// Insert `placeholder` between pages, mirroring
492    /// [`DoclingDocument::page_break_placeholder`] for the buffered path (the
493    /// concatenated chunks stay byte-identical to it). `None` — the default —
494    /// omits page breaks. Set before the first [`push`](Self::push).
495    pub fn with_page_break_placeholder(mut self, placeholder: Option<String>) -> Self {
496        self.page_break = placeholder;
497        self
498    }
499
500    /// Render pictures' alt text (#676) — [`DoclingDocument::picture_alt_text`]
501    /// for the stream; strict Markdown renders it regardless. Set before the
502    /// first [`push`](Self::push).
503    pub fn with_picture_alt_text(mut self, on: bool) -> Self {
504        self.picture_alt_text = on;
505        self
506    }
507
508    /// Open the stream with the YAML front matter of `metadata` (#679) —
509    /// what the buffered export writes for a document whose
510    /// [`DoclingDocument::metadata_output`] is `Frontmatter`. Empty
511    /// metadata writes nothing; the plain-text export never writes it.
512    pub fn with_metadata(mut self, metadata: &crate::metadata::DocumentMetadata) -> Self {
513        self.front_matter = (!self.plain)
514            .then(|| metadata.to_front_matter())
515            .filter(|f| !f.is_empty());
516        self
517    }
518
519    /// The `(relative path, bytes)` of images rendered by pushes since the last
520    /// drain ([`ImageMode::Referenced`] only — empty otherwise). Paths are
521    /// relative to the Markdown file, i.e. they start with the configured
522    /// artifacts dir.
523    pub fn take_artifacts(&mut self) -> Vec<(String, Vec<u8>)> {
524        std::mem::take(&mut self.artifacts)
525    }
526
527    /// Render one finalized batch of nodes (plus any links recovered from the same
528    /// span, in document order) into the next Markdown chunk. Returns an empty
529    /// string when the batch produces no output (e.g. empty tables/pictures), in
530    /// which case nothing should be written.
531    pub fn push(&mut self, nodes: &[Node], links: &[(String, String)]) -> String {
532        self.push_holding(nodes, links, true)
533    }
534
535    /// [`push`](Self::push); with `hold`, a picture the batch ends on is
536    /// held back for the next push (`finish` renders without holding).
537    fn push_holding(&mut self, nodes: &[Node], links: &[(String, String)], hold: bool) -> String {
538        self.links.extend(links.iter().cloned());
539        // A picture held back from the last push leads this one; a picture
540        // this push ends on is held back in turn (placeholder mode only —
541        // the one in which the next item can change what it prints).
542        let images = self.images;
543        let ends_on_picture = |nodes: &[Node]| {
544            matches!(images, ImageMode::Placeholder)
545                && matches!(nodes.last(), Some(Node::Picture { .. }))
546        };
547        let mut owned: Vec<Node> = Vec::new();
548        let mut nodes = nodes;
549        if self.held.is_some() || (hold && ends_on_picture(nodes)) {
550            owned.extend(self.held.take());
551            owned.extend(nodes.iter().cloned());
552            if hold && ends_on_picture(&owned) {
553                self.held = owned.pop();
554            }
555            nodes = &owned;
556        }
557        let mut ctx = Ctx {
558            strict: self.strict,
559            alt_text: self.strict || self.picture_alt_text,
560            compact_tables: self.compact_tables,
561            images: self.images,
562            artifacts_dir: std::mem::take(&mut self.artifacts_dir),
563            artifacts: std::mem::take(&mut self.artifacts),
564            pic_index: self.pic_index,
565            in_table_cell: false,
566            page_break: std::mem::take(&mut self.page_break),
567            pending_page_break: self.pending_page_break,
568            emitted_any: self.items_emitted,
569            layers: self.layers,
570            current_layer: None,
571            traverse_pictures: self.traverse_pictures,
572            escape_html: self.escape_html,
573            escape_underscores: self.escape_underscores,
574            image_placeholder: std::mem::take(&mut self.image_placeholder),
575            plain: self.plain,
576        };
577        let mut blocks: Vec<String> = Vec::new();
578        render(nodes, &mut blocks, &mut ctx);
579        self.image_placeholder = std::mem::take(&mut ctx.image_placeholder);
580        self.artifacts_dir = std::mem::take(&mut ctx.artifacts_dir);
581        self.artifacts = std::mem::take(&mut ctx.artifacts);
582        self.pic_index = ctx.pic_index;
583        self.page_break = std::mem::take(&mut ctx.page_break);
584        self.pending_page_break = ctx.pending_page_break;
585        self.items_emitted = ctx.emitted_any;
586        if blocks.is_empty() {
587            return String::new();
588        }
589        let mut body = blocks.join("\n\n");
590        if self.strict && !self.plain && !self.links.is_empty() {
591            body = apply_links_chunk(&body, &mut self.links);
592        }
593        let chunk = if let Some(front) = self.front_matter.take() {
594            format!("{front}\n{body}")
595        } else if self.emitted_any {
596            format!("\n\n{body}")
597        } else {
598            body
599        };
600        self.emitted_any = true;
601        chunk
602    }
603
604    /// Emit the trailing newline that finishes the document (empty if no content
605    /// was produced). Call exactly once, after the final [`push`](Self::push).
606    pub fn finish(mut self) -> String {
607        let mut out = String::new();
608        if self.held.is_some() {
609            out.push_str(&self.push_holding(&[], &[], false));
610        }
611        if let Some(front) = self.front_matter {
612            out.push_str(&front);
613        } else if self.emitted_any {
614            out.push('\n');
615        }
616        out
617    }
618}
619
620/// In `strict` mode, rewrite inline text for readability rather than byte-for-byte
621/// docling fidelity: undo the legacy `\_` underscore escaping, and tighten stray
622/// spaces around punctuation (`[ 37 , 36 ]` → `[37, 36]`, `( x )` → `(x)`). This
623/// cleans up both the PDF backend's glyph-split spacing and the space the legacy
624/// emphasis serialization leaves before punctuation (`*a* ,` → `*a*,`).
625/// Legacy/default output keeps docling's spacing untouched. Only inline text
626/// nodes pass through here — code blocks and table cells are left alone.
627fn strict_text(text: &str, strict: bool) -> String {
628    if !strict {
629        return text.to_string();
630    }
631    // A list item's leading GFM task box (`[ ] todo`, a docling-JSON check
632    // list item, #1033) is markup, not a stray space inside brackets.
633    if let Some(rest) = text.strip_prefix("[ ] ") {
634        return format!("[ ] {}", strict_text(rest, strict));
635    }
636    text.replace("\\_", "_")
637        .replace(" ,", ",")
638        .replace(" .", ".")
639        .replace(" ;", ";")
640        .replace(" )", ")")
641        .replace("( ", "(")
642        .replace(" ]", "]")
643        .replace("[ ", "[")
644}
645
646/// The longest run of consecutive backticks in `text` (docling-core
647/// 2.103.1's `_longest_backtick_run`, #859).
648pub fn longest_backtick_run(text: &str) -> usize {
649    let (mut best, mut run) = (0, 0);
650    for c in text.chars() {
651        if c == '`' {
652            run += 1;
653            best = best.max(run);
654        } else {
655            run = 0;
656        }
657    }
658    best
659}
660
661/// `text` as a Markdown code span no backtick run inside can close
662/// (docling-core's `_code_span`, #859): one backtick more than the longest
663/// run in it, and a space on both sides when the text starts or ends with
664/// a backtick — the pad CommonMark strips again — so `` a`b `` is
665/// ``` ``a`b`` ``` and `` `x `` is ``` `` `x `` ```.
666pub fn code_span(text: &str) -> String {
667    let ticks = "`".repeat(longest_backtick_run(text) + 1);
668    let pad = if text.starts_with('`') || text.ends_with('`') {
669        " "
670    } else {
671        ""
672    };
673    format!("{ticks}{pad}{text}{pad}{ticks}")
674}
675
676/// A fenced code block whose fence out-lengths every backtick run in `body`
677/// (docling-core's `_code_block`, #859): three backticks, or one more than
678/// the longest run inside, so a body quoting a ``` fence cannot close the
679/// block early. `language` rides on the opening fence (empty for none).
680pub fn code_fence(language: &str, body: &str) -> String {
681    let fence = "`".repeat(longest_backtick_run(body).max(2) + 1);
682    format!("{fence}{language}\n{body}\n{fence}")
683}
684
685/// The code span (or flattened fence) opening at `chars[i]`, a run of
686/// backticks: `(content start, content end, index after the closing run)`.
687/// The closing run is the first later run of exactly the same length — a
688/// run of another length is literal inside the span, as in CommonMark. A
689/// span of two or more backticks sheds the one-space pad [`code_span`]
690/// adds; a single-backtick span keeps its content as it stands, the shape
691/// every reader of the baked text relied on.
692pub(crate) fn code_span_bounds(chars: &[char], i: usize) -> Option<(usize, usize, usize)> {
693    let n = chars[i..].iter().take_while(|&&c| c == '`').count();
694    if n == 0 {
695        return None;
696    }
697    let mut k = i + n;
698    while k < chars.len() {
699        if chars[k] != '`' {
700            k += 1;
701            continue;
702        }
703        let run = chars[k..].iter().take_while(|&&c| c == '`').count();
704        if run == n {
705            let (mut s, mut e) = (i + n, k);
706            if n > 1
707                && e - s >= 2
708                && chars[s] == ' '
709                && chars[e - 1] == ' '
710                && chars[s..e].iter().any(|&c| c != ' ')
711            {
712                s += 1;
713                e -= 1;
714            }
715            return Some((s, e, k + run));
716        }
717        k += run;
718    }
719    None
720}
721
722/// A line that is a code fence: three or more backticks and nothing else.
723fn is_fence_line(line: &str) -> bool {
724    line.len() >= 3 && line.bytes().all(|b| b == b'`')
725}
726
727/// The plain export's inline text (#613): the Markdown markers docling-core's
728/// `PlainTextDocSerializer` never writes — `serialize_bold` / `_italic` /
729/// `_strikethrough` return the text, `serialize_hyperlink` the label, and
730/// `format_code_blocks=False` drops inline code's backticks. The backends
731/// bake those markers into an item's Markdown text (`***x***`, `**x**`,
732/// `*x*`, `~~x~~`, `` `x` ``, `[label](url)`, the set DocLang's run parser
733/// reads too), so they are taken out here, nested ones included. A marker
734/// counts only when it closes and its content is tight against both
735/// markers (CommonMark's flanking rule): `2 * 3 * 4` is arithmetic and IBM
736/// i's `*USE … have *OBJMGT` are special values, not emphasis, and stay as
737/// they are — docling's own emphasis around a space (WebVTT's `* *`) stays
738/// literal too. Inline `$…$` formulas pass through untouched.
739pub(crate) fn plain_inline(text: &str) -> String {
740    if !text.contains(['*', '~', '`', '[']) {
741        return text.to_string();
742    }
743    let chars: Vec<char> = text.chars().collect();
744    let mut out = String::with_capacity(text.len());
745    plain_inline_into(&chars, &mut out);
746    out
747}
748
749fn plain_inline_into(chars: &[char], out: &mut String) {
750    // A backslash-escaped marker (`\*`, the RIS backend's pseudonym stars,
751    // #902) closes no span.
752    let find = |open: usize, pat: &[char]| -> Option<usize> {
753        chars
754            .get(open..)?
755            .windows(pat.len())
756            .enumerate()
757            .position(|(k, w)| w == pat && (open + k == 0 || chars[open + k - 1] != '\\'))
758            .map(|p| open + p)
759    };
760    // An emphasis span opening at `i` with marker `pat`: its closing index
761    // when the content is non-empty and tight against both markers.
762    let span = |i: usize, pat: &[char]| -> Option<usize> {
763        if !chars[i..].starts_with(pat) {
764            return None;
765        }
766        let open = i + pat.len();
767        let end = find(open, pat)?;
768        (end > open && !chars[open].is_whitespace() && !chars[end - 1].is_whitespace())
769            .then_some(end)
770    };
771    let mut i = 0;
772    while i < chars.len() {
773        // `\*` is a literal star, which is what the Markdown renders.
774        if chars[i] == '\\' && chars.get(i + 1) == Some(&'*') {
775            out.push('*');
776            i += 2;
777            continue;
778        }
779        let mut matched = false;
780        for pat in [&['*', '*', '*'][..], &['*', '*'], &['~', '~'], &['*']] {
781            if let Some(end) = span(i, pat) {
782                plain_inline_into(&chars[i + pat.len()..end], out);
783                i = end + pat.len();
784                matched = true;
785                break;
786            }
787        }
788        if matched {
789            continue;
790        }
791        // Inline code: content tight against both backticks, as docling
792        // writes it — a backtick opening a quotation (`` `like this’ ``,
793        // JATS prose) stays.
794        if chars[i] == '`' {
795            if let Some((s, e, after)) = code_span_bounds(chars, i).filter(|&(s, e, _)| {
796                e > s && !chars[s].is_whitespace() && !chars[e - 1].is_whitespace()
797            }) {
798                out.extend(&chars[s..e]);
799                i = after;
800                continue;
801            }
802        }
803        // An inline formula is LaTeX, printed as it is — its brackets and
804        // stars are not Markdown.
805        if chars[i] == '$' {
806            if let Some(end) = find(i + 1, &['$']) {
807                out.extend(&chars[i..=end]);
808                i = end + 1;
809                continue;
810            }
811        }
812        // A link: the `]` closing this `[` (brackets nest) directly followed
813        // by `(` — a citation `[23,24]` before a later link is no anchor.
814        if chars[i] == '[' {
815            if let Some(close) = closing_bracket(chars, i) {
816                if chars.get(close + 1) == Some(&'(') {
817                    if let Some(endp) = crate::doclang::link_dest_end(chars, close + 2) {
818                        plain_inline_into(&chars[i + 1..close], out);
819                        i = endp + 1;
820                        continue;
821                    }
822                }
823            }
824        }
825        // A run of the same marker that opened nothing stays literal as a
826        // whole, so `***` before a lone `*` is not re-read from its middle.
827        let c = chars[i];
828        out.push(c);
829        i += 1;
830        if matches!(c, '*' | '~') {
831            while i < chars.len() && chars[i] == c {
832                out.push(c);
833                i += 1;
834            }
835        }
836    }
837}
838
839/// The index of the `]` matching the `[` at `open`, nested brackets
840/// balanced; `None` when it never closes.
841fn closing_bracket(chars: &[char], open: usize) -> Option<usize> {
842    let mut depth = 0usize;
843    for (k, c) in chars.iter().enumerate().skip(open + 1) {
844        match c {
845            '[' => depth += 1,
846            ']' if depth == 0 => return Some(k),
847            ']' => depth -= 1,
848            _ => {}
849        }
850    }
851    None
852}
853
854/// docling-core 2.92's `_md_line_breaks` (docling-core#721): a single `\n`
855/// inside an item's text becomes a GFM hard line break (`"  \n"`, two trailing
856/// spaces) so renderers honour it; a blank line (`\n\n`) is a paragraph break
857/// and stays as is — the document scope already joins blocks with `\n\n`.
858/// Applied to body text, list items and standalone caption items, never to
859/// code/formulas, nor to the captions a table or picture carries: docling-core's
860/// `serialize_captions` prints those as they are (#769).
861fn md_line_breaks(text: &str) -> String {
862    if !text.contains('\n') {
863        return text.to_string();
864    }
865    text.split("\n\n")
866        .map(|para| para.replace('\n', "  \n"))
867        .collect::<Vec<_>>()
868        .join("\n\n")
869}
870
871/// Undo [`md_line_breaks`] on a rich table cell's flattened Markdown so the
872/// non-Markdown exports (JSON `text`, LaTeX cells) see the cell's raw line
873/// breaks, as docling's do — a rich cell's text is its Markdown serialization
874/// in our model, and the two trailing spaces are a Markdown-only marker.
875pub(crate) fn strip_hard_breaks(text: &str) -> String {
876    if text.contains("  \n") {
877        text.replace("  \n", "\n")
878    } else {
879        text.to_string()
880    }
881}
882
883/// docling-core's `_heading_line_breaks`: a GFM heading cannot span lines, so a
884/// newline inside heading text collapses to a space (`# Hello World`, not a
885/// broken `# Hello\nWorld`).
886fn heading_line_breaks(text: &str) -> String {
887    text.replace('\n', " ")
888}
889
890fn render(nodes: &[Node], blocks: &mut Vec<String>, ctx: &mut Ctx) {
891    let mut i = 0;
892    while i < nodes.len() {
893        let before = blocks.len();
894        match &nodes[i] {
895            // A page boundary: the explicit `PageBreak` (slides, DjVu / DocTags
896            // pages) or the `PageInfo` marker that opens every PDF page and
897            // spreadsheet sheet — a sheet boundary carries both, and the flag
898            // absorbs the pair into one break. docling's `_iterate_items`
899            // yields a `_PageBreakNode` only between two items on different
900            // pages (a group's leading item counts for the group), which is
901            // exactly "a boundary between two rendered blocks": nothing before
902            // the first block, nothing after the last, consecutive boundaries
903            // — empty or furniture-only pages — collapsed into one.
904            Node::PageBreak | Node::PageInfo { .. } => {
905                if ctx.page_break.is_some() && ctx.emitted_any {
906                    ctx.pending_page_break = true;
907                }
908                i += 1;
909            }
910            Node::ListItem { .. } => {
911                let start = i;
912                i += 1;
913                loop {
914                    match nodes.get(i) {
915                        Some(Node::ListItem { .. } | Node::ListText { .. }) => i += 1,
916                        // An empty paragraph between two list items is absorbed
917                        // into the run — docling keeps such a ListGroup
918                        // contiguous rather than splitting it.
919                        Some(Node::Paragraph { text })
920                            if text.is_empty()
921                                && matches!(nodes.get(i + 1), Some(Node::ListItem { .. })) =>
922                        {
923                            i += 1
924                        }
925                        _ => break,
926                    }
927                }
928                render_list_run(&nodes[start..i], blocks, ctx);
929            }
930            other => {
931                let before_item = blocks.len();
932                render_one(other, blocks, ctx);
933                // A picture that is the drawing a `mermaid` code item was
934                // extracted from (#858): in the placeholder mode the
935                // `<!-- image -->` says nothing the graph does not, so the
936                // marker — the last block a picture pushes — goes; an
937                // embedded or referenced image is content and stays.
938                if matches!(other, Node::Picture { .. })
939                    && matches!(ctx.images, ImageMode::Placeholder)
940                    && blocks.len() > before_item
941                    && matches!(
942                        nodes.get(i + 1),
943                        Some(Node::Code { language: Some(l), .. }) if l == "mermaid"
944                    )
945                {
946                    blocks.pop();
947                }
948                i += 1;
949            }
950        }
951        if blocks.len() > before {
952            // docling-core joins only the parts that carry text
953            // (`"\n\n".join(p.text for p in parts if p.text)`, at the
954            // document and every group scope), so an item that renders an
955            // empty block — a picture or chart under `image_placeholder: ""`,
956            // an empty field part or inline group — adds no blank lines
957            // (#605). It still counts as an item for the page-break scan:
958            // upstream's page-break marker sits between the *items* of two
959            // pages and is never empty itself, so the placeholder below still
960            // goes in (an empty placeholder keeps its doubled delimiter).
961            let kept: Vec<String> = blocks.drain(before..).filter(|b| !b.is_empty()).collect();
962            blocks.extend(kept);
963            if ctx.pending_page_break {
964                // The placeholder is a block of its own, joined by the document
965                // delimiter like docling's `_PageBreakSerResult` part — an
966                // empty placeholder therefore leaves the doubled `\n\n`
967                // upstream leaves too.
968                if let Some(placeholder) = &ctx.page_break {
969                    blocks.insert(before, placeholder.clone());
970                }
971                ctx.pending_page_break = false;
972            }
973            ctx.emitted_any = true;
974        }
975    }
976}
977
978/// Render a contiguous run of list items.
979///
980/// Ordered items use their explicit `number`. A new sibling list (marked by
981/// `first_in_list`) at the same depth is separated by a blank line, matching
982/// docling-core's serializer.
983fn render_list_run(items: &[Node], blocks: &mut Vec<String>, ctx: &Ctx) {
984    let mut lines: Vec<String> = Vec::new();
985    // Whether a top-level item has been rendered yet — a fresh-list flag on
986    // the very first item opens nothing.
987    let mut any_top = false;
988
989    for item in items {
990        if let Node::ListText { level, text, glue } = item {
991            let text = ctx.text(text);
992            match lines.last_mut() {
993                Some(last) if *glue => last.push_str(&text),
994                _ => lines.push(format!("{}{text}", "    ".repeat(*level as usize))),
995            }
996            continue;
997        }
998        let Node::ListItem {
999            ordered,
1000            number,
1001            first_in_list,
1002            text,
1003            level,
1004            marker: orig_marker,
1005            location: _,
1006            dclx: _,
1007            split: _,
1008            href: _,
1009            layer,
1010        } = item
1011        else {
1012            continue;
1013        };
1014        // docling's content-layer filtering: an item renders when its layer
1015        // — its own, else the layer of the group it sits in — is in the set
1016        // (body only by default, so a furniture list item is omitted).
1017        if !ctx.layers.contains(layer.or(ctx.current_layer)) {
1018            continue;
1019        }
1020        let level = *level as usize;
1021
1022        // A new sibling list at the top level gets a blank line — and only the
1023        // backend knows where one starts (`first_in_list`: Word's `numId`
1024        // changing, an HTML `<ul>` closing, a Markdown bullet switching
1025        // `-`→`*`). The serializer used to guess it from a kind flip or a
1026        // number gap as well, which split lists docling keeps whole (an
1027        // AsciiDoc `1.` … `5.`, mixed `*`/`1.` markers) — #385. Only at the
1028        // top level: nested sibling groups are children of a list item, and
1029        // docling joins an item's children without blank lines.
1030        if level == 0 {
1031            if any_top && *first_in_list {
1032                lines.push(String::new());
1033            }
1034            any_top = true;
1035        }
1036
1037        let indent = "    ".repeat(level);
1038        lines.push(format!(
1039            "{indent}{} {}",
1040            list_item_marker(orig_marker.as_deref().unwrap_or(""), *ordered, *number),
1041            list_item_text(text, ctx)
1042        ));
1043    }
1044
1045    // A run consisting only of furniture (content-layer-filtered) items yields no
1046    // lines; pushing an empty block here would surface as a stray blank line.
1047    if !lines.is_empty() {
1048        blocks.push(lines.join("\n"));
1049    }
1050}
1051
1052/// docling-core's list item marker (`orig_list_item_marker_mode=AUTO`,
1053/// `ensure_valid_list_item_marker=True`; docling-core 2.100+): a marker that
1054/// is already valid Markdown — `-`, `*`, `+`, or digits and a dot (Python's
1055/// `\d+\.` admits every Unicode decimal digit, so a DOCX `decimalFullWidth`
1056/// `1.` stays as it is, docling#4336) — prints verbatim; any other marker
1057/// holding a letter or digit is informative (`a)`, `①`, `第九条`) and prints
1058/// after a `-`; a markerless item of an enumerated list is numbered by its
1059/// position, and every other item gets a `-`.
1060fn list_item_marker(marker: &str, ordered: bool, number: u64) -> String {
1061    let already_valid = matches!(marker, "-" | "*" | "+")
1062        || marker
1063            .strip_suffix('.')
1064            .is_some_and(|d| !d.is_empty() && d.chars().all(char::is_numeric));
1065    if already_valid {
1066        return marker.to_string();
1067    }
1068    let outer = if ordered && marker.is_empty() {
1069        format!("{number}.")
1070    } else {
1071        "-".to_string()
1072    };
1073    if marker.chars().any(char::is_alphanumeric) {
1074        format!("{outer} {marker}")
1075    } else {
1076        outer
1077    }
1078}
1079
1080/// A list item's Markdown body. The GFM hard-line-break rule (docling-core#721)
1081/// applies to the item's own text; pictures the HTML backend folded into the
1082/// item (`"\n[alt\n]<!-- image -->"` per `<img>` inside the `<li>`) are
1083/// docling's picture *children* of the item, which its serializer prints after
1084/// the item line with plain newlines — so a folded tail keeps its newlines
1085/// unmarked. The tail is recognised structurally: every line after the first is
1086/// an image marker or an alt caption directly followed by one.
1087fn list_item_text(text: &str, ctx: &Ctx) -> String {
1088    let escaped = ctx.text(text);
1089    if ctx.plain {
1090        return escaped;
1091    }
1092    if let Some((own, tail)) = escaped.split_once('\n') {
1093        if is_folded_child_tail(tail) {
1094            return format!("{}\n{tail}", md_line_breaks(own));
1095        }
1096    }
1097    md_line_breaks(&escaped)
1098}
1099
1100/// Whether everything after a list item's own first line is a folded *child*
1101/// block rather than a continuation of the item's text: an image marker
1102/// (optionally preceded by its caption/alt line) or a fenced code block. The
1103/// AsciiDoc backend indents such a block to the item's own depth (as
1104/// docling-core's list serializer does for each part it emits), so a leading
1105/// indent is ignored here.
1106fn is_folded_child_tail(tail: &str) -> bool {
1107    const MARKER: &str = "<!-- image -->";
1108    let mut lines = tail.split('\n').peekable();
1109    let mut any = false;
1110    while let Some(line) = lines.next() {
1111        let line = line.trim_start();
1112        if line == MARKER {
1113            any = true;
1114        } else if is_fence_line(line) {
1115            // Skip the block's body; an unclosed fence is not a folded child.
1116            // The closing fence is the opening one's length (#859).
1117            loop {
1118                match lines.next() {
1119                    Some(l) if l.trim_start() == line => break,
1120                    Some(_) => {}
1121                    None => return false,
1122                }
1123            }
1124            any = true;
1125        } else if lines.next().map(str::trim_start) == Some(MARKER) {
1126            any = true; // an alt caption line, then its marker
1127        } else {
1128            return false;
1129        }
1130    }
1131    any
1132}
1133
1134/// Render one item: docling's content-layer gate first — an item whose layer
1135/// (the group's or wrapper's it sits in, else the body) is outside the set
1136/// renders nothing, while a container still walks its children — then the
1137/// item itself.
1138fn render_one(node: &Node, blocks: &mut Vec<String>, ctx: &mut Ctx) {
1139    match node {
1140        // Containers and layer wrappers decide for their children.
1141        Node::Group { .. }
1142        | Node::Furniture { .. }
1143        | Node::PageFurniture { .. }
1144        | Node::FurnitureText { .. }
1145        | Node::CommentSection { .. }
1146        | Node::PictureChildren(_)
1147        | Node::Commented { .. }
1148        | Node::ScriptText { .. }
1149        | Node::Located { .. }
1150        | Node::Prov { .. }
1151        | Node::Track { .. }
1152        | Node::PageBreak
1153        | Node::PageInfo { .. }
1154        | Node::ProvContinuation { .. }
1155        | Node::DoclangOnly(_) => {}
1156        _ if !ctx.layer_visible() => return,
1157        _ => {}
1158    }
1159    render_item(node, blocks, ctx)
1160}
1161
1162fn render_item(node: &Node, blocks: &mut Vec<String>, ctx: &mut Ctx) {
1163    match node {
1164        Node::Heading { level, text } => {
1165            if ctx.plain {
1166                // `PlainTextTextSerializer`: the heading's text as it is —
1167                // no `#`, its newlines kept.
1168                blocks.push(ctx.text(text));
1169                return;
1170            }
1171            let text = heading_line_breaks(&ctx.text(text));
1172            if ctx.in_table_cell {
1173                // docling-core#540: no `#` markers inside a table cell.
1174                blocks.push(text);
1175            } else {
1176                let hashes = "#".repeat((*level).clamp(1, 6) as usize);
1177                blocks.push(format!("{hashes} {text}"));
1178            }
1179        }
1180        // An empty body paragraph (docling's blank-line text item) contributes
1181        // nothing to Markdown — only DocLang/JSON keep it.
1182        Node::Paragraph { text } if text.is_empty() => {}
1183        Node::Paragraph { text } => blocks.push(ctx.breaks(&ctx.text(text))),
1184        Node::LabeledText { .. } => render_item(&node.labeled_as_paragraph(), blocks, ctx),
1185        // A standalone caption item renders like a text item; its hyperlink
1186        // annotation becomes a Markdown link around the whole caption.
1187        Node::Caption { text, .. } if text.is_empty() => {}
1188        Node::Caption { text, href } => {
1189            let body = ctx.breaks(&ctx.text(text));
1190            blocks.push(match href {
1191                Some(url) if !ctx.plain => crate::hyperlink::markdown_link(&body, url),
1192                _ => body,
1193            });
1194        }
1195        Node::CheckboxItem { checked, text } => {
1196            // docling-core#955: the box needs a space after it, unless the
1197            // text brings its own (a DocLang `<checkbox/> y` reads `" y"`).
1198            let mark = if *checked { "- [x]" } else { "- [ ]" };
1199            let sep = if text.starts_with(' ') { "" } else { " " };
1200            blocks.push(ctx.breaks(&ctx.text(&format!("{mark}{sep}{text}"))));
1201        }
1202        Node::Code {
1203            language,
1204            text,
1205            pretty,
1206            ..
1207        } => {
1208            // Legacy docling never emits a language on the fence; strict keeps
1209            // it. A `mermaid` block (#858, an extraction docling has no
1210            // counterpart for) keeps its tag in either mode: without it the
1211            // graph is a code block no renderer draws.
1212            let lang = match language {
1213                Some(l) if ctx.strict || l == "mermaid" => l.as_str(),
1214                _ => "",
1215            };
1216            // Strict prefers the line-preserving rendering when the backend
1217            // supplied one (PDF); legacy stays on docling's flat `text`.
1218            let body = match pretty {
1219                Some(p) if ctx.strict => p.as_str(),
1220                _ => text.as_str(),
1221            };
1222            // The plain export (`format_code_blocks=False`) prints the code
1223            // as it is.
1224            blocks.push(if ctx.plain {
1225                body.to_string()
1226            } else {
1227                code_fence(lang, body)
1228            });
1229        }
1230        // A decoded display formula renders as docling's `$$…$$`. Without
1231        // decoded text docling-core's `MarkdownTextSerializer` prints the
1232        // placeholder when the item has source text (`orig`: a PDF formula
1233        // region converted without formula enrichment, #1120) and nothing
1234        // when it has neither.
1235        Node::Formula { latex, orig, .. } => {
1236            if !latex.is_empty() {
1237                blocks.push(format!("$${latex}$$"));
1238            } else if !orig.is_empty() {
1239                blocks.push(FORMULA_NOT_DECODED.to_string());
1240            }
1241        }
1242        Node::Table(table) => {
1243            // docling renders a table's caption as a text line before the grid.
1244            // `caption` is already escaped (backend convention), like a paragraph.
1245            if let Some(cap) = &table.caption {
1246                if !cap.is_empty() {
1247                    blocks.push(ctx.text(cap));
1248                }
1249            }
1250            let rendered = if ctx.plain {
1251                render_table(&ctx.plain_table(table), ctx.compact_tables)
1252            } else {
1253                render_table(table, ctx.compact_tables)
1254            };
1255            if !rendered.is_empty() {
1256                blocks.push(rendered);
1257            }
1258            // docling-core#675: the footnotes follow the grid, one paragraph
1259            // each (`serialize_footnotes` with a `\n\n` delimiter).
1260            for note in table.footnotes.iter().filter(|n| !n.is_empty()) {
1261                blocks.push(ctx.text(note));
1262            }
1263        }
1264        // Classification predictions don't affect docling's Markdown output;
1265        // a description (the picture-OCR text, #645) prints between the
1266        // caption and the image placeholder — docling's
1267        // `MarkdownPictureSerializer` order: captions, annotations, image.
1268        // Alt text (#676) is rendered only under strict Markdown or the
1269        // document's `picture_alt_text`, and then where Markdown puts it: as
1270        // the `![alt](…)` of an image line, or — with the placeholder, which
1271        // has no alt slot — as the line a description takes.
1272        Node::Picture {
1273            caption,
1274            image,
1275            description,
1276            ..
1277        } => {
1278            if let Some(cap) = caption {
1279                if !cap.is_empty() {
1280                    blocks.push(ctx.caption(cap));
1281                }
1282            }
1283            let alt = description
1284                .as_ref()
1285                .filter(|d| d.is_alt_text() && ctx.alt_text && !d.text.is_empty());
1286            let marker = picture_marker(image.as_ref(), ctx, alt.map(|d| d.text.as_str()));
1287            // A docling-native `meta.description` (docling#5015) is the
1288            // item's meta, which docling-core's serializer appends *after*
1289            // the item; the legacy-annotation kinds precede the image.
1290            let native = description
1291                .as_ref()
1292                .filter(|d| d.is_docling_meta() && !d.text.is_empty());
1293            if let Some(desc) = description.as_ref().filter(|d| !d.is_docling_meta()) {
1294                let shown = !desc.is_alt_text() || (ctx.alt_text && !marker.starts_with("!["));
1295                if !desc.text.is_empty() && shown {
1296                    blocks.push(ctx.breaks(&ctx.text(&desc.text)));
1297                }
1298            }
1299            blocks.push(marker);
1300            if let Some(desc) = native {
1301                blocks.push(ctx.breaks(&ctx.text(&desc.text)));
1302            }
1303        }
1304        // A chart renders as docling's picture-with-meta markdown: the caption,
1305        // the placeholder, the humanized classification ("line_chart" ->
1306        // "Line chart"), then the chart's data grid as a regular table.
1307        Node::Chart {
1308            kind,
1309            table,
1310            caption,
1311            ..
1312        } => {
1313            if let Some(cap) = caption {
1314                if !cap.is_empty() {
1315                    blocks.push(ctx.caption(cap));
1316                }
1317            }
1318            blocks.push(picture_marker(None, ctx, None));
1319            blocks.push(humanize_label(kind));
1320            let rendered = if ctx.plain {
1321                render_table(&ctx.plain_table(table), false)
1322            } else {
1323                render_table(table, false)
1324            };
1325            if !rendered.is_empty() {
1326                blocks.push(rendered);
1327            }
1328        }
1329        // A DocLang-only node is omitted from Markdown.
1330        Node::DoclangOnly(_) => {}
1331        // A group on a non-body layer (a hidden spreadsheet sheet): its items
1332        // sit on that layer, as every item of such a sheet does upstream — so
1333        // they render exactly when the set includes it (#599), nothing by
1334        // default.
1335        Node::Group {
1336            layer: Some(layer),
1337            children,
1338            ..
1339        } => {
1340            let outer = ctx.current_layer.replace(*layer);
1341            render(children, blocks, ctx);
1342            ctx.current_layer = outer;
1343        }
1344        Node::Group { children, .. } => render(children, blocks, ctx),
1345        Node::FieldRegion { items } => {
1346            // The region container and each field item carry no text of their
1347            // own; docling-core 2.93 (#724) serializes them to nothing (older
1348            // releases emitted a `<!-- missing-text -->` marker for each), so
1349            // only an item's marker/key/value appear, as separate paragraphs.
1350            for item in items {
1351                for part in [&item.marker, &item.key, &item.value].into_iter().flatten() {
1352                    blocks.push(ctx.breaks(&ctx.text(part)));
1353                }
1354            }
1355        }
1356        // docling's Markdown serializer has no component for a `KeyValueItem`
1357        // and writes its fallback placeholder in the item's place.
1358        Node::KeyValueGraph { .. } => blocks.push(MISSING_KEY_VALUE_ITEM.to_string()),
1359        // A rich inline group renders exactly like a paragraph of its Markdown
1360        // text — the structured runs are DocLang-only.
1361        Node::InlineGroup { md_text, .. } => blocks.push(ctx.breaks(&ctx.text(md_text))),
1362        // A plain-text backend dump renders verbatim as a single block.
1363        Node::TextDump(text) => {
1364            if !text.is_empty() {
1365                blocks.push(text.clone());
1366            }
1367        }
1368        // Furniture (page headers/footers, HTML `<title>`, notes) is out of
1369        // the default body-only export, mirroring docling; a set that
1370        // includes its layer renders the wrapped item like a body item (#599).
1371        Node::Furniture { layer, inner } => {
1372            let outer = ctx.current_layer.replace(*layer);
1373            render_one(inner, blocks, ctx);
1374            ctx.current_layer = outer;
1375        }
1376        // A page header/footer or a `.doc` furniture paragraph: upstream's
1377        // `page_header` / `page_footer` / `footnote` text item, a plain
1378        // paragraph when the furniture layer renders.
1379        Node::PageFurniture { text, .. } | Node::FurnitureText { text, .. } => {
1380            if ctx.layers.furniture && !text.is_empty() {
1381                blocks.push(ctx.breaks(&ctx.text(text)));
1382            }
1383        }
1384        // A picture's contained text: docling's Markdown picture serializer
1385        // prints the caption and the image, never the children — unless the
1386        // export traverses pictures, when the item walk yields them after
1387        // the picture and they render as the text items they are (#599).
1388        Node::PictureChildren(children) => {
1389            if ctx.traverse_pictures {
1390                render(children, blocks, ctx);
1391            }
1392        }
1393        // A comment lives in the notes layer — out like other furniture
1394        // unless that layer renders (the note's `[author: …]: text` as a
1395        // paragraph); the annotation on a body item is JSON-only, so render
1396        // the item.
1397        Node::CommentSection { text, .. } => {
1398            if ctx.layers.notes && !text.is_empty() {
1399                blocks.push(ctx.breaks(&ctx.text(text)));
1400            }
1401        }
1402        Node::Commented { inner, .. } => render_one(inner, blocks, ctx),
1403        // The item's text is already the runs' text (docling's Markdown of
1404        // its inline group: the runs joined, no markup — `H2O`).
1405        Node::ScriptText { inner, .. } => render_one(inner, blocks, ctx),
1406        // Layout provenance is DocLang-only; render the wrapped node.
1407        Node::Located { inner, .. } | Node::Prov { inner, .. } | Node::Track { inner, .. } => {
1408            render_one(inner, blocks, ctx)
1409        }
1410        // Page breaks are DocLang-only; docling omits them from Markdown.
1411        Node::PageBreak => {}
1412        // Page markers feed the JSON export only.
1413        Node::PageInfo { .. } | Node::ProvContinuation { .. } => {}
1414        // A link destination (#852) feeds the JSON export only.
1415        Node::Anchor { .. } => {}
1416        // Runs of adjacent list items are merged by `render`; a stray single
1417        // item (a hand-built document, or a `Located` wrapper around one)
1418        // still renders as its own one-item list instead of panicking —
1419        // `nodes` is public API, so every representable tree must serialize.
1420        Node::ListItem { .. } => render_list_run(std::slice::from_ref(node), blocks, ctx),
1421        // Outside a list run (a hand-built document): a paragraph.
1422        Node::ListText { text, .. } if text.is_empty() => {}
1423        Node::ListText { text, .. } => blocks.push(ctx.breaks(&ctx.text(text))),
1424    }
1425}
1426
1427/// The Markdown for a picture under the active [`ImageMode`]; Referenced mode also
1428/// records the bytes in `ctx.artifacts` for the caller to write.
1429/// docling-core's `_humanize_text`: underscores to spaces, first letter
1430/// capitalized ("line_chart" -> "Line chart").
1431fn humanize_label(label: &str) -> String {
1432    let text = label.replace('_', " ");
1433    let mut chars = text.chars();
1434    match chars.next() {
1435        Some(f) => f.to_uppercase().collect::<String>() + chars.as_str(),
1436        None => text,
1437    }
1438}
1439
1440/// The image line's alt: docling's `Image`, or the picture's alt text (#676)
1441/// on one line with its `]` escaped, so it cannot close the bracket.
1442fn image_alt(alt: Option<&str>) -> String {
1443    match alt {
1444        Some(text) => text
1445            .split_whitespace()
1446            .collect::<Vec<_>>()
1447            .join(" ")
1448            .replace('\\', "\\\\")
1449            .replace(']', "\\]"),
1450        None => "Image".to_string(),
1451    }
1452}
1453
1454fn picture_marker(image: Option<&crate::PictureImage>, ctx: &mut Ctx, alt: Option<&str>) -> String {
1455    match (ctx.images, image) {
1456        // docling embeds the `ImageRef`'s PNG (a JPEG re-encoded).
1457        (ImageMode::Embedded, Some(img)) => {
1458            format!(
1459                "![{}]({})",
1460                image_alt(alt),
1461                crate::pixel_digest::docling_data_uri(img).1
1462            )
1463        }
1464        (ImageMode::Referenced, Some(img)) => {
1465            let path = format!(
1466                "{}/image_{:06}.{}",
1467                ctx.artifacts_dir,
1468                ctx.pic_index,
1469                ext_for(&img.mimetype)
1470            );
1471            ctx.pic_index += 1;
1472            ctx.artifacts.push((path.clone(), img.data.clone()));
1473            format!("![{}]({})", image_alt(alt), escape_uri_path(&path))
1474        }
1475        // Placeholder, or any mode with no extracted image.
1476        _ => ctx.image_placeholder.clone(),
1477    }
1478}
1479
1480/// Encode a URL or filesystem path as a Markdown link destination —
1481/// docling-core's `MarkdownPictureSerializer._escape_uri_path`
1482/// (docling-core#698, 2.94). Handles URLs of any scheme as well as POSIX and
1483/// Windows paths, keeps relative paths relative and never double-encodes:
1484/// backslashes become `/` (a backslash is both the Windows separator and a
1485/// Markdown escape), a UNC share `//host/…` and an absolute Windows path
1486/// `C:/…` become RFC 8089 `file://` URLs (the one spelling a renderer cannot
1487/// misread as a scheme-relative URL or a `C:` scheme), a URL keeps its
1488/// scheme / authority / delimiters with only the components encoded, and
1489/// everything else is percent-encoded as a path. `%` is kept so an
1490/// already-encoded destination stays as it is; spaces and parentheses are
1491/// encoded because they would end (or unbalance) a Markdown inline link.
1492pub(crate) fn escape_uri_path(value: &str) -> String {
1493    const KEEP: &str = "/%:@+,;=~$!&'*";
1494    let s = value.replace('\\', "/");
1495    if let Some(rest) = s.strip_prefix("//") {
1496        // A fileshare: `file://<host>/<path>`, the host possibly empty.
1497        let rest = rest.trim_start_matches('/');
1498        let (host, tail) = rest.split_once('/').unwrap_or((rest, ""));
1499        return format!("file://{host}{}", percent_quote(&format!("/{tail}"), KEEP));
1500    }
1501    let bytes = s.as_bytes();
1502    if bytes.len() >= 3 && bytes[0].is_ascii_alphabetic() && bytes[1] == b':' && bytes[2] == b'/' {
1503        // A Windows path with a drive letter: `file:///C:/…`.
1504        return format!("file:///{}", percent_quote(&s, KEEP));
1505    }
1506    // A URL keeps its scheme, authority and delimiters; only its components are
1507    // encoded. A single-character scheme cannot be real (it is a drive letter,
1508    // handled above), so it is read as a path — like `urlsplit`.
1509    if let Some((scheme, rest)) = s.split_once(':') {
1510        let valid_scheme = scheme.len() > 1
1511            && scheme.as_bytes()[0].is_ascii_alphabetic()
1512            && scheme
1513                .bytes()
1514                .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'+' | b'-' | b'.'));
1515        if valid_scheme {
1516            let (authority, rest) = match rest.strip_prefix("//") {
1517                Some(r) => {
1518                    let end = r.find(['/', '?', '#']).unwrap_or(r.len());
1519                    (Some(&r[..end]), &r[end..])
1520                }
1521                None => (None, rest),
1522            };
1523            let (before_frag, fragment) = rest.split_once('#').unwrap_or((rest, ""));
1524            let (path, query) = before_frag.split_once('?').unwrap_or((before_frag, ""));
1525            let mut out = format!("{scheme}:");
1526            if let Some(a) = authority {
1527                out.push_str("//");
1528                out.push_str(a);
1529            }
1530            out.push_str(&percent_quote(path, KEEP));
1531            if !query.is_empty() {
1532                out.push('?');
1533                out.push_str(&percent_quote(query, KEEP));
1534            }
1535            if !fragment.is_empty() {
1536                out.push('#');
1537                out.push_str(&percent_quote(fragment, KEEP));
1538            }
1539            return out;
1540        }
1541    }
1542    // A relative or root-relative local path.
1543    percent_quote(&s, KEEP)
1544}
1545
1546/// `urllib.parse.quote(s, safe)`: unreserved ASCII (`A–Z a–z 0–9 _ . - ~`) and
1547/// the `safe` set stay, every other byte of the UTF-8 encoding becomes `%XX`.
1548fn percent_quote(s: &str, safe: &str) -> String {
1549    let mut out = String::with_capacity(s.len());
1550    for &b in s.as_bytes() {
1551        let keep = b.is_ascii_alphanumeric()
1552            || matches!(b, b'_' | b'.' | b'-' | b'~')
1553            || (b.is_ascii() && safe.contains(b as char));
1554        if keep {
1555            out.push(b as char);
1556        } else {
1557            out.push_str(&format!("%{b:02X}"));
1558        }
1559    }
1560    out
1561}
1562
1563pub(crate) fn ext_for(mimetype: &str) -> &str {
1564    match mimetype {
1565        "image/jpeg" => "jpg",
1566        "image/gif" => "gif",
1567        "image/webp" => "webp",
1568        "image/bmp" => "bmp",
1569        "image/tiff" => "tif",
1570        "image/svg+xml" => "svg",
1571        _ => "png",
1572    }
1573}
1574
1575/// Render a table. `compact` selects between two serializers:
1576///
1577/// - **padded** (default) — docling-core's `tabulate(tablefmt="github")`: columns
1578///   are padded to a fixed width (header width + a minimum padding of 2, or the
1579///   widest data cell); numeric columns (every data cell parses as a number) are
1580///   right-aligned, others left-aligned; separators are plain dashes of
1581///   `width + 2`. Matches current published docling (DOCX/HTML conformance).
1582/// - **compact** — `| a | b |` cells with single-dash `| - | - |` separators, no
1583///   width padding. Matches the committed PDF groundtruth corpus, which predates
1584///   the padded serializer.
1585///
1586/// Each cell is first escaped (`\n` → space, `|` → `&#124;`) so it can't break the
1587/// table. The header row is the table's leading `column_header` block flattened
1588/// to one row ([`Table::header_row_count`] + [`flatten_header_rows`],
1589/// docling-core#723); alignment and widths are computed over the body rows.
1590/// Whether a table cell counts as a number for column alignment, matching
1591/// `tabulate`'s detection: an ordinary float/int (`f64`-parseable, covering
1592/// `1e2`/`inf`/`+1.5`) **or** a thousands-separated number like `7,015`.
1593fn is_number_cell(t: &str) -> bool {
1594    t.parse::<f64>().is_ok() || is_thousands_number(t)
1595}
1596
1597/// A number with comma thousands-separators, per `tabulate`'s
1598/// `_float_with_thousands_separators` regex
1599/// (`^(([+-]?[0-9]{1,3})(?:,([0-9]{3}))*)?(?(1)\.[0-9]*|\.[0-9]+)?$`): the
1600/// integer part is 1–3 digits then any number of `,ddd` groups; the fraction is
1601/// optional (and, without an integer part, must have at least one digit).
1602fn is_thousands_number(t: &str) -> bool {
1603    let b = t.as_bytes();
1604    let mut i = 0;
1605    let start = i;
1606    if i < b.len() && (b[i] == b'+' || b[i] == b'-') {
1607        i += 1;
1608    }
1609    // First digit chunk: 1–3 digits.
1610    let d0 = i;
1611    while i < b.len() && b[i].is_ascii_digit() && i - d0 < 3 {
1612        i += 1;
1613    }
1614    let has_int = i > d0;
1615    if has_int {
1616        // Subsequent `,ddd` groups (exactly three digits each).
1617        while i + 3 < b.len() + 1
1618            && b.get(i) == Some(&b',')
1619            && b.get(i + 1).is_some_and(u8::is_ascii_digit)
1620            && b.get(i + 2).is_some_and(u8::is_ascii_digit)
1621            && b.get(i + 3).is_some_and(u8::is_ascii_digit)
1622        {
1623            i += 4;
1624        }
1625    } else {
1626        // A sign only counts with an integer part.
1627        i = start;
1628    }
1629    // Optional fraction.
1630    if i < b.len() && b[i] == b'.' {
1631        i += 1;
1632        let f0 = i;
1633        while i < b.len() && b[i].is_ascii_digit() {
1634            i += 1;
1635        }
1636        if !has_int && i == f0 {
1637            return false; // `.` with no digits and no integer part
1638        }
1639    } else if !has_int {
1640        return false; // neither integer nor fractional part
1641    }
1642    i == b.len()
1643}
1644
1645/// The single GFM header row for a table: the leading header rows (see
1646/// [`Table::header_row_count`]) flattened per column, texts joined with
1647/// `" - "` after dropping consecutive duplicates — docling-core's
1648/// `_flatten_header_rows` (docling-core#723). The duplicate rule is what
1649/// keeps a row-spanning header from being joined to itself (the grid repeats
1650/// its text into every row it covers); it is position-based, so two stacked
1651/// levels sharing a label collapse too — GFM has one header row, and upstream
1652/// accepts that loss. No header rows → one empty header cell per column.
1653fn flatten_header_rows(header_rows: &[Vec<String>], num_cols: usize) -> Vec<String> {
1654    (0..num_cols)
1655        .map(|c| {
1656            let mut parts: Vec<&str> = Vec::new();
1657            for row in header_rows {
1658                let text = row.get(c).map(String::as_str).unwrap_or("");
1659                if !text.is_empty() && parts.last() != Some(&text) {
1660                    parts.push(text);
1661                }
1662            }
1663            parts.join(" - ")
1664        })
1665        .collect()
1666}
1667
1668/// docling-core's Markdown for a formula item whose text was never decoded
1669/// (a PDF formula region converted without formula enrichment).
1670pub(crate) const FORMULA_NOT_DECODED: &str = "<!-- formula-not-decoded -->";
1671
1672pub(crate) fn render_table(table: &Table, compact: bool) -> String {
1673    if table.rows.is_empty() {
1674        return String::new();
1675    }
1676    let num_cols = table.rows.iter().map(Vec::len).max().unwrap_or(0);
1677    if num_cols == 0 {
1678        return String::new();
1679    }
1680
1681    // Escaped, rectangular grid (ragged rows padded with empty cells). The
1682    // header block is resolved to the one row GFM allows (docling-core#723);
1683    // `tabulate` strips data cells of surrounding whitespace but leaves the
1684    // header texts as-is.
1685    let num_headers = table.header_row_count().min(table.rows.len());
1686    let escaped = |r: usize| -> Vec<String> {
1687        (0..num_cols)
1688            .map(|c| escape_cell(table.rows[r].get(c).map(String::as_str).unwrap_or("")))
1689            .collect()
1690    };
1691    let header_rows: Vec<Vec<String>> = (0..num_headers).map(escaped).collect();
1692    let header = flatten_header_rows(&header_rows, num_cols);
1693    let body: Vec<Vec<String>> = (num_headers..table.rows.len())
1694        .map(|r| {
1695            escaped(r)
1696                .into_iter()
1697                .map(|c| c.trim().to_string())
1698                .collect()
1699        })
1700        .collect();
1701
1702    if compact {
1703        // Compact: cells joined by " | ", no padding, single-dash separators.
1704        let render_row = |row: &[String]| -> String { format!("| {} |", row.join(" | ")) };
1705        let mut lines = Vec::with_capacity(body.len() + 2);
1706        lines.push(render_row(&header));
1707        let sep: Vec<&str> = (0..num_cols).map(|_| "-").collect();
1708        lines.push(format!("| {} |", sep.join(" | ")));
1709        for row in &body {
1710            lines.push(render_row(row));
1711        }
1712        return lines.join("\n");
1713    }
1714
1715    // Display width (Unicode scalar count — good enough for now).
1716    let dw = |s: &str| s.chars().count();
1717
1718    // A column is right-aligned when at least one body cell is numeric and every
1719    // non-empty body cell is numeric — matching `tabulate`'s column typing, where
1720    // empty cells are "missing" (ignored) and a number may carry thousands
1721    // separators (`7,015`), which a plain `f64` parse rejects.
1722    let right: Vec<bool> = (0..num_cols)
1723        .map(|c| {
1724            let mut any = false;
1725            for row in &body {
1726                let t = row[c].trim();
1727                if t.is_empty() {
1728                    continue;
1729                }
1730                if !is_number_cell(t) {
1731                    return false;
1732                }
1733                any = true;
1734            }
1735            any
1736        })
1737        .collect();
1738
1739    // Column width = max(header_width + MIN_PADDING(2), max body-cell width).
1740    let width: Vec<usize> = (0..num_cols)
1741        .map(|c| {
1742            let mut w = dw(&header[c]) + 2;
1743            for row in &body {
1744                w = w.max(dw(&row[c]));
1745            }
1746            w
1747        })
1748        .collect();
1749
1750    let fmt_cell = |s: &str, c: usize| -> String {
1751        let pad = " ".repeat(width[c].saturating_sub(dw(s)));
1752        let body = if right[c] {
1753            format!("{pad}{s}")
1754        } else {
1755            format!("{s}{pad}")
1756        };
1757        format!(" {body} ")
1758    };
1759    let render_row = |row: &[String]| -> String {
1760        let cells: Vec<String> = (0..num_cols).map(|c| fmt_cell(&row[c], c)).collect();
1761        format!("|{}|", cells.join("|"))
1762    };
1763
1764    let mut lines = Vec::with_capacity(body.len() + 2);
1765    lines.push(render_row(&header));
1766    let sep: Vec<String> = (0..num_cols).map(|c| "-".repeat(width[c] + 2)).collect();
1767    lines.push(format!("|{}|", sep.join("|")));
1768    for row in &body {
1769        lines.push(render_row(row));
1770    }
1771    lines.join("\n")
1772}
1773
1774/// Escape a table cell so it can't break the markdown table: newlines become
1775/// spaces and pipes become the `&#124;` HTML entity (matches docling-core).
1776fn escape_cell(s: &str) -> String {
1777    s.replace('\n', " ").replace('|', "&#124;")
1778}
1779
1780#[cfg(test)]
1781mod tests {
1782    use super::*;
1783    use crate::{PictureImage, TableCell, TableStructure};
1784
1785    /// docling-core's formula Markdown (#1120): `$$…$$` for decoded text, the
1786    /// placeholder for an undecoded formula that has source text, nothing
1787    /// for one with neither — never an empty `$$$$`. The chunker prints the
1788    /// same, and an empty formula still takes its item slot.
1789    #[test]
1790    fn an_undecoded_formula_prints_the_placeholder() {
1791        let formula = |latex: &str, orig: &str| Node::Formula {
1792            latex: latex.into(),
1793            orig: orig.into(),
1794            location: None,
1795        };
1796        let mut doc = DoclingDocument::new("t");
1797        doc.nodes = vec![
1798            formula("E = mc^2", "E = mc 2"),
1799            formula("", "E = mc 2"),
1800            formula("", ""),
1801            Node::Paragraph {
1802                text: "After.".into(),
1803            },
1804        ];
1805        assert_eq!(
1806            doc.export_to_markdown().trim(),
1807            "$$E = mc^2$$\n\n<!-- formula-not-decoded -->\n\nAfter."
1808        );
1809        let chunks: Vec<String> = crate::chunker::HierarchicalChunker
1810            .chunk(&doc)
1811            .into_iter()
1812            .map(|c| c.text)
1813            .collect();
1814        assert_eq!(
1815            chunks,
1816            ["$$E = mc^2$$", "<!-- formula-not-decoded -->", "After."]
1817        );
1818    }
1819
1820    /// #385: where one list ends and the next begins is the backend's call
1821    /// (`first_in_list`), never the serializer's. An ordered run `1.` → `5.`
1822    /// is one list (an AsciiDoc numbered list around a nested one), and so are
1823    /// mixed bullet/ordered items the backend did not separate; only a flagged
1824    /// item opens a new list and earns the blank line.
1825    #[test]
1826    fn list_boundaries_come_from_the_backend_not_the_numbering() {
1827        let item = |ordered: bool, number: u64, first_in_list: bool, text: &str| Node::ListItem {
1828            ordered,
1829            number,
1830            first_in_list,
1831            text: text.into(),
1832            level: 0,
1833            marker: None,
1834            location: None,
1835            split: None,
1836            dclx: None,
1837            href: None,
1838            layer: None,
1839        };
1840        let md = |items: Vec<Node>| {
1841            let mut doc = DoclingDocument::new("t");
1842            for n in items {
1843                doc.push(n);
1844            }
1845            doc.export_to_markdown()
1846        };
1847        // A number gap alone is not a boundary.
1848        assert_eq!(
1849            md(vec![
1850                item(true, 1, true, "one"),
1851                item(true, 5, false, "five")
1852            ]),
1853            "1. one\n5. five\n"
1854        );
1855        // Nor is a kind flip the backend did not flag …
1856        assert_eq!(
1857            md(vec![
1858                item(false, 0, true, "bullet"),
1859                item(true, 1, false, "one"),
1860                item(false, 0, false, "bullet two"),
1861            ]),
1862            "- bullet\n1. one\n- bullet two\n"
1863        );
1864        // … while a flagged item is one, whatever its number says.
1865        assert_eq!(
1866            md(vec![
1867                item(true, 1, true, "a"),
1868                item(true, 2, false, "b"),
1869                item(true, 3, true, "new list, continuing count"),
1870            ]),
1871            "1. a\n2. b\n\n3. new list, continuing count\n"
1872        );
1873    }
1874
1875    #[test]
1876    fn renders_headings_paragraphs_and_lists() {
1877        let mut doc = DoclingDocument::new("demo");
1878        doc.add_heading(1, "Title");
1879        doc.add_paragraph("Hello world.");
1880        doc.push(Node::ListItem {
1881            ordered: false,
1882            number: 1,
1883            first_in_list: true,
1884            text: "first".into(),
1885            level: 0,
1886            marker: None,
1887            location: None,
1888            split: None,
1889            dclx: None,
1890            href: None,
1891            layer: None,
1892        });
1893        doc.push(Node::ListItem {
1894            ordered: false,
1895            number: 2,
1896            first_in_list: false,
1897            text: "second".into(),
1898            level: 0,
1899            marker: None,
1900            location: None,
1901            split: None,
1902            dclx: None,
1903            href: None,
1904            layer: None,
1905        });
1906        let md = doc.export_to_markdown();
1907        assert_eq!(md, "# Title\n\nHello world.\n\n- first\n- second\n");
1908    }
1909
1910    /// docling-core 2.92 (#721): a single newline inside an item's text is a
1911    /// GFM hard line break, a blank line stays a paragraph break, and a heading
1912    /// collapses its newline to a space. Nested-table dumps stay verbatim.
1913    #[test]
1914    fn single_newlines_become_gfm_hard_line_breaks() {
1915        let mut doc = DoclingDocument::new("t");
1916        doc.push(Node::Heading {
1917            level: 1,
1918            text: "Hello\nWorld".into(),
1919        });
1920        doc.push(Node::Paragraph {
1921            text: "line one\nline two\n\npara two".into(),
1922        });
1923        doc.push(Node::ListItem {
1924            ordered: false,
1925            number: 1,
1926            first_in_list: true,
1927            text: "item\ncontinued".into(),
1928            level: 0,
1929            marker: None,
1930            location: None,
1931            split: None,
1932            dclx: None,
1933            href: None,
1934            layer: None,
1935        });
1936        doc.push(Node::TextDump("A1 B1 \n\n\nC1".into()));
1937        assert_eq!(
1938            doc.export_to_markdown(),
1939            "# Hello World\n\nline one  \nline two\n\npara two\n\n- item  \ncontinued\n\nA1 B1 \n\n\nC1\n"
1940        );
1941    }
1942
1943    /// docling-core#540: inside a rich table cell a heading is plain text;
1944    /// docling-core#724: a field region renders only its items' key/value text.
1945    #[test]
1946    fn table_cell_mode_and_field_regions() {
1947        let mut doc = DoclingDocument::new("t");
1948        doc.push(Node::Heading {
1949            level: 2,
1950            text: "A  text".into(),
1951        });
1952        doc.push(Node::Paragraph {
1953            text: "body".into(),
1954        });
1955        assert_eq!(to_markdown_table_cell(&doc, false), "A  text\n\nbody");
1956        assert_eq!(doc.export_to_markdown(), "## A  text\n\nbody\n");
1957
1958        let mut doc = DoclingDocument::new("f");
1959        doc.push(Node::FieldRegion {
1960            items: vec![crate::FieldItem {
1961                marker: None,
1962                key: Some("Name:".into()),
1963                value: Some("John Doe".into()),
1964                value_kind: None,
1965            }],
1966        });
1967        assert_eq!(doc.export_to_markdown(), "Name:\n\nJohn Doe\n");
1968    }
1969
1970    #[test]
1971    fn strict_renders_recovered_links_legacy_does_not() {
1972        let mut doc = DoclingDocument::new("cv");
1973        doc.add_paragraph("Find me on LinkedIn or GitHub.");
1974        doc.links = vec![
1975            ("LinkedIn".into(), "https://www.linkedin.com/in/x/".into()),
1976            ("GitHub".into(), "https://github.com/x/".into()),
1977        ];
1978        // Legacy/docling mode: links are left untouched (conformance preserved).
1979        assert_eq!(doc.export_to_markdown(), "Find me on LinkedIn or GitHub.\n");
1980        // Strict mode: anchors become Markdown links.
1981        assert_eq!(
1982            doc.export_to_markdown_with(true),
1983            "Find me on [LinkedIn](https://www.linkedin.com/in/x/) or [GitHub](https://github.com/x/).\n"
1984        );
1985    }
1986
1987    #[test]
1988    fn strict_links_match_escaped_anchor_and_consume_in_order() {
1989        let mut doc = DoclingDocument::new("d");
1990        // The PDF assembler HTML-escapes prose, so by serialization time the body
1991        // already carries `&amp;`; the anchor is stored un-escaped. The matcher must
1992        // escape the anchor to find it. Two identical anchors link in document order.
1993        doc.add_paragraph("AI &amp; ML here, and issues here, then issues there.");
1994        doc.links = vec![
1995            ("AI & ML".into(), "https://a/".into()),
1996            ("issues".into(), "https://first/".into()),
1997            ("issues".into(), "https://second/".into()),
1998        ];
1999        assert_eq!(
2000            doc.export_to_markdown_with(true),
2001            "[AI &amp; ML](https://a/) here, and [issues](https://first/) here, then [issues](https://second/) there.\n"
2002        );
2003    }
2004
2005    /// docling-core#698: the referenced-image destination is percent-encoded —
2006    /// upstream's own case table (paths, Windows flavours, UNC, URLs) plus
2007    /// idempotency on the encoded result.
2008    #[test]
2009    fn referenced_image_destinations_are_escaped() {
2010        let cases = [
2011            (
2012                "doc_artifacts/image_000001_ab12.png",
2013                "doc_artifacts/image_000001_ab12.png",
2014            ),
2015            (
2016                "My Report_artifacts/img.png",
2017                "My%20Report_artifacts/img.png",
2018            ),
2019            ("artifacts/img (1).png", "artifacts/img%20%281%29.png"),
2020            ("100%_scale/a#b?c.png", "100%_scale/a%23b%3Fc.png"),
2021            ("/home/a b/img.png", "/home/a%20b/img.png"),
2022            (
2023                "My Report_artifacts\\img.png",
2024                "My%20Report_artifacts/img.png",
2025            ),
2026            (
2027                "C:/Users/me/My Docs/img.png",
2028                "file:///C:/Users/me/My%20Docs/img.png",
2029            ),
2030            ("C:\\Users\\me\\img.png", "file:///C:/Users/me/img.png"),
2031            (
2032                "//server/share/My Docs/img.png",
2033                "file://server/share/My%20Docs/img.png",
2034            ),
2035            ("\\\\server\\share\\img.png", "file://server/share/img.png"),
2036            ("file:///home/a b/img.png", "file:///home/a%20b/img.png"),
2037            (
2038                "s3://bucket/My Report_artifacts/img.png",
2039                "s3://bucket/My%20Report_artifacts/img.png",
2040            ),
2041            (
2042                "https://example.com:8080/a b.png?w=1&h=2#frag",
2043                "https://example.com:8080/a%20b.png?w=1&h=2#frag",
2044            ),
2045            (
2046                "https://example.com/img (1).png",
2047                "https://example.com/img%20%281%29.png",
2048            ),
2049            ("caf\u{e9}/im\u{e4}ge.png", "caf%C3%A9/im%C3%A4ge.png"),
2050        ];
2051        for (input, expected) in cases {
2052            assert_eq!(escape_uri_path(input), expected, "input {input:?}");
2053            assert_eq!(
2054                escape_uri_path(expected),
2055                expected,
2056                "idempotent {expected:?}"
2057            );
2058        }
2059        // The whole marker, through the referenced-image export.
2060        let mut doc = DoclingDocument::new("t");
2061        doc.push(Node::Picture {
2062            caption: None,
2063            caption_href: None,
2064            image: Some(PictureImage {
2065                dpi: PictureImage::DEFAULT_DPI,
2066                mimetype: "image/png".into(),
2067                width: 1,
2068                height: 1,
2069                data: b"x".to_vec(),
2070                display_size: None,
2071            }),
2072            classification: None,
2073            description: None,
2074            caption_parent: Default::default(),
2075            caption_location: None,
2076        });
2077        let (md, files) = doc
2078            .export_to_markdown_with_images(ImageMode::Referenced, "My Report (final)_artifacts");
2079        assert!(
2080            md.contains("![Image](My%20Report%20%28final%29_artifacts/image_000000.png)"),
2081            "got:\n{md}"
2082        );
2083        // The file path handed back for writing stays unescaped.
2084        assert_eq!(files[0].0, "My Report (final)_artifacts/image_000000.png");
2085    }
2086
2087    /// Pictures the HTML backend folds into a list item print after the item
2088    /// line with plain newlines; a `<br>` newline in the item's own text is
2089    /// still a GFM hard line break.
2090    #[test]
2091    fn folded_list_item_pictures_keep_plain_newlines() {
2092        let doc = DoclingDocument::new("t");
2093        let ctx = Ctx::new(&doc, false, &MarkdownExportOptions::default());
2094        assert_eq!(
2095            list_item_text("Step\n<!-- image -->", &ctx),
2096            "Step\n<!-- image -->"
2097        );
2098        assert_eq!(
2099            list_item_text("Step\nAlt text\n<!-- image -->\n<!-- image -->", &ctx),
2100            "Step\nAlt text\n<!-- image -->\n<!-- image -->"
2101        );
2102        assert_eq!(
2103            list_item_text("line one\nline two", &ctx),
2104            "line one  \nline two"
2105        );
2106    }
2107
2108    /// docling-core#723: the header block is the leading run of rows on which a
2109    /// `column_header` cell starts, flattened per column with " - ".
2110    #[test]
2111    fn stacked_header_rows_flatten_into_one() {
2112        let mut t = Table {
2113            rows: vec![
2114                vec!["".into(), "% of Total".into(), "% of Total".into()],
2115                vec!["class".into(), "Train".into(), "Test".into()],
2116                vec!["Caption".into(), "2.04".into(), "1.77".into()],
2117            ],
2118            ..Default::default()
2119        };
2120        t.structure = Some(TableStructure {
2121            header_row: vec![true, true, false],
2122            col_continuation: vec![
2123                vec![false, false, true],
2124                vec![false, false, false],
2125                vec![false, false, false],
2126            ],
2127            ..Default::default()
2128        });
2129        assert_eq!(t.header_row_count(), 2);
2130        assert_eq!(
2131            render_table(&t, true),
2132            "| class | % of Total - Train | % of Total - Test |\n| - | - | - |\n| Caption | 2.04 | 1.77 |"
2133        );
2134        // padded: widths from the flattened header, alignment from body rows
2135        assert_eq!(
2136            render_table(&t, false),
2137            "| class   |   % of Total - Train |   % of Total - Test |\n\
2138             |---------|----------------------|---------------------|\n\
2139             | Caption |                 2.04 |                1.77 |"
2140        );
2141    }
2142
2143    /// A header spanning two rows is repeated into the second row by the grid;
2144    /// that row is not a header row unless another header cell starts there.
2145    #[test]
2146    fn vertically_spanning_header_does_not_extend_the_block() {
2147        let mut t = Table {
2148            rows: vec![
2149                vec!["Name".into(), "Value".into()],
2150                vec!["Name".into(), "1".into()],
2151                vec!["x".into(), "2".into()],
2152            ],
2153            ..Default::default()
2154        };
2155        t.structure = Some(TableStructure {
2156            col_header: vec![vec![true, true], vec![true, false], vec![false, false]],
2157            row_continuation: vec![vec![false, false], vec![true, false], vec![false, false]],
2158            ..Default::default()
2159        });
2160        assert_eq!(t.header_row_count(), 1);
2161        assert_eq!(
2162            render_table(&t, true),
2163            "| Name | Value |\n| - | - |\n| Name | 1 |\n| x | 2 |"
2164        );
2165    }
2166
2167    /// Flags that begin on a later row promote nothing: every row stays in the
2168    /// body under an empty header row (tabulate's `headers=["", ""]`).
2169    #[test]
2170    fn header_flags_not_on_row_zero_keep_all_rows_in_the_body() {
2171        let mut t = Table {
2172            rows: vec![
2173                vec!["1".into(), "2".into()],
2174                vec!["a".into(), "b".into()],
2175                vec!["333".into(), "4".into()],
2176            ],
2177            ..Default::default()
2178        };
2179        t.structure = Some(TableStructure {
2180            header_row: vec![false, true, false],
2181            ..Default::default()
2182        });
2183        assert_eq!(t.header_row_count(), 0);
2184        assert_eq!(
2185            render_table(&t, false),
2186            "|     |    |\n|-----|----|\n| 1   | 2  |\n| a   | b  |\n| 333 | 4  |"
2187        );
2188    }
2189
2190    /// A pivot table's row headers (`<th rowspan>`) carry `row_header`, not
2191    /// `column_header` (docling#4216), so the data row beside them is not
2192    /// pulled into the header block — what this port used to reach with a
2193    /// deviation now falls out of the flags themselves.
2194    #[test]
2195    fn pivot_row_headers_do_not_extend_the_header() {
2196        let mut t = Table {
2197            rows: vec![
2198                vec!["Year".into(), "Month".into()],
2199                vec!["2025".into(), "January".into()],
2200                vec!["2025".into(), "February".into()],
2201            ],
2202            ..Default::default()
2203        };
2204        t.structure = Some(TableStructure {
2205            col_header: vec![vec![true, true], vec![false, false], vec![false, false]],
2206            row_header: vec![vec![false, false], vec![true, false], vec![true, false]],
2207            row_continuation: vec![vec![false, false], vec![false, false], vec![true, false]],
2208            ..Default::default()
2209        });
2210        assert_eq!(t.header_row_count(), 1);
2211        assert_eq!(
2212            render_table(&t, true),
2213            "| Year | Month |\n| - | - |\n| 2025 | January |\n| 2025 | February |"
2214        );
2215    }
2216
2217    /// No `column_header` anywhere (first-class cells without flags) → row 0
2218    /// stays the header, as before.
2219    #[test]
2220    fn unflagged_cells_keep_row_zero_as_header() {
2221        let mut t = Table {
2222            rows: vec![vec!["h".into()], vec!["d".into()]],
2223            ..Default::default()
2224        };
2225        t.cells = Some(
2226            [(0usize, "h"), (1, "d")]
2227                .into_iter()
2228                .map(|(r, text)| TableCell {
2229                    text: text.into(),
2230                    bbox: None,
2231                    start_row: r,
2232                    start_col: 0,
2233                    row_span: 1,
2234                    col_span: 1,
2235                    column_header: false,
2236                    row_header: false,
2237                    row_section: false,
2238                })
2239                .collect(),
2240        );
2241        assert_eq!(t.header_row_count(), 1);
2242        assert_eq!(render_table(&t, true), "| h |\n| - |\n| d |");
2243    }
2244
2245    /// A table with first-class 1×1 cells, `column_header` where `ched` says.
2246    fn flagged_table(rows: &[&[&str]], ched: impl Fn(usize, usize) -> bool) -> Table {
2247        let mut cells = Vec::new();
2248        for (r, row) in rows.iter().enumerate() {
2249            for (c, text) in row.iter().enumerate() {
2250                cells.push(TableCell {
2251                    text: (*text).into(),
2252                    bbox: None,
2253                    start_row: r,
2254                    start_col: c,
2255                    row_span: 1,
2256                    col_span: 1,
2257                    column_header: ched(r, c),
2258                    row_header: false,
2259                    row_section: false,
2260                });
2261            }
2262        }
2263        Table {
2264            rows: rows
2265                .iter()
2266                .map(|row| row.iter().map(|t| (*t).to_string()).collect())
2267                .collect(),
2268            cells: Some(cells),
2269            ..Default::default()
2270        }
2271    }
2272
2273    /// #604 (docling-core#766, 2.97): a row whose first-column label is a
2274    /// `column_header` but whose other cells carry body text stops the header
2275    /// block. Expected outputs are docling-core 2.99's, byte for byte.
2276    #[test]
2277    fn rows_with_body_text_stop_the_header_block() {
2278        // The issue's form: labels flagged on every row, a real header on top.
2279        let t = flagged_table(
2280            &[
2281                &["Item", "Q1", "Q2"],
2282                &["Sales", "10", "20"],
2283                &["Costs", "5", "7"],
2284            ],
2285            |r, c| r == 0 || c == 0,
2286        );
2287        assert_eq!(t.header_row_count(), 1);
2288        assert_eq!(
2289            render_table(&t, false),
2290            "| Item   |   Q1 |   Q2 |\n\
2291             |--------|------|------|\n\
2292             | Sales  |   10 |   20 |\n\
2293             | Costs  |    5 |    7 |"
2294        );
2295        // Labels on every row and no header row: row 0 stops, later rows are
2296        // flagged → nothing promotable, the body keeps every row.
2297        let t = flagged_table(&[&["Sales", "10", "20"], &["Costs", "5", "7"]], |_, c| {
2298            c == 0
2299        });
2300        assert_eq!(t.header_row_count(), 0);
2301        assert_eq!(
2302            render_table(&t, false),
2303            "|       |    |    |\n\
2304             |-------|----|----|\n\
2305             | Sales | 10 | 20 |\n\
2306             | Costs |  5 |  7 |"
2307        );
2308        let t = flagged_table(
2309            &[&["a", "1", "2"], &["b", "3", "4"], &["c", "5", "6"]],
2310            |r, c| c == 0 && r < 2,
2311        );
2312        assert_eq!(t.header_row_count(), 0);
2313        // Row 0 stops on its body text, but no later row carries a flag:
2314        // row 0 is the header anyway, as for an unflagged table.
2315        let t = flagged_table(&[&["a", "1", "2"], &["b", "3", "4"]], |r, c| {
2316            r == 0 && c == 0
2317        });
2318        assert_eq!(t.header_row_count(), 1);
2319        assert_eq!(
2320            render_table(&t, false),
2321            "| a   |   1 |   2 |\n\
2322             |-----|-----|-----|\n\
2323             | b   |   3 |   4 |"
2324        );
2325        // Blank cells beside a flagged label are not body text.
2326        let t = flagged_table(&[&["Item", "", ""], &["x", "1", "2"]], |_, c| c == 0);
2327        assert_eq!(t.header_row_count(), 1);
2328        assert_eq!(
2329            render_table(&t, false),
2330            "| Item   |    |    |\n\
2331             |--------|----|----|\n\
2332             | x      |  1 |  2 |"
2333        );
2334    }
2335
2336    #[test]
2337    fn renders_compact_table() {
2338        let mut doc = DoclingDocument::new("t");
2339        // The compact form is opt-in (the PDF backend sets it); default output uses
2340        // the padded GitHub serializer (covered by the regression fixtures).
2341        doc.compact_tables = true;
2342        doc.push(Node::Table(Table {
2343            footnotes: Vec::new(),
2344            rows: vec![vec!["a".into(), "b".into()], vec!["1".into(), "2".into()]],
2345            location: None,
2346            structure: None,
2347            cell_blocks: None,
2348            cells: None,
2349            caption: None,
2350            caption_parent: Default::default(),
2351            caption_location: None,
2352            document_index: false,
2353        }));
2354        let md = doc.export_to_markdown();
2355        assert_eq!(md, "| a | b |\n| - | - |\n| 1 | 2 |\n");
2356    }
2357
2358    #[test]
2359    fn renders_padded_github_table_by_default() {
2360        let mut doc = DoclingDocument::new("t");
2361        doc.push(Node::Table(Table {
2362            footnotes: Vec::new(),
2363            rows: vec![vec!["a".into(), "b".into()], vec!["1".into(), "2".into()]],
2364            location: None,
2365            structure: None,
2366            cell_blocks: None,
2367            cells: None,
2368            caption: None,
2369            caption_parent: Default::default(),
2370            caption_location: None,
2371            document_index: false,
2372        }));
2373        let md = doc.export_to_markdown();
2374        // Numeric data columns are right-aligned; columns padded to header+2.
2375        assert_eq!(md, "|   a |   b |\n|-----|-----|\n|   1 |   2 |\n");
2376    }
2377
2378    #[test]
2379    fn strict_unescapes_inline_underscores_legacy_keeps_them() {
2380        let mut doc = DoclingDocument::new("t");
2381        doc.add_heading(1, "a\\_b");
2382        doc.add_paragraph("x\\_y");
2383        doc.push(Node::ListItem {
2384            ordered: false,
2385            number: 1,
2386            first_in_list: true,
2387            text: "i\\_j".into(),
2388            level: 0,
2389            marker: None,
2390            location: None,
2391            split: None,
2392            dclx: None,
2393            href: None,
2394            layer: None,
2395        });
2396        // Legacy reproduces docling's `\_` escaping byte-for-byte.
2397        assert_eq!(doc.export_to_markdown(), "# a\\_b\n\nx\\_y\n\n- i\\_j\n");
2398        // Strict prefers literal underscores (Rust-only readability mode).
2399        assert_eq!(doc.export_to_markdown_with(true), "# a_b\n\nx_y\n\n- i_j\n");
2400    }
2401
2402    /// Drive a document's nodes through [`MarkdownStreamer`] in the given page
2403    /// splits and assert the concatenated chunks equal the buffered serializer.
2404    fn assert_stream_matches(
2405        doc: &DoclingDocument,
2406        strict: bool,
2407        images: ImageMode,
2408        splits: &[usize],
2409    ) {
2410        let (want, want_artifacts) = to_markdown_images(doc, strict, images, "artifacts");
2411        let mut streamer =
2412            MarkdownStreamer::with_artifacts(strict, images, doc.compact_tables, "artifacts")
2413                .with_page_break_placeholder(doc.page_break_placeholder.clone());
2414        let mut got = String::new();
2415        let mut got_artifacts = Vec::new();
2416        let mut start = 0;
2417        for &end in splits {
2418            // Links only matter in strict mode; feed them all with the first batch
2419            // that has content (document order is preserved by the queue).
2420            let links = if start == 0 {
2421                doc.links.as_slice()
2422            } else {
2423                &[]
2424            };
2425            got.push_str(&streamer.push(&doc.nodes[start..end], links));
2426            // Referenced mode: drain per push, as a real caller writing files
2427            // page by page would — numbering must continue across drains.
2428            got_artifacts.extend(streamer.take_artifacts());
2429            start = end;
2430        }
2431        got.push_str(&streamer.push(
2432            &doc.nodes[start..],
2433            if start == 0 {
2434                doc.links.as_slice()
2435            } else {
2436                &[]
2437            },
2438        ));
2439        got_artifacts.extend(streamer.take_artifacts());
2440        got.push_str(&streamer.finish());
2441        assert_eq!(
2442            got, want,
2443            "streamed output diverged (splits={splits:?}, strict={strict})"
2444        );
2445        assert_eq!(
2446            got_artifacts, want_artifacts,
2447            "streamed artifacts diverged (splits={splits:?}, strict={strict})"
2448        );
2449    }
2450
2451    #[test]
2452    fn streaming_is_byte_identical_to_buffered() {
2453        let mut doc = DoclingDocument::new("d");
2454        doc.add_heading(1, "Title");
2455        doc.add_paragraph("First paragraph.");
2456        doc.push(Node::ListItem {
2457            ordered: false,
2458            number: 1,
2459            first_in_list: true,
2460            text: "a".into(),
2461            level: 0,
2462            marker: None,
2463            location: None,
2464            split: None,
2465            dclx: None,
2466            href: None,
2467            layer: None,
2468        });
2469        doc.push(Node::ListItem {
2470            ordered: false,
2471            number: 2,
2472            first_in_list: false,
2473            text: "b".into(),
2474            level: 0,
2475            marker: None,
2476            location: None,
2477            split: None,
2478            dclx: None,
2479            href: None,
2480            layer: None,
2481        });
2482        doc.push(Node::Code {
2483            language: Some("rust".into()),
2484            text: "let x = 1;".into(),
2485            orig: None,
2486            pretty: None,
2487        });
2488        doc.push(Node::Table(Table {
2489            footnotes: Vec::new(),
2490            rows: vec![vec!["a".into(), "b".into()], vec!["1".into(), "2".into()]],
2491            location: None,
2492            structure: None,
2493            cell_blocks: None,
2494            cells: None,
2495            caption: None,
2496            caption_parent: Default::default(),
2497            caption_location: None,
2498            document_index: false,
2499        }));
2500        doc.push(Node::Picture {
2501            caption: Some("Fig 1".into()),
2502            caption_href: None,
2503            image: Some(PictureImage {
2504                dpi: PictureImage::DEFAULT_DPI,
2505                mimetype: "image/png".into(),
2506                width: 2,
2507                height: 2,
2508                data: b"png-one".to_vec(),
2509                display_size: None,
2510            }),
2511            classification: None,
2512            description: None,
2513            caption_parent: Default::default(),
2514            caption_location: None,
2515        });
2516        doc.add_paragraph("Last paragraph.");
2517        // A second embedded picture, so referenced mode must keep numbering
2518        // (`image_000001`) across chunk boundaries.
2519        doc.push(Node::Picture {
2520            caption: None,
2521            caption_href: None,
2522            image: Some(PictureImage {
2523                dpi: PictureImage::DEFAULT_DPI,
2524                mimetype: "image/png".into(),
2525                width: 2,
2526                height: 2,
2527                data: b"png-two".to_vec(),
2528                display_size: None,
2529            }),
2530            classification: None,
2531            description: None,
2532            caption_parent: Default::default(),
2533            caption_location: None,
2534        });
2535
2536        // A run of list items must never straddle a split, so try splits that fall
2537        // on safe block boundaries (the streaming PDF assembler guarantees this).
2538        for &strict in &[false, true] {
2539            for &images in &[
2540                ImageMode::Placeholder,
2541                ImageMode::Embedded,
2542                ImageMode::Referenced,
2543            ] {
2544                for splits in [&[][..], &[1][..], &[2][..], &[4][..], &[1, 4, 6, 7][..]] {
2545                    assert_stream_matches(&doc, strict, images, splits);
2546                }
2547            }
2548        }
2549    }
2550
2551    #[test]
2552    fn streaming_applies_recovered_links_in_strict_mode() {
2553        let mut doc = DoclingDocument::new("d");
2554        doc.add_paragraph("See LinkedIn for details.");
2555        doc.add_paragraph("And GitHub too.");
2556        doc.links = vec![
2557            ("LinkedIn".into(), "https://lnkd/".into()),
2558            ("GitHub".into(), "https://gh/".into()),
2559        ];
2560        // The second anchor lives in the second block, so it must be carried across
2561        // the page boundary and placed when that block streams out.
2562        assert_stream_matches(&doc, true, ImageMode::Placeholder, &[1]);
2563    }
2564
2565    /// A three-page document with one empty page in the middle and page
2566    /// markers of both kinds, as the backends emit them.
2567    fn paged_doc() -> DoclingDocument {
2568        let mut doc = DoclingDocument::new("p");
2569        doc.push(Node::PageInfo {
2570            page_no: 1,
2571            width: 100.0,
2572            height: 100.0,
2573        });
2574        doc.add_heading(1, "Title");
2575        doc.add_paragraph("Page one.");
2576        // Page two: a marker plus furniture only — renders nothing.
2577        doc.push(Node::PageBreak);
2578        doc.push(Node::PageInfo {
2579            page_no: 2,
2580            width: 100.0,
2581            height: 100.0,
2582        });
2583        doc.push(Node::PageFurniture {
2584            footer: true,
2585            location: [0, 500, 511, 511],
2586            text: "2".into(),
2587        });
2588        doc.push(Node::PageBreak);
2589        doc.push(Node::PageInfo {
2590            page_no: 3,
2591            width: 100.0,
2592            height: 100.0,
2593        });
2594        doc.add_paragraph("Page three.");
2595        // A trailing boundary with nothing after it.
2596        doc.push(Node::PageBreak);
2597        doc
2598    }
2599
2600    #[test]
2601    fn page_break_placeholder_lands_between_pages_only() {
2602        let mut doc = paged_doc();
2603        // Off by default: docling's Markdown carries no page breaks.
2604        assert_eq!(
2605            doc.export_to_markdown(),
2606            "# Title\n\nPage one.\n\nPage three.\n"
2607        );
2608        doc.page_break_placeholder = Some("<!-- page break -->".into());
2609        // One break for the 1→3 transition (the empty page 2 and the doubled
2610        // PageBreak+PageInfo markers collapse), none before the first block,
2611        // none for the trailing boundary.
2612        assert_eq!(
2613            doc.export_to_markdown(),
2614            "# Title\n\nPage one.\n\n<!-- page break -->\n\nPage three.\n"
2615        );
2616        // An empty placeholder is still a (blank) part, as upstream's
2617        // `str.replace(marker, "")` leaves the delimiters around it.
2618        doc.page_break_placeholder = Some(String::new());
2619        assert_eq!(
2620            doc.export_to_markdown(),
2621            "# Title\n\nPage one.\n\n\n\nPage three.\n"
2622        );
2623    }
2624
2625    #[test]
2626    fn page_break_placeholder_never_leads_a_single_page() {
2627        let mut doc = DoclingDocument::new("one");
2628        doc.page_break_placeholder = Some("---".into());
2629        doc.push(Node::PageBreak);
2630        doc.push(Node::PageInfo {
2631            page_no: 1,
2632            width: 10.0,
2633            height: 10.0,
2634        });
2635        doc.add_paragraph("Only page.");
2636        assert_eq!(doc.export_to_markdown(), "Only page.\n");
2637        // Two boundaries with no content between them: still one break.
2638        doc.push(Node::PageBreak);
2639        doc.push(Node::PageBreak);
2640        doc.add_paragraph("Next.");
2641        assert_eq!(doc.export_to_markdown(), "Only page.\n\n---\n\nNext.\n");
2642    }
2643
2644    #[test]
2645    fn page_break_placeholder_streams_byte_identical() {
2646        let mut doc = paged_doc();
2647        doc.page_break_placeholder = Some("<!-- page break -->".into());
2648        // Split at every page marker (how the PDF pipeline pushes page batches)
2649        // and at odd places inside a page: the pending break must survive a
2650        // push that renders nothing (page two) and land on page three's block.
2651        for splits in [
2652            &[3usize][..],
2653            &[3, 6],
2654            &[3, 6, 8],
2655            &[1, 2, 3, 4, 5, 6, 7, 8, 9],
2656            &[8],
2657        ] {
2658            assert_stream_matches(&doc, false, ImageMode::Placeholder, splits);
2659            assert_stream_matches(&doc, true, ImageMode::Placeholder, splits);
2660        }
2661    }
2662
2663    #[test]
2664    fn strict_tightens_punctuation_spacing_legacy_keeps_it() {
2665        let mut doc = DoclingDocument::new("t");
2666        doc.add_paragraph("see [ 37 , 36 ] and ( x ) .");
2667        // Legacy keeps docling's spacing byte-for-byte.
2668        assert_eq!(doc.export_to_markdown(), "see [ 37 , 36 ] and ( x ) .\n");
2669        // Strict tightens punctuation for readable Markdown.
2670        assert_eq!(doc.export_to_markdown_with(true), "see [37, 36] and (x).\n");
2671    }
2672
2673    // ----- MarkdownExportOptions (#599) ------------------------------------
2674
2675    /// A document touching every option: furniture, a comment, a hidden
2676    /// sheet group, a picture with nested text, escaped text.
2677    fn options_doc() -> DoclingDocument {
2678        use crate::document::ContentLayer;
2679        let mut doc = DoclingDocument::new("opts");
2680        doc.push(Node::PageFurniture {
2681            footer: false,
2682            location: [0, 0, 0, 0],
2683            text: "FAX COVER \\_ R&amp;D".into(),
2684        });
2685        doc.add_heading(1, "R&amp;D \\_ report");
2686        doc.add_paragraph("Body a\\_b &lt;tag&gt;");
2687        doc.push(Node::Picture {
2688            caption: Some("Figure 1".into()),
2689            caption_href: None,
2690            image: None,
2691            classification: None,
2692            description: None,
2693            caption_parent: Default::default(),
2694            caption_location: None,
2695        });
2696        doc.push(Node::PictureChildren(vec![
2697            Node::Paragraph {
2698                text: "Field: Name".into(),
2699            },
2700            Node::Paragraph {
2701                text: "Field: Date".into(),
2702            },
2703        ]));
2704        doc.push(Node::CommentSection {
2705            name: "comment-1".into(),
2706            text: "[author: A]: note".into(),
2707            refs_note_text: false,
2708            grouped: true,
2709        });
2710        doc.push(Node::Group {
2711            label: "section".into(),
2712            name: Some("sheet: Hidden".into()),
2713            layer: Some(ContentLayer::Invisible),
2714            children: vec![Node::Paragraph {
2715                text: "hidden cell".into(),
2716            }],
2717        });
2718        doc.push(Node::Furniture {
2719            layer: ContentLayer::Furniture,
2720            inner: Box::new(Node::Paragraph {
2721                text: "Page 1 of 2".into(),
2722            }),
2723        });
2724        doc.push(Node::FurnitureText {
2725            label: "page_footer".into(),
2726            text: "footer line".into(),
2727        });
2728        doc
2729    }
2730
2731    /// The defaults are docling's: the options export is the plain export,
2732    /// byte for byte — and the plain export is unchanged (furniture, notes,
2733    /// hidden sheets and picture children out; escaping kept).
2734    #[test]
2735    fn default_options_are_the_default_export() {
2736        let doc = options_doc();
2737        let plain = doc.export_to_markdown();
2738        assert_eq!(
2739            plain,
2740            "# R&amp;D \\_ report\n\nBody a\\_b &lt;tag&gt;\n\nFigure 1\n\n<!-- image -->\n"
2741        );
2742        let (with_default, artifacts) =
2743            doc.export_to_markdown_with_options(&MarkdownExportOptions::default());
2744        assert_eq!(with_default, plain);
2745        assert!(artifacts.is_empty());
2746    }
2747
2748    #[test]
2749    fn layers_render_furniture_notes_and_hidden_sheets() {
2750        use crate::document::ContentLayer;
2751        let doc = options_doc();
2752        let md = |layers: ContentLayers| {
2753            doc.export_to_markdown_with_options(&MarkdownExportOptions {
2754                layers,
2755                ..MarkdownExportOptions::default()
2756            })
2757            .0
2758        };
2759        assert_eq!(
2760            md(ContentLayers::BODY.with(ContentLayer::Furniture)),
2761            "FAX COVER \\_ R&amp;D\n\n# R&amp;D \\_ report\n\nBody a\\_b &lt;tag&gt;\n\nFigure 1\n\n<!-- image -->\n\nPage 1 of 2\n\nfooter line\n",
2762            "a page header, a furniture-wrapped paragraph and a furniture text item render as paragraphs"
2763        );
2764        assert_eq!(
2765            md(ContentLayers::BODY.with(ContentLayer::Notes)),
2766            "# R&amp;D \\_ report\n\nBody a\\_b &lt;tag&gt;\n\nFigure 1\n\n<!-- image -->\n\n[author: A]: note\n"
2767        );
2768        assert_eq!(
2769            md(ContentLayers::BODY.with(ContentLayer::Invisible)),
2770            "# R&amp;D \\_ report\n\nBody a\\_b &lt;tag&gt;\n\nFigure 1\n\n<!-- image -->\n\nhidden cell\n",
2771            "a hidden sheet's items sit on the sheet's layer"
2772        );
2773        assert_eq!(
2774            md(ContentLayers::NONE.with(ContentLayer::Furniture)),
2775            "FAX COVER \\_ R&amp;D\n\nPage 1 of 2\n\nfooter line\n",
2776            "without the body layer only the furniture prints"
2777        );
2778        assert_eq!(md(ContentLayers::NONE), "");
2779        assert_eq!(
2780            md(ContentLayers::ALL),
2781            "FAX COVER \\_ R&amp;D\n\n# R&amp;D \\_ report\n\nBody a\\_b &lt;tag&gt;\n\nFigure 1\n\n<!-- image -->\n\n[author: A]: note\n\nhidden cell\n\nPage 1 of 2\n\nfooter line\n"
2782        );
2783    }
2784
2785    /// A list item carries its own layer: a furniture list renders with the
2786    /// furniture layer and stays out of the body export.
2787    #[test]
2788    fn layers_apply_to_list_items() {
2789        use crate::document::ContentLayer;
2790        let mut doc = DoclingDocument::new("lists");
2791        doc.push(Node::ListItem {
2792            ordered: false,
2793            number: 1,
2794            first_in_list: true,
2795            text: "nav link".into(),
2796            level: 0,
2797            marker: None,
2798            location: None,
2799            split: None,
2800            dclx: None,
2801            href: None,
2802            layer: Some(ContentLayer::Furniture),
2803        });
2804        doc.add_paragraph("body");
2805        assert_eq!(doc.export_to_markdown(), "body\n");
2806        let (md, _) = doc.export_to_markdown_with_options(&MarkdownExportOptions {
2807            layers: ContentLayers::BODY.with(ContentLayer::Furniture),
2808            ..MarkdownExportOptions::default()
2809        });
2810        assert_eq!(md, "- nav link\n\nbody\n");
2811    }
2812
2813    #[test]
2814    fn traverse_pictures_prints_the_nested_text_after_the_picture() {
2815        let doc = options_doc();
2816        let (md, _) = doc.export_to_markdown_with_options(&MarkdownExportOptions {
2817            traverse_pictures: true,
2818            ..MarkdownExportOptions::default()
2819        });
2820        assert_eq!(
2821            md,
2822            "# R&amp;D \\_ report\n\nBody a\\_b &lt;tag&gt;\n\nFigure 1\n\n<!-- image -->\n\nField: Name\n\nField: Date\n"
2823        );
2824    }
2825
2826    #[test]
2827    fn escaping_can_be_turned_off_per_kind() {
2828        let doc = options_doc();
2829        let (md, _) = doc.export_to_markdown_with_options(&MarkdownExportOptions {
2830            escape_html: false,
2831            ..MarkdownExportOptions::default()
2832        });
2833        assert_eq!(
2834            md,
2835            "# R&D \\_ report\n\nBody a\\_b <tag>\n\nFigure 1\n\n<!-- image -->\n"
2836        );
2837        let (md, _) = doc.export_to_markdown_with_options(&MarkdownExportOptions {
2838            escape_underscores: false,
2839            ..MarkdownExportOptions::default()
2840        });
2841        assert_eq!(
2842            md,
2843            "# R&amp;D _ report\n\nBody a_b &lt;tag&gt;\n\nFigure 1\n\n<!-- image -->\n"
2844        );
2845        // Code and table cells are never touched (upstream leaves them
2846        // unescaped too, so nothing was escaped there to undo).
2847        let mut doc = DoclingDocument::new("code");
2848        doc.push(Node::Code {
2849            language: None,
2850            text: "a &amp; b \\_ c".into(),
2851            orig: None,
2852            pretty: None,
2853        });
2854        let (md, _) = doc.export_to_markdown_with_options(&MarkdownExportOptions {
2855            escape_html: false,
2856            escape_underscores: false,
2857            ..MarkdownExportOptions::default()
2858        });
2859        assert_eq!(md, "```\na &amp; b \\_ c\n```\n");
2860    }
2861
2862    /// #859 (docling-core 2.103.1): a fence out-lengths every backtick run
2863    /// in the block and a span its text, so neither can be closed early; the
2864    /// readers of the baked spans take the longer form back.
2865    #[test]
2866    fn fences_and_spans_out_length_inner_backticks() {
2867        let code = |text: &str| Node::Code {
2868            language: Some("md".into()),
2869            text: text.into(),
2870            orig: None,
2871            pretty: None,
2872        };
2873        let fence_of = |text: &str| {
2874            let mut doc = DoclingDocument::new("d");
2875            doc.push(code(text));
2876            (doc.export_to_markdown(), doc.export_to_markdown_with(true))
2877        };
2878        assert_eq!(fence_of("x").0, "```\nx\n```\n");
2879        assert_eq!(fence_of("a ` b").0, "```\na ` b\n```\n");
2880        assert_eq!(fence_of("a ``` b").0, "````\na ``` b\n````\n");
2881        assert_eq!(
2882            fence_of("a ``` b ```` c"),
2883            (
2884                "`````\na ``` b ```` c\n`````\n".to_string(),
2885                "`````md\na ``` b ```` c\n`````\n".to_string()
2886            )
2887        );
2888        assert_eq!(code_span("x"), "`x`");
2889        assert_eq!(code_span("a`b"), "``a`b``");
2890        assert_eq!(code_span("a ``` b"), "````a ``` b````");
2891        assert_eq!(code_span("`x"), "`` `x ``");
2892        assert_eq!(code_span("x`"), "`` x` ``");
2893        for (span, text) in [
2894            ("`x`", "x"),
2895            ("``a`b``", "a`b"),
2896            ("`` `x ``", "`x"),
2897            ("````a ``` b````", "a ``` b"),
2898        ] {
2899            assert_eq!(
2900                plain_inline(&format!("see {span} here")),
2901                format!("see {text} here")
2902            );
2903        }
2904        // The plain export prints a folded fence's body unfenced, whatever
2905        // the fence's length.
2906        let mut doc = DoclingDocument::new("d");
2907        doc.push(code("a ``` b"));
2908        assert_eq!(doc.export_to_text(), "a ``` b");
2909        // Streamed and buffered agree on the longer fence.
2910        let mut doc = DoclingDocument::new("d");
2911        doc.add_paragraph("Before.");
2912        doc.push(code("a ``` b ```` c"));
2913        doc.add_paragraph("After.");
2914        assert_stream_matches(&doc, false, ImageMode::Placeholder, &[1, 2]);
2915        assert_stream_matches(&doc, true, ImageMode::Placeholder, &[1, 2]);
2916    }
2917
2918    /// #858: a `mermaid` code item extracted from a drawing takes the
2919    /// place of the drawing's `<!-- image -->` in the placeholder mode —
2920    /// in the buffered export and in a stream cut anywhere around the pair;
2921    /// a picture nothing follows keeps its marker.
2922    #[test]
2923    fn mermaid_code_item_replaces_its_picture_placeholder() {
2924        let picture = || Node::Picture {
2925            caption: None,
2926            caption_href: None,
2927            image: None,
2928            classification: None,
2929            description: None,
2930            caption_parent: Default::default(),
2931            caption_location: None,
2932        };
2933        let mut doc = DoclingDocument::new("d");
2934        doc.add_paragraph("Before.");
2935        doc.push(picture());
2936        doc.push(Node::Code {
2937            language: Some("mermaid".into()),
2938            text: "flowchart TD\n  A --> B".into(),
2939            orig: None,
2940            pretty: None,
2941        });
2942        doc.add_paragraph("After.");
2943        doc.push(picture());
2944        let md = doc.export_to_markdown();
2945        assert_eq!(
2946            md,
2947            "Before.\n\n```mermaid\nflowchart TD\n  A --> B\n```\n\nAfter.\n\n<!-- image -->\n"
2948        );
2949        assert_eq!(doc.export_to_markdown_with(true), md);
2950        for splits in [&[1][..], &[2], &[1, 2], &[2, 3], &[1, 2, 3, 4]] {
2951            assert_stream_matches(&doc, false, ImageMode::Placeholder, splits);
2952            assert_stream_matches(&doc, true, ImageMode::Placeholder, splits);
2953        }
2954        // A stream that ends on the picture still prints it.
2955        let mut doc = DoclingDocument::new("d");
2956        doc.add_paragraph("Only.");
2957        doc.push(picture());
2958        assert_eq!(doc.export_to_markdown(), "Only.\n\n<!-- image -->\n");
2959        assert_stream_matches(&doc, false, ImageMode::Placeholder, &[1]);
2960        assert_stream_matches(&doc, false, ImageMode::Placeholder, &[2]);
2961    }
2962
2963    #[test]
2964    fn image_placeholder_is_configurable() {
2965        let doc = options_doc();
2966        let (md, _) = doc.export_to_markdown_with_options(&MarkdownExportOptions {
2967            image_placeholder: "[figure]".into(),
2968            ..MarkdownExportOptions::default()
2969        });
2970        assert!(md.contains("Figure 1\n\n[figure]\n"), "{md}");
2971        assert!(!md.contains("<!-- image -->"));
2972    }
2973
2974    /// #605: an empty `image_placeholder` prints nothing — no empty block, so
2975    /// no extra blank lines — while the page-break scan still counts the
2976    /// picture as an item. Every expectation is docling-core 2.99's own
2977    /// `export_to_markdown(image_placeholder="", page_break_placeholder=…)`
2978    /// (plus the trailing newline this port always writes).
2979    #[test]
2980    fn empty_image_placeholder_prints_nothing() {
2981        fn picture(caption: Option<&str>) -> Node {
2982            Node::Picture {
2983                caption: caption.map(Into::into),
2984                caption_href: None,
2985                image: None,
2986                classification: None,
2987                description: None,
2988                caption_parent: Default::default(),
2989                caption_location: None,
2990            }
2991        }
2992        fn page(no: usize) -> Node {
2993            Node::PageInfo {
2994                page_no: no,
2995                width: 100.0,
2996                height: 100.0,
2997            }
2998        }
2999        fn para(text: &str) -> Node {
3000            Node::Paragraph { text: text.into() }
3001        }
3002        let options = MarkdownExportOptions {
3003            image_placeholder: String::new(),
3004            ..MarkdownExportOptions::default()
3005        };
3006        // (nodes, page-break placeholder, expected)
3007        let cases: Vec<(Vec<Node>, Option<&str>, &str)> = vec![
3008            (
3009                vec![page(1), para("a"), picture(None), para("b")],
3010                None,
3011                "a\n\nb\n",
3012            ),
3013            (
3014                vec![page(1), para("a"), picture(Some("Figure 1")), para("b")],
3015                None,
3016                "a\n\nFigure 1\n\nb\n",
3017            ),
3018            (
3019                vec![
3020                    page(1),
3021                    para("a"),
3022                    page(2),
3023                    picture(None),
3024                    page(3),
3025                    para("b"),
3026                ],
3027                Some("<!-- pb -->"),
3028                "a\n\n<!-- pb -->\n\n<!-- pb -->\n\nb\n",
3029            ),
3030            (
3031                vec![
3032                    page(1),
3033                    para("a"),
3034                    page(2),
3035                    picture(None),
3036                    page(3),
3037                    para("b"),
3038                ],
3039                Some(""),
3040                "a\n\n\n\n\n\nb\n",
3041            ),
3042            (
3043                vec![page(1), picture(None), page(2), para("b")],
3044                Some("<!-- pb -->"),
3045                "<!-- pb -->\n\nb\n",
3046            ),
3047            (
3048                vec![page(1), picture(None), page(2), para("b")],
3049                Some(""),
3050                "\n\nb\n",
3051            ),
3052            (
3053                vec![page(1), para("a"), page(2), picture(None)],
3054                Some("<!-- pb -->"),
3055                "a\n\n<!-- pb -->\n",
3056            ),
3057        ];
3058        for (nodes, placeholder, expected) in cases {
3059            let mut doc = DoclingDocument::new("t");
3060            doc.page_break_placeholder = placeholder.map(Into::into);
3061            for node in nodes {
3062                doc.push(node);
3063            }
3064            let (md, _) = doc.export_to_markdown_with_options(&options);
3065            assert_eq!(md, expected, "page break {placeholder:?}");
3066            // The streamer agrees at every chunking, one node per push
3067            // included — an all-empty push still owes the next page break.
3068            for size in 1..=doc.nodes.len() {
3069                let mut streamer = MarkdownStreamer::new(false, ImageMode::Placeholder, false)
3070                    .with_export_options(&options)
3071                    .with_page_break_placeholder(placeholder.map(Into::into));
3072                let mut out = String::new();
3073                for chunk in doc.nodes.chunks(size) {
3074                    out.push_str(&streamer.push(chunk, &[]));
3075                }
3076                out.push_str(&streamer.finish());
3077                assert_eq!(
3078                    out, expected,
3079                    "chunks of {size}, page break {placeholder:?}"
3080                );
3081            }
3082        }
3083        // The default placeholder is untouched.
3084        let mut doc = DoclingDocument::new("t");
3085        doc.push(para("a"));
3086        doc.push(picture(None));
3087        doc.push(para("b"));
3088        assert_eq!(doc.export_to_markdown(), "a\n\n<!-- image -->\n\nb\n");
3089    }
3090
3091    /// The streamer takes the same options and its chunks concatenate to the
3092    /// buffered export.
3093    #[test]
3094    fn streamer_matches_buffered_export_with_options() {
3095        let doc = options_doc();
3096        let options = MarkdownExportOptions {
3097            layers: ContentLayers::ALL,
3098            traverse_pictures: true,
3099            escape_html: false,
3100            escape_underscores: false,
3101            image_placeholder: "(img)".into(),
3102            ..MarkdownExportOptions::default()
3103        };
3104        let (buffered, _) = doc.export_to_markdown_with_options(&options);
3105        let mut streamer = MarkdownStreamer::new(false, ImageMode::Placeholder, false)
3106            .with_export_options(&options);
3107        let mut out = String::new();
3108        for chunk in doc.nodes.chunks(2) {
3109            out.push_str(&streamer.push(chunk, &[]));
3110        }
3111        out.push_str(&streamer.finish());
3112        assert_eq!(out, buffered);
3113        assert!(
3114            buffered.contains("(img)") && buffered.contains("R&D _ report"),
3115            "{buffered}"
3116        );
3117    }
3118
3119    /// #902: an escaped star is a literal one in the plain text, and closes
3120    /// no emphasis span around it.
3121    #[test]
3122    fn plain_text_reads_escaped_stars() {
3123        assert_eq!(plain_inline("A\\*\\*\\* GmbH"), "A*** GmbH");
3124        assert_eq!(
3125            plain_inline("**FN \\*0\\*271\\*h** and *h\\*.at*"),
3126            "FN *0*271*h and h*.at"
3127        );
3128    }
3129
3130    /// #613: the plain export of a document holding every decoration the
3131    /// Markdown export writes, and the streamer agreeing with it.
3132    #[test]
3133    fn plain_text_drops_the_markdown_decoration() {
3134        let item = |text: &str, ordered: bool, number: u64, level: u8| Node::ListItem {
3135            ordered,
3136            number,
3137            first_in_list: number == 1 && level == 0,
3138            text: text.into(),
3139            level,
3140            marker: None,
3141            location: None,
3142            split: None,
3143            dclx: None,
3144            href: None,
3145            layer: None,
3146        };
3147        let mut doc = DoclingDocument::new("plain");
3148        doc.add_heading(1, "Title with **bold**");
3149        doc.add_heading(2, "Section");
3150        doc.add_paragraph("Some **bold**, *italic*, ~~gone~~ and `code` with a [link](https://x.org).\nNext line.");
3151        doc.push(item("*one*", false, 1, 0));
3152        doc.push(item("[two](https://y.org)", false, 2, 0));
3153        doc.push(item("nested", true, 1, 1));
3154        doc.push(Node::CheckboxItem {
3155            checked: true,
3156            text: "done".into(),
3157        });
3158        doc.push(Node::Code {
3159            language: Some("rust".into()),
3160            text: "let x = **y**;".into(),
3161            orig: None,
3162            pretty: None,
3163        });
3164        doc.push(Node::Picture {
3165            caption: Some("Figure *1*".into()),
3166            caption_href: None,
3167            image: None,
3168            classification: None,
3169            description: None,
3170            caption_parent: Default::default(),
3171            caption_location: None,
3172        });
3173        doc.push(Node::Caption {
3174            text: "Linked caption".into(),
3175            href: Some("https://z.org".into()),
3176        });
3177        doc.push(Node::Table(Table {
3178            rows: vec![
3179                vec!["**n**".into(), "rich".into()],
3180                vec!["**2**".into(), "a  \nb".into()],
3181            ],
3182            ..Default::default()
3183        }));
3184        doc.add_paragraph("R&amp;D \\_ x");
3185        let text = doc.export_to_text();
3186        assert_eq!(
3187            text,
3188            "Title with bold\n\n\
3189             Section\n\n\
3190             Some bold, italic, gone and code with a link.\nNext line.\n\n\
3191             - one\n- two\n    1. nested\n\n\
3192             - [x] done\n\n\
3193             let x = **y**;\n\n\
3194             Figure 1\n\n\
3195             Linked caption\n\n\
3196             |   n | rich   |\n\
3197             |-----|--------|\n\
3198             |   2 | a b    |\n\n\
3199             R&D _ x"
3200        );
3201
3202        let options = MarkdownExportOptions::plain_text();
3203        let (buffered, _) = doc.export_to_markdown_with_options(&options);
3204        assert_eq!(buffered, format!("{text}\n"));
3205        let mut streamer = MarkdownStreamer::new(false, ImageMode::Placeholder, false)
3206            .with_export_options(&options);
3207        let mut out = String::new();
3208        for chunk in doc.nodes.chunks(3) {
3209            out.push_str(&streamer.push(chunk, &[]));
3210        }
3211        out.push_str(&streamer.finish());
3212        assert_eq!(out, buffered);
3213    }
3214
3215    /// #613: text that only looks like Markdown stays as it is.
3216    #[test]
3217    fn plain_inline_keeps_literal_markers() {
3218        for (input, want) in [
3219            ("**bold** and *it* and ***both***", "bold and it and both"),
3220            ("**[label](https://a.b/c_(d))** end", "label end"),
3221            (
3222                "grant *USE and *OBJMGT authority",
3223                "grant *USE and *OBJMGT authority",
3224            ),
3225            ("2 * 3 * 4", "2 * 3 * 4"),
3226            ("a ** b", "a ** b"),
3227            ("the `quoted’ and `x` term", "the `quoted’ and x term"),
3228            ("see [12] and [docs](u)", "see [12] and docs"),
3229            ("formula $[a](b)$ stays", "formula $[a](b)$ stays"),
3230            ("price $5 and **bold**", "price $5 and bold"),
3231            ("[outer [inner] text](u)", "outer [inner] text"),
3232            ("unclosed **bold", "unclosed **bold"),
3233        ] {
3234            assert_eq!(plain_inline(input), want, "{input}");
3235        }
3236    }
3237}