[JackyHsu-X]

Related Issues

No existing issue. This is separate from #13104 (tabs after the header prefix) and #13344 (code fences).

Proposed Changes:

MarkdownHeaderSplitter ignores valid ATX headings such as ## Install, merging their sections and losing header metadata used for retrieval. Accept up to three leading spaces, as specified by CommonMark, while preserving the original content. Four-space and tab-indented lines remain content.

Add regression coverage for header hierarchy, page numbers, both keep_headers modes, secondary splitting, selected levels, and code-block exclusion. Update the docstring, docs, and release note.

How did you test it?

On Windows / Python 3.12, using the project's Hatch environments:

• Original source with the new tests: 13 failed, 79 passed. Fixed splitter suite: 92 passed.
• Splitter, DocumentWriter, and sync/async FilterRetriever suites: 121 passed, 2 integration tests deselected.
• Real sync/async indexing and section-filtering smoke checks passed.
• Full hatch run fmt-check, scoped mypy on both changed Python files, and all applicable pre-commit hooks passed.

The full repository test suite, live integrations, and documentation build were not run.

Notes for the reviewer

Fully generated with Codex at the author's request. Codex ran the local checks reported above.

Checklist

• Read the contributing guidelines and code of conduct.
• Added regression tests, updated the docstring and documentation.
• Used a conventional PR title and added a release note.
• Ran pre-commit hooks and fixed the reported issues.
• Related issue update: N/A (no existing issue).

[vercel]

@JackyHsu-X is attempting to deploy a commit to the deepset Team on Vercel.

A member of the Team first needs to authorize it.

[HaystackBot]

Hi @JackyHsu-X, thanks a lot for your contribution! 🙏

We noticed that the Contributor License Agreement (CLA) check (license/cla) hasn't passed yet, so we've temporarily moved this PR to draft and paused the review assignment.

To get your PR reviewed, please sign the CLA via the link in the license/cla check below (or in the CLA bot comment). As soon as the check turns green, this PR will automatically be marked ready for review again and a reviewer will be re-assigned.

[CLAassistant]

All committers have signed the CLA.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[HaystackBot]

Thanks for signing the CLA, @JackyHsu-X! 🎉 This PR is now ready for review again and the reviewer has been re-assigned.

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
haystack/components/preprocessors
markdown_header_splitter.py
Project Total

This report was generated by python-coverage-comment-action

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
haystack-docs	Ready	Preview	Oct 27, 2026 10:47am UTC

[davidsbatista]

thanks for the contribution