Docs: align MDX component guidance with actual snippets/partials layout #128

New issue

Closed

opened 2026-04-18 11:12:58 +00:00 by pokebedrock-bot · 0 comments

pokebedrock-bot commented

2026-04-18 11:12:58 +00:00

(Migrated from github.com)

Summary

The wiki authoring docs still give slightly stale guidance around reusable MDX components:

docs/en/handbook/style-guide.mdx and docs/es/handbook/style-guide.mdx show an explicit import example for ../_partials/ServicenodeCallout.mdx, but that file does not exist in the repo.
README.md and CONTRIBUTING.md still describe reusable callouts/components as if they only come from docs/<locale>/_partials, even though the repo also uses auto-registered exports from docs/<locale>/snippets/.

That makes the docs self-contradictory and gives contributors a copy-paste example that fails immediately.

Impact

New contributors can copy a broken MDX import path from the style guide.
Authoring guidance undersells the snippets/ convention that the repo already relies on.
The docs become harder to trust because the examples do not match the current repo structure.

Acceptance criteria

Remove or replace the nonexistent ServicenodeCallout example with guidance that only references files/components that actually exist in the repo.
Update contributor-facing docs to distinguish auto-registered docs/<locale>/snippets/ components from explicitly imported docs/<locale>/_partials/ fragments.
Keep the change limited to docs and validate with npm run ci.

## Summary The wiki authoring docs still give slightly stale guidance around reusable MDX components: - `docs/en/handbook/style-guide.mdx` and `docs/es/handbook/style-guide.mdx` show an explicit import example for `../_partials/ServicenodeCallout.mdx`, but that file does not exist in the repo. - `README.md` and `CONTRIBUTING.md` still describe reusable callouts/components as if they only come from `docs/<locale>/_partials`, even though the repo also uses auto-registered exports from `docs/<locale>/snippets/`. That makes the docs self-contradictory and gives contributors a copy-paste example that fails immediately. ## Impact - New contributors can copy a broken MDX import path from the style guide. - Authoring guidance undersells the `snippets/` convention that the repo already relies on. - The docs become harder to trust because the examples do not match the current repo structure. ## Acceptance criteria - Remove or replace the nonexistent `ServicenodeCallout` example with guidance that only references files/components that actually exist in the repo. - Update contributor-facing docs to distinguish auto-registered `docs/<locale>/snippets/` components from explicitly imported `docs/<locale>/_partials/` fragments. - Keep the change limited to docs and validate with `npm run ci`.