Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

MarkdownHeaderSplitter treats headings inside longer closing fences as headers

Open Beginner friendly
  • Is something wrong?
#12,954 2 comments 0 reactions 1 assignee View on GitHub

Maintainers usually reply within 1 day

@julian-risch is already working on this.

Since Sep 27, 2026.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
82/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
python
Domain
backend, testing-qa

Research direction

Start at the MarkdownHeaderSplitter entry point and its _code_block_pattern, then reproduce the issue with the supplied Python example. Update the fence matching so longer backtick and tilde closers are excluded from header matches, and add regression coverage for longer and equal-length closers plus the real header after the block.

Written by the indexing model from the issue text.

Description

Problem

MarkdownHeaderSplitter excludes headers inside fenced code blocks only if the closing fence has exactly the same length as the opening fence. Markdown permits a closing fence of the same type with at least as many fence characters. With a longer valid closing fence, the splitter treats code comments as document headers and cuts the code block apart.

Reproduction

On current main:

from haystack import Document
from haystack.components.preprocessors import MarkdownHeaderSplitter

text = "# Intro\nBody\n````python\n# fake\n`````\n## Real\nEnd\n"
result = MarkdownHeaderSplitter().run(documents=[Document(content=text)])
print([doc.meta["header"] for doc in result["documents"]])

Actual: ['Intro', 'fake', 'Real']. Expected: ['Intro', 'Real']. I ran it twice with identical results. Replacing the five-backtick closer with a four-backtick closer gives the expected result. The same failure occurs with four opening tildes and five closing tildes.

The current _code_block_pattern uses a backreference to the opening fence, requiring equal lengths. The CommonMark rule is a closing fence of the same type with at least the opening length: https://spec.commonmark.org/0.31.2/#fenced-code-blocks .

Suggested scope

Recognize longer closing fences when excluding code blocks from header matches, while keeping unrelated heading and secondary-split behavior unchanged. Regression tests should cover longer backtick and tilde closers, equal-length closers, and the real header after the block. This should not require a public API change. I did not find a matching open/closed issue or PR and can prepare a patch once the current Haystack PR queue clears.

Dominant language
Python
Stars
26.6k
Forks
3.2k
Avg merge
1d 13h
Merged PRs (30d)
263

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from deepset-ai/haystack

All issues in deepset-ai/haystack

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.