Problem Statement:
This is a large, actively growing Docusaurus documentation site (docs/, blog/, community/, wiki/ all present, 1,708 commits) built by many first-time contributors. Docusaurus has a config option (onBrokenLinks in docusaurus.config.ts) that controls whether broken internal links fail the build ('throw') or merely log a warning ('warn'/'ignore'). I could not confirm from the README which setting is currently active — this needs a direct look at docusaurus.config.ts before filing.
Why this matters:
Documentation sites with high contributor turnover are especially prone to accumulating broken internal links (renamed docs pages, moved sidebar entries, typo'd relative links) over time, since each contributor typically only touches a small section. If onBrokenLinks isn't set to 'throw', these silently degrade the site instead of blocking the PR that introduced them.
Proposed Solution (once confirmed):
If onBrokenLinks (and onBrokenMarkdownLinks) aren't already set to 'throw' in docusaurus.config.ts, change them — this alone catches broken links at build/PR time going forward.
Additionally, add a scheduled (e.g., weekly) GitHub Actions workflow using a link-checking tool (e.g., lychee or markdown-link-check) to catch external links that have gone dead over time — something Docusaurus's own build check doesn't cover.
Report findings as a checklist issue if the initial scan turns up existing dead links, so they can be fixed incrementally by other GSSoC contributors (a great source of additional "good first issue" tickets).
Impact: Protects the credibility and usability of the project's core deliverable — the documentation itself — as it scales with contributor volume.
Problem Statement:
This is a large, actively growing Docusaurus documentation site (docs/, blog/, community/, wiki/ all present, 1,708 commits) built by many first-time contributors. Docusaurus has a config option (onBrokenLinks in docusaurus.config.ts) that controls whether broken internal links fail the build ('throw') or merely log a warning ('warn'/'ignore'). I could not confirm from the README which setting is currently active — this needs a direct look at docusaurus.config.ts before filing.
Why this matters:
Documentation sites with high contributor turnover are especially prone to accumulating broken internal links (renamed docs pages, moved sidebar entries, typo'd relative links) over time, since each contributor typically only touches a small section. If onBrokenLinks isn't set to 'throw', these silently degrade the site instead of blocking the PR that introduced them.
Proposed Solution (once confirmed):
If onBrokenLinks (and onBrokenMarkdownLinks) aren't already set to 'throw' in docusaurus.config.ts, change them — this alone catches broken links at build/PR time going forward.
Additionally, add a scheduled (e.g., weekly) GitHub Actions workflow using a link-checking tool (e.g., lychee or markdown-link-check) to catch external links that have gone dead over time — something Docusaurus's own build check doesn't cover.
Report findings as a checklist issue if the initial scan turns up existing dead links, so they can be fixed incrementally by other GSSoC contributors (a great source of additional "good first issue" tickets).
Impact: Protects the credibility and usability of the project's core deliverable — the documentation itself — as it scales with contributor volume.