| name | check-docs-style |
| description | Check modified Nx documentation pages against the astro-docs style guide. Auto-trigger after writing or editing docs content in the nx repo. Also trigger on "check style", "style guide", "docs review", "validate docs". Should run as a final step whenever docs files are modified. IMPORTANT: anytime astro-docs/**/*.mdoc files are modified, this should always run automatically without being asked. |
Nx docs style check
You are a documentation editor for Nx. Whenever you detect that the user is writing or editing
documentation files in astro-docs/src/content/ (.mdoc, .mdx, .md), automatically run this
check and fix any issues. Do not wait to be asked.
Phase 1: Information architecture audit
Read astro-docs/STYLE_GUIDE.md (the "Information architecture" section) and
astro-docs/sidebar.mts to understand where the page lives in the sidebar hierarchy.
For every new or moved page, evaluate against ALL SEVEN principles. These are non-negotiable:
1. Progressive disclosure ("journey" rule)
- Is this for the first 30 minutes (Getting Started), first 30 days (Features), or forever (Reference)?
- Flag if the content complexity doesn't match the section's experience level.
2. Category homogeneity ("scan" rule)
- Look at sibling pages in the same sidebar section.
- Do they all share the same content type (concepts, tasks, or products)?
- Flag if this page mixes types that siblings don't.
3. Type-based navigation ("intent" rule)
- Is this a learning page (narrative/guide) or a lookup page (reference/API)?
- Flag if it's in the wrong category (e.g., a reference page in a guides section).
4. Pen and paper test ("theory" rule)
- Can the page be explained using only pen and paper (no terminal needed)?
- YES = belongs in "How Nx Works" (architecture/concepts)
- NO (needs terminal/code examples) = belongs in "Platform Features" or "Technologies"
- Flag if a concept page has terminal output, CLI commands, or code-heavy examples.
5. Universal vs. specific ("placement" rule)
- Does this feature apply to every Nx user?
- YES = "Platform Features"
- NO (only React/Angular/etc. users) = "Technologies"
- Flag if a technology-specific page is in Platform Features or vice versa.
6. Golden path ("one way" rule)
- Does the page teach one default workflow, or does it enumerate flags and variants?
- Flag sentences a first-time user needs neither to succeed nor to choose. Those belong in a Knowledge Base guide.
7. One page per feature ("don't make me hunt" rule)
- List the questions a new reader, or an AI answering for one, would ask about this feature.
- Flag any answer that lives only on another page. The feature page should carry the question even when the detail fans out to a Knowledge Base guide.
- This is the counterweight to principle 6, not an exception to it: trim variants, keep decisions.
Phase 2: Style validation
Step 1: Run Vale and fix errors
Run nx run astro-docs:vale to check the modified files.
- errors — fix these automatically. Edit the file to resolve the violation.
- warnings — fix these automatically when the fix is unambiguous (e.g., sentence case headings).
For ambiguous cases, suggest the fix and ask.
- suggestions — mention them to the user but do not auto-fix.
Step 2: Apply the guide by hand (Vale covers only a subset)
Vale enforces only the mechanical rules, and even the ones it implements are partial. A
clean Vale run is not evidence the guide passed. Reading the guide is also not enough;
you have to test your changed text against each rule.
For the diff you just made:
- Run the guide's own "Pre-publish pass order" end to end, in order, on your changed text.
Where a pass is a procedure (a grep, a count, a rewrite), perform it on your text rather
than just confirming the pass exists.
- Then go through the rest of
STYLE_GUIDE.md rule by rule, checking your changed lines
against every rule the pass order did not already cover. A rule counts as checked only
after you've read your actual sentences through it, not after you've read the rule.
- Fix every violation. If a rule genuinely doesn't apply to this change, move on.
Handling false positives
Use inline Vale comments to suppress legitimate exceptions:
<!-- vale Nx.Headings = NO -->
## extractLicenses
<!-- vale Nx.Headings = YES -->
Common cases where suppression is appropriate:
- CLI option headings (e.g.,
## extractLicenses) — camelCase by design.
Prefer wrapping in backticks first (## \extractLicenses``).
- Product possessives in historical/migration context (e.g., "Angular's original schematic system")
- Terminology in migration docs (e.g., explaining what "schematics" were before being renamed)
Do NOT suppress rules just to avoid fixing real violations.
Output summary
After fixing, report what you did:
## Style check results
### Information architecture: [PASS/FAIL]
[List any violations or confirm all seven principles pass]
### Vale: [X errors fixed, Y warnings fixed, Z suggestions noted]
[Summary of changes made]
### Manual fixes: [list of additional fixes applied]
