fix(docs): remove duplicate page titles after mystmd conversion#805
Merged
Conversation
The mystmd migration (#792) gave every page a frontmatter `title:` and demoted the original `#` page heading to `##`. The book-theme renders the frontmatter title as a title-block H1, so each page showed its title twice and the landing page rendered a bare "Home" heading above the content. Drop the redundant frontmatter `title` and promote body headings back one level so MyST extracts the single `#` H1 as the page title. `short_title` still drives the nav on the GHA/style pages; the index keeps a `short_title: Home` nav label. The two packaging guides had a tip/cog block before the heading (which blocks title extraction), so their `#` heading moves to the top. Resolves the "extra Home header" and "duplicated headers" review notes from #801 Assisted-by: ClaudeCode:claude-opus-4.8
`_partials/pyproject.md` opened with an H1 that got inlined mid-page in the two packaging guides, which include it at the `##`-section level. Demote each heading one level so it nests correctly, and add a `rumdl-disable MD041` since the file now starts with an H2 (same pattern as footer.md). Assisted-by: ClaudeCode:claude-opus-4.8
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🤖 AI text below 🤖
Problem
Follow-up to #801. On the mystmd site every page showed its title twice, and the landing page rendered a bare Home heading above the content (review note).
Root cause
The mystmd migration (#792) gave every page a frontmatter
title:and demoted the original#page heading to##. The book-theme renders the frontmattertitleas a title-block H1, so the##heading below it became a visible duplicate. Onindex.mdthe title wasHome, so the page led with a stray "Home" H1.Fix
For each page, drop the redundant frontmatter
titleand promote body headings back up one level. MyST then extracts the single#H1 as the page title (rendered once in the title block), and sections nest correctly beneath it.short_titlestill drives the nav labels on the GHA/style pages; their title block now shows the fuller heading instead of the terse duplicate.index.mdkeeps ashort_title: Homenav label while its title becomes Scientific Python Library Development Guide.packaging_simple.md/packaging_compiled.mdhad atip/cog block before the heading (which blocks MyST title extraction), so their#heading moves to the top.Verification
mystmdand walked the rendered mdast for all pages: every page has a correct title and zero body headings duplicating it.prek -apasses fully, includingrumdl(MD041),blacken-docs, and Cog the pages (the cog reorder inpackaging_compiledregenerates cleanly).The other review notes are theme work (tab selection, configurable highlight scheme, three-way theme toggle) tracked separately; the site already renders the nav/outline table of contents.
📚 Documentation preview 📚: https://scientific-python-cookie--805.org.readthedocs.build/