docling-project / docling-project/docling

Custom Output Naming

Open
#2,397 1 comment 0 reactions 0 assignees View on GitHub
enhancement triage/close-stale
Dominant language
Python
Stars
66.4k
Forks
4.8k
Avg merge
2d 21h
Merged PRs (30d)
84

Description

### Feature: Custom Output Naming

I've found `docling` to be great, but simply using the basename of whatever URI we're hitting isn't always ideal.
I'd like to be able to have `docling` save documents according to some information within the document, or to include additional parts of the URI.

1. URI-based Enhancements
* Additional Folders/Namespaces
* domain.tld/2025-10-01/post.html -> `2025-10-01_post.md` vs `post.md`
* "Always" and "When Name < N Characters in Length"
* Domain Prefixing
* domain_one.tld/some/path/How_to_Win.html -> `domain_one_tld_How_to_Win.md`
* domain_two.tld/some/path/How_to_Win.html -> `domain_two_tld_How_to_Win.md`
* Domain Bucketing
* `docling --output=~/Documents domain.tld/2025-10-01/post.html`
* --> `~/Documents/domain.tld/post.md`
* Preserving "Extension"
* Define a list of common/known web extension (ie: .html, .php)
* Only trim strings for these values, not "everything after the last dot".
1. Metadata-based Enhancements
* Use `` for naming instead of file basename.
* Fallback on URI-based naming if not available
* LLM naming
* Allow the LLM to come up with a title for the document.
1. Date-based Enhancements
* Allow custom `date` timestamps to be used when naming the output.
1. Manual
* Expose `--filename`
* Relative to `--output` or CWD
* Absolute and bypass `--output`

We should also have the option of normalizing/sanitizing this output string:

* Special Character -> `_`
* Space and `-` -> `_`
* Emoji / Extended Unicode -> `_`

#### Use Case

`docling` is great, until you grab a document and it's named `aarch64.md`, and then you're afraid you might blow it away with another document with a similar name. I am looking for a way to help prevent name clashing, while not asking for a "versioning" or "backup" feature (though, I do think that would also be helpful). While this could be used to help with clashing, the primary goal is to allow better/custom naming of file outputs.

I checked `docling --help`, but I did not see anything that would help me accomplish any of this.
I primarily use `docling` via it's CLI implementation.

#### Examples

1. `https://csrc.nist.gov/pubs/fips/203/final`
* I'd like to be able to grab this as `203_final`
1. `https://doi.org/10.6028/NIST.FIPS.203`
* Here, the file is downloaded as `NIST.FIPS`, which means they clash
1. `https://xkfan.github.io/cross-toolchain/aarch64.html`
* This doesn't result in a valid toolchain, but it is an example document.

### Alternatives
I could fire off and request the page data myself, extract `<title>` and then rename everything... but...
1. I'd need to know the file(s) generated by `docling`
1. It'd be hairy and hacky
1. `docling` is already doing a great job with what it does, see if it makes sense to implement within

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.