Skip to content

fix(docs): remove duplicate page titles after mystmd conversion#805

Merged
henryiii merged 2 commits into
mainfrom
fix/docs-heading-duplication
Jun 15, 2026
Merged

fix(docs): remove duplicate page titles after mystmd conversion#805
henryiii merged 2 commits into
mainfrom
fix/docs-heading-duplication

Conversation

@henryiii

@henryiii henryiii commented Jun 15, 2026

Copy link
Copy Markdown
Collaborator

🤖 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 frontmatter title as a title-block H1, so the ## heading below it became a visible duplicate. On index.md the title was Home, so the page led with a stray "Home" H1.

Fix

For each page, drop the redundant frontmatter title and 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_title still drives the nav labels on the GHA/style pages; their title block now shows the fuller heading instead of the terse duplicate.
  • index.md keeps a short_title: Home nav label while its title becomes Scientific Python Library Development Guide.
  • packaging_simple.md / packaging_compiled.md had a tip/cog block before the heading (which blocks MyST title extraction), so their # heading moves to the top.

Verification

  • Built with mystmd and walked the rendered mdast for all pages: every page has a correct title and zero body headings duplicating it.
  • prek -a passes fully, including rumdl (MD041), blacken-docs, and Cog the pages (the cog reorder in packaging_compiled regenerates cleanly).
  • The diff only touches headings and frontmatter — no prose or code changes.

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/

henryiii added 2 commits June 15, 2026 12:21
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
@henryiii henryiii merged commit ee56fe2 into main Jun 15, 2026
7 checks passed
@henryiii henryiii deleted the fix/docs-heading-duplication branch June 15, 2026 16:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant