docs: drop the numeric section prefixes from the content paths (fixes #2939)

[mfal]

/02-foundations/01-design/02-colors is now /foundations/design/colors. This answers the product call #2939 asked for: breaking the public docs URLs is accepted, with a redirect layer.

What replaced the numbers

The numbers stopped carrying the top-level order when the header moved to an explicit SECTION_ORDER (#2760). What was left was the intra-section order and the URLs themselves.

The authored order now lives in apps/docs/src/lib/content/contentOrder.ts — a flat list of pathnames, read like a table of contents, that the navigation, the header, llms.txt, llms.json and the sitemap all sort by. Unlisted entries sort alphabetically by label; the components do that deliberately.

An order list in code invites one silent failure: a forgotten line falls back to alphabetical and nothing says so. contentOrder.test.ts closes that — it rejects a listed path that no longer exists, and a group that lists only some of its children. It runs in pnpm nx test:links docs, so CI catches it.

It has already earned its keep: merging #3011, which removed the internal Boundaries section, left two entries pointing at nothing and the test named both. Without it they would have sat there matching no page, silently.

Redirects

One rule in apps/docs/nginx.conf (the docs ship as an nginx image, so next.config redirects would do nothing under output: "export"):

absolute_redirect off;
rewrite "^(?!/_next/)(.*/)[0-9]{2}-(.*)$" $1$2 permanent;

Strips an NN- prefix from any segment and 301s, /raw/** included. A path with several prefixes converges over as many hops; new paths never match, so it terminates. /_next/ is excluded because build chunks are named <id>-<hash>.js — a two-digit id would be rewritten into a 404.

absolute_redirect off is the second half. The container listens on port 80 behind a TLS-terminating proxy, so nginx built the Location as http://… and downgraded every HTTPS visitor following a pre-rename link. Relative redirects carry no scheme to get wrong. This was latent before — try_files … $uri/ can emit the same absolute redirect — but nothing redirected until now.

Verified on the preview deployment, against real nginx:

old path	hops	lands on
/04-components/actions/button	1	/components/actions/button
/03-patterns/01-patterns/dashboard	2	/patterns/patterns/dashboard
/02-foundations/01-design/02-colors	3	/foundations/design/colors
/raw/02-foundations/01-design/02-colors.md	3	/raw/foundations/design/colors.md

All https, all ending in 200, Location relative (location: /components/actions/button). New paths — /foundations/structure/components included — answer 200 in zero hops.

Simulated against the whole out/ build beforehand: 2373 reconstructed old paths resolve to exactly their new path, and all 2787 new paths plus all 32 _next assets stay untouched.

Two things that only worked because the directories were numbered

Both were "alphabetical happens to be the authored order", and both broke on the rename:

• The header linked a section at mdxFiles[0], i.e. filesystem order. After the rename that lands Foundations on Fehlermeldungen instead of Design Tokens. Caught in the built HTML; the first page is now picked by the authored order.
• The components section was matched with includes("04-components"). A bare includes("components") also matches /foundations/structure/components — that would have mis-marked the header's current section and mis-typed the static params. Both compare path segments explicitly now.

Not in scope

03-patterns/01-patterns became /patterns/patterns/*. The duplication is already in the navigation today (section "Patterns" > group "Patterns"); the numbers only hid it in the URL. Dissolving that group is a content decision.

Drive-by

The component overview linked its tiles at .../overview, a legacy tab redirect. Pointing our own links at a redirect while building a redirect layer made no sense.

One unrelated fix carried along

CodeBlock truncated (Local) failed the visual suite with 1702 pixels (ratio 0.01) — the signature #3009 documents for a capture whose reference encodes a focus ring, taken without waiting for the focus. It does encode one: the scenario tabs onto the truncation toggle and captures it focused, and toggling swaps the label, so React re-renders the button the focus sits on. #3009 migrated DatePicker and DateRangePicker to waitForFocusInTheScenario() and left this scenario behind; same remedy applied here. No baseline was touched.

Not caused by this PR — main passed the scheduled visual run at 088b525 half an hour before this branch failed on it, and this branch changes no rendering code. The visual suite runs here at all because the PR touches root-level files, which makes nx consider everything affected.

Verification

• pnpm nx test:links docs — 32 tests, all links in content and app sources resolve
• pnpm nx build docs — static export builds, navigation order checked in the emitted HTML
• pnpm lint — 0 errors
• pnpm nx test:compile remote-react-components — for the visual-test fix
• node --test .github/scripts/release-relevance-lib.test.mjs — 19 tests

fixes #2939

🤖 Generated with Claude Code

[github-actions]

Coverage Report for ./packages/components/

Status	Category	Percentage	Covered / Total
🔵	Lines	78.69%	746 / 948
🔵	Statements	78.57%	763 / 971
🔵	Functions	80.09%	165 / 206
🔵	Branches	70.33%	377 / 536

File Coverage

No changed files found.

Generated in workflow #6460 for commit 28b3069 by the Vitest Coverage Report Action

[github-actions]

🚀 Preview Deployment

Preview environments are ready:

Type	URL
docs	pr-3016.docs.review.flow-components.de
storybook	pr-3016.storybook.review.flow-components.de

Images:

• docs: ghcr.io/mittwald/flow/docs:pr-3016
• storybook: ghcr.io/mittwald/flow/storybook:pr-3016