fleischwolf_core/document.rs
1//! The unified document representation.
2
3use crate::markdown::{to_markdown, to_markdown_images};
4use crate::ImageMode;
5
6/// The unified, format-agnostic document produced by every backend.
7///
8/// This is the heart of docling: backends parse their source format into a
9/// `DoclingDocument`, and serializers turn it back into Markdown, HTML, JSON,
10/// etc. Phase 0 uses a flat sequence of [`Node`]s; the production schema will
11/// match docling-core's body-tree-with-references layout.
12#[derive(Debug, Clone, PartialEq)]
13pub struct DoclingDocument {
14 /// Logical document name (usually the input file stem).
15 pub name: String,
16 /// Top-level content, in reading order.
17 pub nodes: Vec<Node>,
18 /// Default Markdown export mode for [`Self::export_to_markdown`]. `false`
19 /// (the default) reproduces docling's legacy output byte-for-byte; `true`
20 /// emits cleaner, more conformant Markdown. Set by `DocumentConverter`.
21 pub strict_markdown: bool,
22 /// Emit tables in the compact `| a | b |` / `| - | - |` form rather than
23 /// docling-core's width-padded GitHub serializer. The PDF backend sets this
24 /// (its committed groundtruth corpus predates the padded serializer); DOCX/HTML
25 /// leave it `false` to match current published docling.
26 pub compact_tables: bool,
27}
28
29/// A single piece of document content.
30#[derive(Debug, Clone, PartialEq)]
31pub enum Node {
32 /// A heading. `level` is 1-6.
33 Heading { level: u8, text: String },
34 /// A run of body text.
35 Paragraph { text: String },
36 /// A single list item at the given nesting `level` (0 = top). For ordered
37 /// items, `number` is the display number (honoring the list's `start`); it
38 /// is unused for unordered items. `first_in_list` marks the first item of a
39 /// list so the serializer can blank-line-separate adjacent sibling lists.
40 ListItem {
41 ordered: bool,
42 number: u64,
43 first_in_list: bool,
44 text: String,
45 level: u8,
46 },
47 /// A fenced code block.
48 Code {
49 language: Option<String>,
50 text: String,
51 },
52 /// A table. The first row is treated as the header.
53 Table(Table),
54 /// A picture/figure, with an optional caption and (when a backend extracts
55 /// it) the embedded image itself.
56 Picture {
57 caption: Option<String>,
58 image: Option<PictureImage>,
59 },
60 /// A logical grouping of child nodes (e.g. a list, a section).
61 Group { label: String, children: Vec<Node> },
62}
63
64/// An extracted picture's raw encoded bytes plus its mimetype and pixel size —
65/// the fleischwolf analogue of docling-core's `ImageRef`.
66#[derive(Debug, Clone, PartialEq)]
67pub struct PictureImage {
68 /// e.g. `image/png`, `image/jpeg`.
69 pub mimetype: String,
70 pub width: u32,
71 pub height: u32,
72 /// The image file bytes, exactly as embedded (PNG/JPEG/…).
73 pub data: Vec<u8>,
74}
75
76impl PictureImage {
77 /// A `data:` URI for the image (`data:<mimetype>;base64,<…>`).
78 pub fn data_uri(&self) -> String {
79 format!(
80 "data:{};base64,{}",
81 self.mimetype,
82 crate::base64::encode(&self.data)
83 )
84 }
85}
86
87/// A simple row-major table. `rows[0]` is the header row.
88#[derive(Debug, Clone, PartialEq)]
89pub struct Table {
90 pub rows: Vec<Vec<String>>,
91}
92
93impl DoclingDocument {
94 /// Create an empty document with the given name.
95 pub fn new(name: impl Into<String>) -> Self {
96 Self {
97 name: name.into(),
98 nodes: Vec::new(),
99 strict_markdown: false,
100 compact_tables: false,
101 }
102 }
103
104 /// Append a node.
105 pub fn push(&mut self, node: Node) {
106 self.nodes.push(node);
107 }
108
109 /// Convenience: append a heading.
110 pub fn add_heading(&mut self, level: u8, text: impl Into<String>) {
111 self.push(Node::Heading {
112 level,
113 text: text.into(),
114 });
115 }
116
117 /// Convenience: append a paragraph.
118 pub fn add_paragraph(&mut self, text: impl Into<String>) {
119 self.push(Node::Paragraph { text: text.into() });
120 }
121
122 /// Serialize the document to Markdown.
123 ///
124 /// The Rust equivalent of docling-core's
125 /// `DoclingDocument.export_to_markdown()`. Uses [`Self::strict_markdown`] to
126 /// pick between docling-legacy output (default) and the cleaner, more
127 /// conformant variant.
128 pub fn export_to_markdown(&self) -> String {
129 to_markdown(self, self.strict_markdown)
130 }
131
132 /// Serialize to Markdown, explicitly choosing the mode regardless of
133 /// [`Self::strict_markdown`]. `strict = true` produces cleaner, more
134 /// conformant Markdown (code-fence languages preserved, no inline-run
135 /// spacing artifacts); `strict = false` reproduces docling's legacy output.
136 pub fn export_to_markdown_with(&self, strict: bool) -> String {
137 to_markdown(self, strict)
138 }
139
140 /// Serialize to docling-core's native JSON wire format (`DoclingDocument`
141 /// schema), pretty-printed — the Rust equivalent of
142 /// `DoclingDocument.export_to_dict()` / `save_as_json()`. The output loads
143 /// back into Python docling-core and round-trips to the same Markdown.
144 pub fn export_to_json(&self) -> String {
145 serde_json::to_string_pretty(&crate::json::to_json(self))
146 .expect("DoclingDocument JSON is always serializable")
147 }
148
149 /// Serialize to Markdown with an explicit picture [`ImageMode`] (mirrors
150 /// docling's `image_mode`). Returns the Markdown and, for
151 /// [`ImageMode::Referenced`], the `(relative-path, bytes)` of each image the
152 /// caller should write next to the Markdown file. `artifacts_dir` is the
153 /// directory name used in referenced links.
154 pub fn export_to_markdown_with_images(
155 &self,
156 image_mode: ImageMode,
157 artifacts_dir: &str,
158 ) -> (String, Vec<(String, Vec<u8>)>) {
159 to_markdown_images(self, self.strict_markdown, image_mode, artifacts_dir)
160 }
161}