Description
During a recent contribution to the main docling repository regarding backend parsing and layout spacing fixes, I discussed how headers and footers are currently treated by the parser. They are correctly categorized structurally as FURNITURE.
Currently, during export or markdown serialization, these elements are omitted by default to ensure the output remains uncluttered by repetitive page margins. However, for certain documents (such as official templates, 3GPP standards, or heavily structured agreements), the information contained in the header or footer carries meaningful document metadata or versioning context that users may want to include in the final Markdown output.
Solution
To separate parsing concerns from serialization, I would like to introduce a configurable option within the markdown serializers (under the transforms logic in docling-core) to control whether and how headers and footers are serialized.
As suggested by the maintainers, I propose implementing a three-tiered enum configuration option:
none (Default): Skips all headers and footers entirely. This preserves the current existing behavior.all: Serializes every header and footer element precisely where it appears sequentially across the page splits.distinct: Employs a deduplication strategy. A header or footer element is serialized only once in the document, appearing the very first time its unique text content is encountered by the serializer. This captures template metadata perfectly without repeating it endlessly across a multi-page document.
An alternative was attempting to conditionally override the element categorization at the backend parser layer itself, but this was rejected because it violates the separation of concerns and ruins the structural purity of the DoclingDocument object model.
Additional Context
This feature request directly follows the discussion and architectural recommendations laid out during the review of the MS Word backend updates.
I would be more than happy to claim this issue and submit a pull request implementing this configuration if the maintainers agree with the proposed roadmap!
Description
During a recent contribution to the main
doclingrepository regarding backend parsing and layout spacing fixes, I discussed how headers and footers are currently treated by the parser. They are correctly categorized structurally asFURNITURE.Currently, during export or markdown serialization, these elements are omitted by default to ensure the output remains uncluttered by repetitive page margins. However, for certain documents (such as official templates, 3GPP standards, or heavily structured agreements), the information contained in the header or footer carries meaningful document metadata or versioning context that users may want to include in the final Markdown output.
Solution
To separate parsing concerns from serialization, I would like to introduce a configurable option within the markdown serializers (under the
transformslogic indocling-core) to control whether and how headers and footers are serialized.As suggested by the maintainers, I propose implementing a three-tiered enum configuration option:
none(Default): Skips all headers and footers entirely. This preserves the current existing behavior.all: Serializes every header and footer element precisely where it appears sequentially across the page splits.distinct: Employs a deduplication strategy. A header or footer element is serialized only once in the document, appearing the very first time its unique text content is encountered by the serializer. This captures template metadata perfectly without repeating it endlessly across a multi-page document.An alternative was attempting to conditionally override the element categorization at the backend parser layer itself, but this was rejected because it violates the separation of concerns and ruins the structural purity of the
DoclingDocumentobject model.Additional Context
This feature request directly follows the discussion and architectural recommendations laid out during the review of the MS Word backend updates.
I would be more than happy to claim this issue and submit a pull request implementing this configuration if the maintainers agree with the proposed roadmap!