sphinx-doc / sphinx-doc/sphinx
How TocTree handles pages with multiple H1 headers
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Today I just spent a lot of time figuring out why shinx was ignoring my custom label in a toctree and putting the first H1 title of the linked page instead of the custom label.
I figured out it was because the linked page had several H1 titles in it, which in my opinion should not be a problem...
Illustration
was rendered as :
"Markdown Cheatsheet" is the first of several H1 Title in my
markdown_cheatsheet_viewpage
instead of :
which is the result I get when I make sure that there only one H1 title in the page...
I can work around this, but to me this should not be the expected behavior, and is probably easy to fix.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the TocTree/toctree behavior with the markdown_cheatsheet_view page containing multiple H1 headers, using the screenshots as the expected-versus-actual reference. Trace how the linked page title is selected and ensure the custom label remains effective; done means the illustrated custom label is rendered even when the page has several H1 titles.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown, python
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100