docling-project / docling-project/docling-core

[Feature Request] Add configurable serialization options for headers and footers in Markdown output

Open
#665 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
HTML
Stars
282
Forks
214
Avg merge
2d 15h
Merged PRs (30d)
21

Description

## 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!

Contributor guide

Open the contributing guide

Research direction

Start by locating the Markdown serializers under the transforms logic in docling-core and inspect how FURNITURE elements are currently filtered. Trace how elements are ordered across page splits, then define the enum behavior for none, all, and distinct; done means the default remains unchanged and each option produces the requested header and footer output.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.