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

.github/scripts/release-relevance-lib.test.mjs

@@ -12,7 +12,7 @@ test("isPublishRelevant: docs, CI and tooling paths are irrelevant", () => {
     ".github/workflows/publish.yml",
     ".github/scripts/release-relevance-lib.mjs",
     ".github/ISSUE_TEMPLATE/bug_report.yml",
-    "apps/docs/src/content/04-components/button.mdx",
+    "apps/docs/src/content/components/button.mdx",
     "apps/remote-dom-demo/src/App.tsx",
     "docs/adr/0005-semver-contract.md",
     "docs/remote-ui.md",
@@ -91,7 +91,7 @@ test("classifyChangedFiles: docs-only and CI-only pushes do not publish", () =>
   // #2870 "docs: fix heading spacing" → 0.2.0-alpha.1044
   assert.equal(
     classifyChangedFiles([
-      "apps/docs/src/content/01-foundations/typography.mdx",
+      "apps/docs/src/content/foundations/typography.mdx",
       "apps/docs/src/app/globals.css",
     ]).publish,
     false,
@@ -108,7 +108,7 @@ test("classifyChangedFiles: docs-only and CI-only pushes do not publish", () =>
 
 test("classifyChangedFiles: a mixed push publishes", () => {
   const result = classifyChangedFiles([
-    "apps/docs/src/content/04-components/button.mdx",
+    "apps/docs/src/content/components/button.mdx",
     ".github/workflows/test.yml",
     "packages/components/src/components/Button/Button.tsx",
   ]);
@@ -160,8 +160,8 @@ test("classifyChangedFiles: square brackets are legitimate path characters", ()
   // Next.js dynamic routes in the docs app — docs-only, must still skip.
   assert.equal(
     classifyChangedFiles([
-      "apps/docs/src/app/04-components/[group]/[component]/develop/page.tsx",
-      "apps/docs/src/app/01-get-started/[...slug]/page.tsx",
+      "apps/docs/src/app/components/[group]/[component]/develop/page.tsx",
+      "apps/docs/src/app/get-started/[...slug]/page.tsx",
     ]).publish,
     false,
   );

AGENTS.md

@@ -206,7 +206,7 @@ A new or substantially changed component comes with:
    [packages/components/AGENTS.md](packages/components/AGENTS.md)
 2. Stories: `stories/Default.stories.tsx` with realistic args and meaningful
    variants
-3. A docs page in `apps/docs/src/content/04-components/<category>/…`
+3. A docs page in `apps/docs/src/content/components/<category>/…`
 4. Tests along the testing bar: unit tests for lib functions, browser tests for
    behavior (see the components AGENTS.md testing section). **New or changed
    rendered behavior (a new prop, variant, or layout that affects the visual

CONTRIBUTE.md

@@ -471,8 +471,8 @@ that automatically when no label is given).
 
 ### 9. Document it on the docs site
 
-Add a doc set under `apps/docs/src/content/04-components/<category>/<slug>/`
-(the content is **not** colocated with the component — copy the structure of a
+Add a doc set under `apps/docs/src/content/components/<category>/<slug>/` (the
+content is **not** colocated with the component — copy the structure of a
 neighbor like `actions/button/`):
 
 - `index.mdx` — **the whole page**, read top to bottom: frontmatter with

README.md

@@ -64,7 +64,7 @@ export default function App() {
 Prefer to override Flow's styles without specificity tricks? Import the
 [CSS Cascade Layers](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer)
 variant instead — `@mittwald/flow-react-components/all-layered.css`. See the
-[stylesheet guide](https://flow.mittwald.de/01-get-started/stylesheet#layered-variante-optional)
+[stylesheet guide](https://flow.mittwald.de/get-started/stylesheet#layered-variante-optional)
 for when to use which.
 
 Set application-wide component defaults once by wrapping your app in

apps/docs/AGENTS.md

@@ -8,11 +8,20 @@ Next.js documentation site for the flow Styleguide, deployed to
   the section and page structures, heading conventions, tone of voice, and
   language rules (German content, English Design System terminology).
 - Content lives in `src/content` as MDX, one directory per section
-  (`01-get-started`, `02-foundations`, `03-patterns`, `04-components`). A
-  component page is a single `index.mdx` — the former `overview`, `develop` and
-  `guidelines` tabs are consolidated onto it. Their routes under
-  `src/app/04-components/[group]/[component]/` are `redirect()`-only, kept so
+  (`get-started`, `foundations`, `patterns`, `components`). A component page is
+  a single `index.mdx` — the former `overview`, `develop` and `guidelines` tabs
+  are consolidated onto it. Their routes under
+  `src/app/components/[group]/[component]/` are `redirect()`-only, kept so
   existing links (and their fragments) keep working.
+- **Directory names are the public URL**, and they carry no order. The authored
+  order lives in `src/lib/content/contentOrder.ts` — a flat list of pathnames
+  that the navigation, the header, `llms.txt` and the sitemap all sort by.
+  Unlisted entries sort alphabetically by label (the components, deliberately).
+  `contentOrder.node.test.ts` rejects a stale entry and a group that lists only
+  some of its children; the latter is the silent half-ordered case.
+- The sections lost their `NN-` prefixes, so `nginx.conf` carries a `rewrite`
+  that strips such a prefix from any segment and 301s. Old links keep working —
+  do not write new ones against the old paths.
 - Code examples are `.tsx` files in the `examples/` directory next to the MDX
   file, referenced via `example="<name>"` (see "Page Building Blocks" in the
   README).

apps/docs/README.md

@@ -16,8 +16,14 @@ The Styleguide is available at:
 https://flow.mittwald.de/
 
 All content lives in `src/content`, organized in one directory per section
-(`01-get-started`, `02-foundations`, `03-patterns`, `04-components`). Pages are
-written in MDX.
+(`get-started`, `foundations`, `patterns`, `components`). Pages are written in
+MDX. Directory names are the URL — a page's path is its directory path.
+
+The order sections and their groups appear in is authored explicitly in
+`src/lib/content/contentOrder.ts`; anything not listed there sorts
+alphabetically by its label, which is what the components do. Add a page to an
+ordered group and you add it to that list — a test fails if a group ends up half
+listed.
 
 ## Styleguide Structure
 
@@ -247,7 +253,7 @@ each with a link to that Component's page and its own example (Button:
   names both and one example shows them together.
 - **`## React Hook Form` is the fixed convention** for form-capable Components:
   always add it, linking to the
-  [Form (React Hook Form)](/04-components/react-hook-form/form) page. A simple
+  [Form (React Hook Form)](/components/react-hook-form/form) page. A simple
   toggle-style Component that ships no dedicated form example (for example
   Switch) may omit it.
 
@@ -417,9 +423,9 @@ code identifiers.
 Use inline links generously to connect related documentation.
 
 - Component names in prose link to the Component's page:
-  `[Section](/04-components/structure/section)`.
-- Links are root-relative (starting with `/01-get-started`, `/02-foundations`,
-  `/03-patterns`, or `/04-components`).
+  `[Section](/components/structure/section)`.
+- Links are root-relative (starting with `/get-started`, `/foundations`,
+  `/patterns`, or `/components`).
 - Verify a link target exists before adding it, and avoid linking to the same
   page multiple times within a short section unless it improves readability.
 

apps/docs/nginx.conf

@@ -4,9 +4,22 @@ server {
     root /usr/share/nginx/html;
     index index.html;
 
+    # The container listens on port 80 behind a TLS-terminating proxy, so nginx
+    # builds absolute redirects as `http://` and downgrades every HTTPS visitor
+    # it redirects. Relative ones carry no scheme and cannot get this wrong.
+    absolute_redirect off;
+
     charset utf-8;
     charset_types text/plain text/markdown text/css text/xml application/javascript application/json;
 
+    # The content paths dropped their numeric prefixes, so links written before
+    # that rename point at pages which no longer exist. Strip the prefix from
+    # any segment and redirect — `/raw/**` included. A path carrying several
+    # prefixes converges over as many hops; the new paths never match, so this
+    # terminates. `/_next/` is excluded because build chunks are named
+    # `<digits>-<hash>.js` and must not be rewritten.
+    rewrite "^(?!/_next/)(.*/)[0-9]{2}-(.*)$" $1$2 permanent;
+
     location ~ \.md$ {
         types {
             text/markdown md;