RDoc-3631 Panel headings are missing from TOC - #2659
Merged
ppekrol merged 1 commit intoSep 11, 2026
Conversation
Docusaurus builds the right-hand TOC at MDX compile time and its remark/toc plugin only collects Markdown heading nodes (plus TOC slices of imported .mdx partials). `<Panel heading="...">` is a JSX prop, so 1733 panel headings across 400 current-version pages never reached the TOC - 70 pages had an empty "In this article" box. Add a `remark-panel-headings` plugin, registered as `beforeDefaultRemarkPlugins` on every content instance, which hoists the prop into a real heading node before the default `headings` and `toc` plugins run. The anchor id is pre-set with the slug the component used to compute at render time, and `remark/headings` honours it, so every panel anchor stays valid (github-slugger would have rewritten 175 of them). Heading ids are now a build-time concern only: `Panel` renders the hoisted heading it receives as its first child and knows nothing about ids or the TOC. A heading the plugin cannot hoist (an expression instead of a plain string) is reported with its file path; no such panel exists in the content today. Panel ids also take part in per-file dedup now, so a panel heading that duplicates a Markdown heading on the same page gets a `-1` suffix instead of a duplicate id (4 pages). The links that pointed at the shared id resolved to the first occurrence before and still do.
Lwiel
approved these changes
Sep 10, 2026
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
3 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.
Issue link
https://issues.hibernatingrhinos.com/issue/RDoc-3631
Additional description
Docusaurus builds the "In this article" list at compile time and only looks at Markdown headings.
<Panel heading="...">is a JSX prop, so panel headings were invisible to it. On 70 current-version pages that box was completely empty, and on the rest the panel sections were missing while their subheadings showed up flat, with no hint of which panel they belonged to.A new
remark-panel-headingsplugin turns the prop into a real Markdown heading before Docusaurus collects the TOC, andPanelrenders that heading instead of the prop. The rendered markup and CSS are identical to before, so panels look exactly the same.The plugin assigns the id itself, reusing the rule the component used at render time. Every panel link that works today keeps working; letting Docusaurus' slugger recompute the ids would have changed a lot of live anchors.
Before vs After
Type of change
/templatesor readme)Changes in docs URLs
/scripts/redirects.jsonfile, setDocuments MovedPR label)Changes in UX/UI