feat: add artifacts_dir parameter to export_to_markdown and export_to_html

[olijacklu]

Related to docling-project/docling#3094

Summary

• Added artifacts_dir parameter to export_to_markdown() and export_to_html()
• When provided with ImageRefMode.REFERENCED, images are automatically saved to the specified directory
• Reuses existing _with_pictures_refs() method

Usage

markdown = doc.export_to_markdown(
    image_mode=ImageRefMode.REFERENCED,
    artifacts_dir="./images"
)

Future feature

I also reference this feature in my issue but I haven't added it for now (let me know if you think it could be worth it):

• image_path_prefix parameter to allow custom paths in the output (e.g., for CDN URLs or web server paths)

[github-actions]

✅ DCO Check Passed

Thanks @olijacklu, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

[dosubot]

Related Documentation

1 document(s) may need updating based on files changed in this PR:

Docling

Content Layers

View Suggested Changes

@@ -62,6 +62,32 @@
 
 This ensures that both the main body and any detected headers or footers are present in the exported file.
 
+### Saving Images to a Directory
+
+When exporting to Markdown or HTML with `ImageRefMode.REFERENCED`, you can use the `artifacts_dir` parameter to automatically save images to a specified directory:
+
+```python
+from docling_core.types.doc.document import ImageRefMode
+
+# Export to Markdown with images saved to a directory
+markdown = doc.export_to_markdown(
+    image_mode=ImageRefMode.REFERENCED,
+    artifacts_dir="./images"
+)
+with open("output.md", "w") as f:
+    f.write(markdown)
+
+# Export to HTML with images saved to a directory
+html = doc.export_to_html(
+    image_mode=ImageRefMode.REFERENCED,
+    artifacts_dir="./images"
+)
+with open("output.html", "w") as f:
+    f.write(html)
+```
+
+The images are automatically extracted and saved to the specified directory, with the output referencing the saved image files.
+
 The `export_to_text()` method produces clean plain text without Markdown decoration (no heading markers `#`, bold/italic markers, or hyperlink syntax), while still preserving list bullets, ordered list numbers, and table separators for readability. The `export_to_vtt()` method serializes documents with TrackSource data to valid WebVTT format with configurable timestamp and voice tag formatting.
 
 All four export methods (`export_to_text()`, `export_to_markdown()`, `export_to_html()`, `export_to_vtt()`) support the `included_content_layers` parameter:
@@ -70,6 +96,9 @@
 Additionally, `export_to_text()`, `export_to_markdown()`, and `export_to_html()` support:
 - `page_no`: Optional[int] = None  
 - `page_break_placeholder`: Optional[str] = None
+
+The `export_to_markdown()` and `export_to_html()` methods also support:
+- `artifacts_dir`: Optional[Union[str, Path]] = None – When provided with `ImageRefMode.REFERENCED`, images are automatically saved to the specified directory and referenced in the output
 
 The `export_to_vtt()` method has additional WebVTT-specific parameters:
 - `omit_hours_if_zero`: bool = False – If True, omit hours when they are 0 in the timings (e.g., "00:11.000" instead of "00:00:11.000")

[Accept] [Decline]

Note: You must be authenticated to accept/decline updates.

^{How did I do? Any feedback?}  

[codecov]

Codecov Report

❌ Patch coverage is 71.42857% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
docling_core/types/doc/document.py	71.42%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[olijacklu]

Is the codecov check blocking or can this be merged? Happy to add any tests if needed

[olijacklu]

@PeterStaar-IBM is this ok to merge?

[olijacklu]

@PeterStaar-IBM @vagenas fixed changes