[DanielNg0729]

Hi maintainers, this PR makes the CLI write portable image links in referenced mode. After this change, you can move or share the output folder and the images still open.

Issue resolved by this Pull Request:
Resolves #3678

Summary

With --image-export-mode referenced, export_documents calls save_as_markdown(filename=..., image_mode=...) without artifacts_dir. The JSON, YAML and HTML exports do the same. docling-core then chooses the link style from the shape of the output path (DoclingDocument._get_output_paths):

--output	Images written to	Link in the Markdown
. (default)	doc_artifacts/	doc_artifacts/image_….png
out	out/out/doc_artifacts/	out/doc_artifacts/image_….png
D:\out	D:\out\doc_artifacts\	file:///D:/out/doc_artifacts/image_….png

• An absolute output path gives absolute file:/// links. The images do not load after you move the folder or open it on another machine.
• A relative output path is used twice, so the images go to out/out/doc_artifacts/. This is docling-core#362.

Changes

• A new helper, _artifacts_dir(output_path) in docling/cli/export_utils.py, returns the relative folder <name>_artifacts. This is the same name as the docling-core default, so the folder layout does not change.
• export_documents gives this folder to save_as_json, save_as_yaml, save_as_html (normal and split-page) and save_as_markdown. When artifacts_dir is relative, docling-core puts the folder next to the output file and links the images relative to that file. docling-core#399 suggested this approach.
• convert-remote uses the same export_documents, so it also gets the fix.
• The --image-export-mode help text and docs/reference/cli.md now say where the images go.

The fix is only in the CLI. It needs no new docling-core release, because all four save methods accept artifacts_dir since docling-core 2.98 (the current minimum pin). The Python API does not change: doc.save_as_markdown("/abs/doc.md", image_mode=ImageRefMode.REFERENCED) still writes absolute links. That fix must be made in docling-core, for example with docling-core#363.

Behaviour change for JSON and YAML

A JSON or YAML file written to an absolute --output now has relative image URIs. Today you get the same result with the default --output .. docling-core opens a relative URI from the current directory (ImageRef.pil_image). So to load the images again from such a file (with enable_local_fetch=True), you must run from the output folder. Do you prefer to keep absolute URIs for JSON and YAML? If so, I can limit the change to Markdown and HTML.

Known limit: HTML on Windows

docling-core 2.100.0 writes the HTML src with quote(str(uri)). On Windows the relative link is then doc_artifacts%5Cimage_….png. docling-core#772 fixes this on docling-core main, but no release has it yet. On main, the Windows link is the full absolute path, which is also encoded (C%3A%5CUsers%5C…), so this PR does not make it worse. The Markdown link is correct on all platforms, and the HTML link is correct on Linux and macOS.

Checklist:

• Documentation has been updated, if necessary.
• Examples have been added, if necessary.
• Tests have been added, if necessary.

[github-actions]

✅ DCO Check Passed

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

[mergify]

Merge Protections

🟢 Merge protection satisfied — ready to merge.

Show 1 satisfied protection

🟢 Enforce conventional commit

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)(?:\(.+\))?(!)?:

[github-actions]

AI triage (advisory)

Checked commit 581207cfe3. The analysis read the diff only. It did not run code from this pull request.

The PR adds a _artifacts_dir helper in export_utils.py and passes it to all save_as_* calls in main.py, so --image-export-mode referenced writes a relative <name>_artifacts folder next to the output file instead of an absolute or doubled path.

Topic labels added: enhancement, CLI.

CI safety: no concern found. A maintainer must still approve CI.

2 related pull request(s) in the same code

PR	State	Signal	Assessment
#4496	open	changes the same code	related: Both PRs edit main.py and docs/reference/cli.md, but PR 4496 adds a new --extract-form-fields CLI option for AcroForm extraction and does not touch image export or _artifacts_dir.
#4819	open	changes the same code	related: Both PRs edit main.py and both are by the same author, but PR 4819 refactors the --version callback for speed and does not overlap the image-export changes.

_{The ai:* labels are advisory. They do not approve CI and they do not add tests:full. A new push runs this check again.}

[github-actions]

AI first review (advisory): no blocker found

This review covers the full diff at 581207cfe3. It read the code and did not run it.

The fix correctly passes a relative artifacts_dir to every save_as_* call site so docling-core stores images next to the output file and links them with a relative path. The installed docling-core 2.100.0 accepts artifacts_dir on all four methods and its _get_output_paths logic correctly resolves a relative dir against filename.parent. Tests cover both relative and absolute --output paths and the --output-file case. No blocking issues found; verify CI is green.

_{A maintainer makes the merge decision. This review never approves the pull request.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!