CI: validate relative MDX imports #132

New issue

Closed

opened 2026-04-18 19:17:25 +00:00 by pokebedrock-bot · 0 comments

pokebedrock-bot commented

2026-04-18 19:17:25 +00:00

(Migrated from github.com)

Summary

The wiki repo validates markdown style, frontmatter, images, links, generated artifacts, and search builds, but it still does not validate relative MDX imports.

That leaves a blind spot where broken imports can live on main without any CI signal until someone manually notices the page or copy example is wrong.

Evidence

Current main still contains example imports that point at a nonexistent partial:

docs/en/handbook/style-guide.mdx
docs/es/handbook/style-guide.mdx

Both currently show:

import ServicenodeCallout from "../_partials/ServicenodeCallout.mdx";

…but the only partial under each locale today is ReleaseChecklist.mdx, so that relative target does not exist.

The existing CI stack does not catch this because:

npm run lint checks markdown, frontmatter, and images
npm run lint:links checks outbound links
npm run check:generated checks emitted search/manifests

None of those steps resolve MDX import ... from "./relative-path.mdx" targets.

Impact

Broken or stale MDX examples can survive on main
Contributor guidance can drift away from the real repo layout with no automation feedback
Future partial/snippet renames can silently break docs until a human spots them

Acceptance criteria

Add a lint/build step that scans docs MDX files for relative import ... from statements
Fail CI when a relative MDX import target does not exist
Ignore package imports / non-relative imports so normal MDX library usage still works
Wire the check into the existing lint or CI path so contributors get the failure automatically
Optionally document the new validation in repo docs if needed

## Summary The wiki repo validates markdown style, frontmatter, images, links, generated artifacts, and search builds, but it still does **not** validate relative MDX imports. That leaves a blind spot where broken imports can live on `main` without any CI signal until someone manually notices the page or copy example is wrong. ## Evidence Current `main` still contains example imports that point at a nonexistent partial: - `docs/en/handbook/style-guide.mdx` - `docs/es/handbook/style-guide.mdx` Both currently show: ```mdx import ServicenodeCallout from "../_partials/ServicenodeCallout.mdx"; ``` …but the only partial under each locale today is `ReleaseChecklist.mdx`, so that relative target does not exist. The existing CI stack does not catch this because: - `npm run lint` checks markdown, frontmatter, and images - `npm run lint:links` checks outbound links - `npm run check:generated` checks emitted search/manifests None of those steps resolve MDX `import ... from "./relative-path.mdx"` targets. ## Impact - Broken or stale MDX examples can survive on `main` - Contributor guidance can drift away from the real repo layout with no automation feedback - Future partial/snippet renames can silently break docs until a human spots them ## Acceptance criteria - Add a lint/build step that scans docs MDX files for relative `import ... from` statements - Fail CI when a relative MDX import target does not exist - Ignore package imports / non-relative imports so normal MDX library usage still works - Wire the check into the existing lint or CI path so contributors get the failure automatically - Optionally document the new validation in repo docs if needed