Fix all broken anchors reported by the docs build - #628
Closed
samglover wants to merge 1 commit into
Closed
Conversation
`npm run build` reported ~590 broken anchors. Almost all came from the
auto-generated API reference pages: pydoc-markdown emits raw
`<a id="Module.member"></a>` tags and a table of contents that links to
them, but Docusaurus only registers anchors that come from Markdown
headings, so every one of those links looked broken.
- Add `fix-doc-anchors.py`, run after `fix-doc-titles.sh` locally and in
CI. For each page under `docs/components` it folds the `<a id>` tag into
the following heading as an explicit `{#id}` (escaping `_` so `__init__`
isn't parsed as emphasis), drops the module's dangling self-link in the
ToC (an `<h1>`, which Docusaurus never gives an id), closes an unclosed
upstream docstring code fence that was swallowing a heading, and expands
short docstring cross-references (`[x](#x)`, `[x](mod#x)`) to the fully
qualified id. It is idempotent.
- Regenerate the committed reference pages through that script.
- Hand-written pages: repair genuinely wrong anchors
(`writing_review_screen` ToC, `beginners_guide`, `althemetemplate`,
`volunteer`, ALKiln `#unused_rows`/`#join`), demote a stray `#` heading
to `###` in `writing_tests`, turn a bare `<span id>` into `<Anchor>`,
and register the homepage `#partners` div via `useBrokenLinks`.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Contributor
Author
|
Not what I intended. |
There was a problem hiding this comment.
🔵 Needs a closer look
The PR introduces a new content-rewriting script and regenerates many reference docs, so a final human pass is warranted to confirm no subtle anchor/link regressions slipped in.
Pull request overview
This PR eliminates Docusaurus “broken anchor” build warnings by post-processing auto-generated API reference Markdown (so anchors are registered via heading IDs) and by correcting/aligning a handful of hand-written docs and homepage anchors with what Docusaurus’ checker recognizes.
Changes:
- Add
fix-doc-anchors.pyto rewritedocs/components/**.mdanchor patterns into explicit Docusaurus heading IDs and normalize certain cross-references. - Update multiple docs pages to point at existing anchors/sections (and add explicit IDs where needed).
- Register the homepage
#partnersanchor with Docusaurus’ broken-link checker and run the new fixer in CI workflows.
File summaries
| File | Description |
|---|---|
| src/pages/index.tsx | Registers partners as a known in-page anchor for broken-link checking. |
| fix-doc-anchors.py | New post-processor to convert raw <a id> anchors into Docusaurus-recognized heading IDs and expand short xrefs. |
| docs/volunteer/volunteer.mdx | Adds an explicit heading ID for the volunteer signup section. |
| docs/get_started/beginners_guide.md | Fixes links that previously pointed to non-existent intra-page anchors. |
| docs/components/GithubFeedbackForm/github_feedback.md | Updates an API reference link to target the fully-qualified heading ID. |
| docs/components/FormFyxer/pdf_wrangling.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs (plus fence fix). |
| docs/components/FormFyxer/lit_explorer.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/FormFyxer/docx_wrangling.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/EFSPIntegration/py_efsp_client.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs and updates an intra-page reference. |
| docs/components/EFSPIntegration/interview_logic.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/EFSPIntegration/efm_client.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs and updates cross-page reference. |
| docs/components/EFSPIntegration/conversions.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs and updates intra-page references. |
| docs/components/AssemblyLine/sign.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/AssemblyLine/sessions.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/AssemblyLine/language.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/AssemblyLine/custom_jinja_filters.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/AssemblyLine/background_assembly.md | Updates a link to target the fully-qualified heading ID. |
| docs/components/AssemblyLine/al_general.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/AssemblyLine/al_courts.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/ALToolbox/ThreePartsDate.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/ALToolbox/save_input_data.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/ALToolbox/misc.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/ALToolbox/llms.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/ALToolbox/display_template.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/ALToolbox/copy_button.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/ALToolbox/business_days.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/ALToolbox/altoolbox_overview.md | Updates a link to target the fully-qualified heading ID. |
| docs/components/ALToolbox/al_income.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/ALToolbox/Addup.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/ALToolbox/addenda.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/ALThemeTemplate/althemetemplate_overview.md | Fixes a link to a renamed heading anchor. |
| docs/components/ALKiln/writing_tests.mdx | Demotes a section heading so the explicit ID isn’t dropped (avoids H1 behavior). |
| docs/components/ALKiln/troubleshooting.mdx | Updates links to match the actual anchor IDs used by the target sections. |
| docs/components/ALKiln/automated_testing.mdx | Updates links/anchors (including converting a raw span id to a recognized anchor component). |
| docs/components/ALDashboard/validate_docx.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/ALDashboard/translation.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/ALDashboard/project_maintenance.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/ALDashboard/package_scanner.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/ALDashboard/docx_wrangling.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/ALDashboard/create_package.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/components/ALDashboard/aldashboard.md | Regenerated anchors/ToC to use Docusaurus-recognized heading IDs. |
| docs/authoring/writing_review_screen.md | Fixes a ToC link to match the actual “Step 3” heading. |
| .github/workflows/test-deploy.yml | Runs fix-doc-anchors.py as part of the docs generation/build pipeline. |
| .github/workflows/deploy.yml | Runs fix-doc-anchors.py as part of the docs generation/build pipeline. |
Review details
- Files reviewed: 45/45 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+15
to
+16
| * the "Table of Contents" entry that links a module to itself (an ``<h1>``, | ||
| which Docusaurus never gives an id) loses its now-danglink link. |
Member
|
@samglover I'll look this over closer, but I think the right place to make changes isn't these files, which are auto-generated in the build process on github; we don't use the committed versions (and perhaps should get them out of the repo as they can be misleading) edit: never mind, I see you closed the PR |
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.
What
npm run buildwas printing a long "Docusaurus found broken anchors!" list — roughly 590 broken anchor links across ~45 pages. This clears the list; the build now finishes with no warnings.Why it was happening
The overwhelming majority were on the auto-generated API reference pages under
docs/components.pydoc-markdownemits a raw<a id="Module.member"></a>tag before every heading and a Table of Contents whose links point at those ids. Docusaurus' broken-anchor checker only registers anchors that come from Markdown headings (plus a couple of theme components), so it never sees a bare<a id>/<div id>/<span id>and reports every one of those links as broken — even though they work in the browser.Changes
fix-doc-anchors.py(new) — runs afterfix-doc-titles.sh, locally and in both workflowsFor each generated page it:
<a id="X"></a>into the heading that follows it as an explicit Docusaurus id:#### foo(...) {#X}. Underscores in the id are escaped ({#...\_\_init\_\_}) so__init__isn't parsed as**init**emphasis, which was corrupting those ids.<h1>, and Docusaurus deliberately never gives<h1>an id.pdf_wranglingdocstring that was swallowing theunlock_pdf_in_placeheading.[x](#x),[x](other_module#x)) to the fully-qualified id the heading now carries.It is idempotent (re-running is a no-op), so it's safe to keep in the CI pipeline where the pages are regenerated from the source repos.
The committed reference pages are regenerated through the script in this PR.
Hand-written pages
authoring/writing_review_screen.md— ToC linked#step-4-...; the heading is "Step 3".get_started/beginners_guide.md— two links pointed at intra-page anchors that don't exist; now link to the Hello World and project-management pages.components/ALThemeTemplate— link to a since-renamed heading (#creating-a-custom-theme).volunteer/volunteer.mdx— added{#sign-up-to-volunteer}to the heading a link already expected.components/ALKiln—#unused-rows→#unused_rows(matches the<Anchor>id),beginners_guide.md#join→intro.md#join-the-community, and a bare<span id="accessibility">is now<Anchor id="accessibility">so the checker sees it.components/ALKiln/writing_tests.mdx— a subsection was written as#(an<h1>, so{#github-vars}was dropped); demoted to###.src/pages/index.tsx— the homepage<div id="partners">is now registered withuseBrokenLinks().collectAnchor('partners').Testing
npm run buildcompletes cleanly with no broken-anchor (or other) warnings. Spot-checked the generated HTML for the tricky cases (dunder methods, the previously fence-swallowed heading, colliding method names likeBirthDate.validate, the#→###fix,<span>→<Anchor>, and#partners).🤖 Generated with Claude Code