| name | nx-docs-iterate |
| description | Validate-and-ship loop for nx astro-docs changes. Runs prettier, vale, the STYLE_GUIDE structural pass, an anchor sweep, then amends the squashed commit and force-pushes. Use after every docs edit round in the nx repo. Triggers on "docs iterate", "amend and push the docs", "ship the docs change", "docs validate and push". |
nx-docs-iterate
The per-iteration loop for nx astro-docs PRs that keep a single squashed commit and amend
on every review round (NXC-4453 ran this ~15 times). Run it AFTER each edit round, BEFORE
telling Jack it's pushed.
Process
All paths relative to the nx repo root (or worktree).
1. Format
npx prettier --write <changed .mdoc/.mts/.mjs files>
Prettier may reflow Markdoc - re-check {% aside %} blocks with lists (blank line before
{% /aside %} or parsing breaks).
2. Vale (mechanical tier)
cd astro-docs && vale <changed files under src/content/docs/>
Target: 0 errors, 0 warnings. Suggestions in UNTOUCHED sections may stay; fix any in
paragraphs you added.
3. Structural pass (what vale can't see)
Per astro-docs/STYLE_GUIDE.md, on every paragraph added or rewritten:
- Claim calibration: no unsupportable absolutes ("less chance of issues", never "will not
introduce issues").
- Terminology table: "workspace" not "monorepo"; generator not script (gloss once);
Nx Cloud/Console capitalized.
- Bold only for UI labels and term definitions - never emphasis.
- No semicolons, no em/en dashes, ASCII only:
git diff master -- astro-docs/ | grep "^+" | grep -E ';|—|–|→|·' must be empty.
- No trust words (easily/simply/just), no banned AI phrases, no list completing an intro
sentence.
- Golden path check: feature pages teach the default workflow with ONE command form; flags
appear only where the reader makes a real choice (brief why + link), with constraints and
edge cases in the advanced/KB guide; converged sections get merged, not duplicated.
4. Anchor sweep (after any heading/section/sidebar change)
cd astro-docs
grep -rhoE "<changed-page-slug>#[a-z0-9-]+" src/content/docs/ | sort -u
grep -E "^#{2,4} " "src/content/docs/<changed page>"
- Deleted anchors can't be redirected - repoint the inbound links.
- Sidebar GROUP label renames: breadcrumbs +
sidebar_group_cards slugify/match labels
exactly. Move/retitle the knowledge-base/<slug>/index.mdoc landing page, update its
group= attr, add redirects in BOTH astro.config.mjs and netlify.toml (before the
/docs/* catch-all).
5. Redirect sweep (after any page move/rename/delete)
Every moved, renamed, or deleted page under astro-docs/src/content/docs/ MUST ship a
redirect in astro-docs/netlify.toml in the SAME commit. Missed one on the
nx-vs-turborepo move (#36275, fixed in #36320) - do not repeat.
git diff master --name-status -- 'astro-docs/src/content/docs/' | grep -E '^[RD]'
For each R (rename/move): add old URL -> new URL. For each D (delete): redirect to the
closest surviving page. URL from path: lowercase, spaces/underscores -> dashes, drop
extension, prefix /docs/ (guides/Adopting Nx/nx-vs-turborepo.mdoc ->
/docs/guides/adopting-nx/nx-vs-turborepo).
Rules:
- Place the rule BEFORE the
/docs/* catch-all at the bottom of netlify.toml.
- One-line comment above the block naming the ticket/PR.
- netlify.toml is the canonical location;
astro.config.mjs redirects are legacy - do not
add there for plain page moves.
- Deleted ANCHORS can't be redirected - repoint inbound links instead (step 4).
- Verify:
grep -n "<old-slug>" astro-docs/netlify.toml hits, and the line number is above
the /docs/* rule.
6. validate-links (when structure changed)
Works in the sandbox if ~/.m2 and ~/.gradle are write-allowlisted (ask Jack to grant
if not):
NX_NO_CLOUD=true npx nx run astro-docs:validate-links
Gotchas: nx reset forces a cold graph (gradle wrapper re-download); nx-dev:next:build
is flaky on cold full rebuilds - run it alone once, then re-run validate-links. Pipe to a
file, not | tail (tail eats the exit code).
7. Amend + push (logged)
git add astro-docs/...
git commit --amend --no-edit --no-verify
Then force-push:
git push --no-verify --force-with-lease origin <branch>
Report
One line per gate: prettier / vale (errors-warnings-suggestions) / structural / anchors /
redirects (n/a or added) / validate-links (run or skipped+why) / pushed SHA.
