Repository navigation
DOCS: Manual table of contents duplicates GitBook's "On this page" navigation #4897
Description
Activity
Another example, this time independent of GitBook: #4827 renamed the H1 of
documentation/advanced-features/debugging-with-dlv.mdfrom "Debugger" to "Debugging Tips" and added a "Debughelpers.js" section, but the table of contents wasn't regenerated. It still links to#debugger, which no longer exists, and doesn't list the new section:So besides the duplicate navigation and the anchors that don't resolve on GitBook, a hand-maintained TOC also depends on the plug-in being run after every heading change.
Dang. I forgot about the "On this page" listing.
Let me get on my soapbox for a minute...
What I like about "on this page" is that once the TOC has scrolled off, it is still there to help me navigate.
Here's what I don't like about "On this page". It doesn't convey the structure of the document very well to the reader. The point of a TOC is not to catalog what's in the document. The point is to give the reader a visual depiction of the document structure so that they can gain a deep understanding about the structure. That helps them many ways.
When the reader has a knowledge of the document's structure they don't just find what they want easier, it helps them skip what they don't want. I don't know if you remember those "Speed Reading" classes from the 1980s but one thing they taught wasn't "read faster", it was "decide what to skip". When the speed reading classes advertised "I read this entire book in one day!" what they didn't tell you is that after studying the ToC, you can usually figure out which 1-2 chapters to actually read and skip the rest.
I find the "on this page" to be a good catalog of what is in the document. I find the in-line TOC to convey the structure of the document and make the reader an "educated consumer" of the information.
- The TOC on https://docs.dnscontrol.org/developer-info/adding-new-rtypes makes it easy to see this is really 4 "how to" documents in 1. You can easily click on the one you want. The "On this page" doesn't covey this. It's too narrow to allow the eye to see that most of the items are "steps".
- The TOC on https://docs.dnscontrol.org/developer-info/styleguide-code reveals that this is a linear list of tips, with the final one needing a lot of explanation. Which, by the way, makes me realize the tips should be numbered and the last one shouldn't use headings for all that explanation. See? Seeing the structure helps me better understand the page... and I wrote the page!
Ok, I'll get off my soapbox.
My preferences is to display both and have GitBook and have both generate compatible anchors. They each serve different purposes.
If that's not possible, I'd rather get rid of one or the other. If we get rid of the TOC, it should be replaced with a comment reminding me not to add the TOC back. I know how forgetful I am and need that reminder.
@TomOnTime thanks for the explanation, that makes sense. Keeping both looks doable. Comparing the GitBook previews with GitHub, the anchors only differ in three cases:
- GitBook gives the H1 no anchor, so a TOC entry for the page title never resolves.
- GitBook keeps a period in the anchor: "Step 1. Instrument the provider" becomes
#step-1.-instrument-the-provideron GitBook and#step-1-instrument-the-provideron GitHub. - A heading that starts with a number gets an
id-prefix on GitBook.
Colons and parentheses are dropped by both, so a heading like "How to: Run the golden tests" gets
#how-to-run-the-golden-testseverywhere. So if the TOC skips the H1 and follows GitBook's anchors for headings with a period or a leading number, both the TOC and "On this page" work on docs.dnscontrol.org.No rush on my side. Let me know if and when you'd like me to prepare this, and whether you'd prefer one pull request for all pages or a few pages at a time.
Sounds good! yes, please do it all in one PR. Thanks!
- added a commit that references this issue
on Sep 24, 2026
#4818 added a table of contents to the pages under
documentation/, kept up to date with a VS Code plug-in. On https://docs.dnscontrol.org these pages now show the table of contents twice, because GitBook already renders an "On this page" navigation for every page, for example on https://docs.dnscontrol.org/developer-info/styleguide-code:The TOC links use GitHub-style anchors, which don't always match the anchors GitBook generates. Comparing the links with the heading ids on docs.dnscontrol.org, 93 of the 317 anchors on 33 published pages don't exist in GitBook:
#gitlab-ci-dnscontrol-previewinstead of#gitlab-ci---dnscontrol-preview.id-prefix and keep the dot:#id-1.-install-the-softwareinstead of#1-install-the-software.Broken anchors per page
documentation/advanced-features/adding-new-rtypes.mddocumentation/getting-started/getting-started.mddocumentation/developer-info/goreleaser.mddocumentation/advanced-features/ci-cd-gitlab.mddocumentation/developer-info/cookbook.mddocumentation/developer-info/provider-request.mddocumentation/release/release-engineering.mddocumentation/advanced-features/writing-providers.mddocumentation/getting-started/typescript.mddocumentation/advanced-features/cli-variables.mddocumentation/advanced-features/notifications.mddocumentation/advanced-features/opinions.mddocumentation/advanced-features/styleguide-code.mddocumentation/advanced-features/testing-txt-records.mddocumentation/commands/creds-json.mddocumentation/developer-info/github-actions.mddocumentation/language-reference/why-the-dot.mddocumentation/developer-info/modernizingproviders.mdanddocumentation/developer-info/goldenfiles.mdalso got a TOC, but they are not inSUMMARY.md, so they aren't published on docs.dnscontrol.org (404).@TomOnTime is the TOC mainly meant for reading the Markdown on GitHub? How would you like to handle the duplicate navigation and the anchors that don't resolve on the GitBook site?