Description
The project's docs/ and blog/ directories contain a large and actively growing volume of educational content (per the repo structure: docs/GitHub/, docs/Google-Student-Ambassador/, and many more subdirectories, plus numerous dated blog posts like git-coding-agent/, google-backlinks/). Docusaurus ships with a built-in onBrokenLinks config option that can fail the production build on broken internal links, but the documented CI/dev tooling (ESLint, Prettier, tsc type-checking) doesn't mention link validation as part of the pipeline, and there's no dedicated docs.md/community/our-documentation.md reference to a link-checking step being part of the review process.
With 1,708 commits and heavy multi-contributor GSSoC activity across many simultaneous docs PRs, internal links between docs pages (or docs referencing blog posts, or vice versa) are a natural, easy-to-introduce regression — a page rename or move in one PR can silently break links added by a completely different, unrelated PR merged around the same time.
Impact
Silent broken links directly undermine the core product (an educational platform whose entire value is navigable, trustworthy documentation) without any contributor being aware they caused it.
A CI-enforced check is far cheaper than manual QA across a docs corpus this large, and scales naturally as GSSoC brings in dozens of simultaneous docs-focused contributors (a very likely contribution pattern for an educational Docusaurus site).
Proposed Solution
Set onBrokenLinks: 'throw' (or at minimum 'warn' initially, to establish a baseline without breaking existing PRs) in docusaurus.config.ts if not already configured this way.
Add a dedicated CI job (.github/workflows/) that runs npm run build specifically to catch broken-link failures, separate from any existing lint/type-check jobs, with a clear job name like "Check Broken Links" so failing PRs get an unambiguous signal.
Document this check in community/understand-lint-checks.md (which already exists and is the natural home for this) so new contributors know what "broken link" CI failures mean and how to fix them.
Acceptance Criteria
docusaurus.config.ts configured to fail (or clearly warn) on broken internal links
Dedicated CI job added running the Docusaurus build specifically to catch link breakage
community/understand-lint-checks.md updated to explain this check for new contributors
Verified against at least one intentionally-broken test link to confirm the CI job actually catches it
Description
The project's docs/ and blog/ directories contain a large and actively growing volume of educational content (per the repo structure: docs/GitHub/, docs/Google-Student-Ambassador/, and many more subdirectories, plus numerous dated blog posts like git-coding-agent/, google-backlinks/). Docusaurus ships with a built-in onBrokenLinks config option that can fail the production build on broken internal links, but the documented CI/dev tooling (ESLint, Prettier, tsc type-checking) doesn't mention link validation as part of the pipeline, and there's no dedicated docs.md/community/our-documentation.md reference to a link-checking step being part of the review process.
With 1,708 commits and heavy multi-contributor GSSoC activity across many simultaneous docs PRs, internal links between docs pages (or docs referencing blog posts, or vice versa) are a natural, easy-to-introduce regression — a page rename or move in one PR can silently break links added by a completely different, unrelated PR merged around the same time.
Impact
Silent broken links directly undermine the core product (an educational platform whose entire value is navigable, trustworthy documentation) without any contributor being aware they caused it.
A CI-enforced check is far cheaper than manual QA across a docs corpus this large, and scales naturally as GSSoC brings in dozens of simultaneous docs-focused contributors (a very likely contribution pattern for an educational Docusaurus site).
Proposed Solution
Set onBrokenLinks: 'throw' (or at minimum 'warn' initially, to establish a baseline without breaking existing PRs) in docusaurus.config.ts if not already configured this way.
Add a dedicated CI job (.github/workflows/) that runs npm run build specifically to catch broken-link failures, separate from any existing lint/type-check jobs, with a clear job name like "Check Broken Links" so failing PRs get an unambiguous signal.
Document this check in community/understand-lint-checks.md (which already exists and is the natural home for this) so new contributors know what "broken link" CI failures mean and how to fix them.
Acceptance Criteria
docusaurus.config.ts configured to fail (or clearly warn) on broken internal links
Dedicated CI job added running the Docusaurus build specifically to catch link breakage
community/understand-lint-checks.md updated to explain this check for new contributors
Verified against at least one intentionally-broken test link to confirm the CI job actually catches it