Render title headers at their final levels - #324
Merged
Conversation
Reference titles style object names through the doc-object-name span. Assert that span instead of the removed inline style attribute.
Five post-render rewrites cannot match current HTML: object names are wrapped in spans, the parenthesis rewrite has no effect, the targeted section-heading level is absent, title wrapping searches for markup produced later, and the inline font duplicates the stylesheet. Remove them. Rendered reference HTML changes only by losing the redundant inline style.
Two post-render transforms shifted object-page headings. The file-wide transform also changed navigation and footer headings, while the main-content transform demoted the title. Pages therefore rendered the title at h2, sections at h4, and members at h5. Remove the file-wide transform. Keep the title at h1 and shift only its sections and members to h2 and h3. Scope the compact title style to API object pages.
Match the title class within any class list so Quarto's additional display classes cannot expose the title to the heading shift. Add a Python-reference body class and scope the compact title rule to it. MCP pages share the general API page class but retain their standard title size. Extend the heading test to cover member headings.
Require every reference-index group heading to render at h2, directly below the h1 page title.
Reference, CLI and MCP pages rendered both the page title and the secondary navigation label as h1. Render the navigation label as h5 and target its styles and status icon by class rather than heading tag. Use one helper to nest object-page and reference-index headings below their titles. Scope compact title sizing to Python object pages, excluding the reference index.
Count page-level sections and class members independently so a Parameters section cannot satisfy the member coverage guard. Add the mixed-docstring fixture, skip packages without members, and require the full fixture set to exercise the h3 assertion. Restrict section checks to level2 so member-nested sections are excluded. Remove requirement identifiers from the test names.
Disable the site-wide heading shift on API object pages and the reference index. Render titles at h1, docstring sections at h2, and members at h3 without post-render compensation. Update fallback docstring sections and member separators to use those final levels. Raise the table-of-contents depth to include members and subtitled index sections.
Bootstrap adds a top margin to the new h5 navigation label, moving it below the sidebar toggle. Override that margin with the same importance as Bootstrap's rule.
Extend the heading hierarchy test from main content to the complete document. Each object page must contain one h1 page title, while the secondary navigation label remains h5.
Keep subtitle-only reference sections in generated configuration instead of renaming them Untitled. They now render at h3 and appear in the sidebar and table of contents beside h2 titled sections. Render fallback docstring sections at h4 inside h3 class members and at h2 for top-level objects. Add rendered fixtures and assertions for both paths.
Use a section's subtitle when its title is absent while generating llms.txt, the AI guide and the skill overview. Subtitle-only sections now retain their headings instead of merging into the preceding section.
Fallback translators process the same member in sequence. After the first emits an h4 section, the next must still recognise member context instead of returning to h2. Treat any preceding heading at h3 or deeper as member context. Add a fixture whose method exercises field and bold-section fallbacks together.
Update the synthetic package metadata and README to describe four titled sections and one subtitled section.
Verify that subtitle-only sections keep their own headings in llms.txt, llms-full.txt and skill.md. Check the section body so an entry under the preceding heading cannot pass. Verify that class pages contain one solid rule after the member summary and one dotted rule between each pair of members.
Quarto renders secondary navigation as a breadcrumb nav when breadcrumbs are enabled and as a bare h1 when they are disabled. Replace either form with the h5 navigation label and remove any duplicate breadcrumb in the title block. Use the shared replacement for API, MCP and CLI pages. Add a site-wide no-breadcrumb fixture that requires one h1 page title and the h5 navigation label.
CLI command pages wrote a body title in addition to the front matter title. Remove the duplicate, disable heading shifts on CLI pages, and render body sections at h2. MCP pages retain the site-wide shift, so write their body sections one level deeper. Add rendered coverage for CLI and MCP object pages and indexes.
CLI command titles wrap the command name in a span. Read the complete h1 text when building the navigation label instead of falling back to a filename-derived name. Process nested command pages recursively. Update sidebar assertions for the labelled CLI index entry and verify labels on flat and nested pages.
Top-level docstring sections render at h2, while sections inside members render at h4. Target the shared section class instead of a heading tag so standard and warning styles apply at either depth.
Class member headings require a table-of-contents depth of 3. Read the merged depth from generated Quarto configuration or source site configuration, pass it to each page, and add an override only when the site setting is shallower. Apply the same rule to subtitle headings on the reference index. Preserve user-configured depths above 3 and verify that class members appear in the rendered table of contents.
MCP pages retain the site-wide heading shift because disabling it prevents Quarto from hoisting the marked title and creates a duplicate title. Record why source sections start one level deeper than API reference sections.
When a reference section has no title, display its subtitle in great-docs scan --verbose instead of Untitled. This matches the rendered index and other generated outputs.
Every reference index and API page now carries a page-kind class plus that class prefixed by its family: doc-reference with doc-py-reference, doc-mcp-reference or doc-cli-reference, and doc-api-page with doc-py-api-page, doc-mcp-api-page or doc-cli-api-page. MCP object pages previously carried no family class, so a style could reach them only by excluding the other families. Python object pages and the Python reference index shared one class, which forced the compact title rule to match on two classes and left the index carrying a class no rule used. Drop doc-reference-index, which marked the same three pages as doc-reference and nothing else. The copy-page widget now skips index pages by that class.
has2k1
changed the title
rich-iannone
self-requested a review
August 19, 2026 20:06
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
2 participants
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.
This PR corrects the heading structure of generated reference pages. Object pages previously rendered the title at
h2, docstring sections ath4, and members ath5, and every page carried twoh1elements: the page title and the secondary navigation label. Two post-render transforms caused the shift, one of which also rewrote navigation and footer headings. Headings are now emitted at their final levels during rendering rather than corrected afterwards.The PR also introduces
doc-*-referenceanddoc-*-api-pageclasses to disambiguate the reference and api pages,<body>classesdoc-referencedoc-py-referencedoc-referencedoc-mcp-referencedoc-referencedoc-cli-referencedoc-api-pagedoc-py-api-pagedoc-api-pagedoc-mcp-api-pagedoc-api-pagedoc-cli-api-pageBreaking Change
The title styling rule moves from
h2.titleto.doc-py-reference h1.title, because the title is now genuinely anh1. The renderer emits a newdoc-py-referencebody class on API reference pages so the rule can target them specifically instead of matching everyh1.titleon the site.