[kieronlanning]

Why

docs/wiki was one flat directory of 33 pages, so a reader found a page by remembering its file name, and the only hierarchy was the sidebar. It is now one folder per topic area — and because the docs sync publishes a page's folder as part of its URL, the address mirrors the tree.

The tree

docs/wiki/
  Getting-Started.md          landing page (docs.rootPage)
  Fluent-Schema-API.md        deep-linked by the site catalogue (docsPage)
  AspNetCore-Integration.md   deep-linked by the site catalogue (docsPage)
  Home.md  _Sidebar.md
  concepts/       Core Concepts, Composition and Transforms
  schemas/        9 pages: one per schema family, plus the rule catalogue
  generator/      Source Generator, DataAnnotations, Diagnostics
  serialization/  JSON Schema export and import, System.Text.Json, Newtonsoft
  hosting/        Microsoft.Extensions.Validation, OpenAPI, Blazor, HttpClient,
                  dependency injection, localization
  quality/        guarantees, performance, trimming/AOT, cross-platform interop
  development/    Contributing, Release Flow

Published at /docs/zodsharp/<folder>/<page>/ — e.g. schemas/Custom-Rules.md is /docs/zodsharp/schemas/custom-rules/.

Three pages stay at the root. Getting-Started.md is the site's landing page, and Fluent-Schema-API.md and AspNetCore-Integration.md are the two pages the site catalogue deep-links through docsPage — that slug must be a single path segment and must exist in both documentation channels, so those two keep root-level URLs.

What changed

• 30 pages moved with git mv (history preserved); 216 internal links rewritten to resolve from the page that contains them — siblings by file name, cross-folder through ../<folder>/.
• _Sidebar.md lists every page by its path from the wiki root (that is what the sync slugifies for page order), grouped into the same seven sections as before.
• Home.md gained a section→folder table and per-section folder pointers; Getting-Started.md (the published landing page) groups what follows by the goal it serves.
• development/Contributing.md documents the tree, the URL rules (folder is part of the URL; names are letters/digits/dashes so nothing needs encoding; a move needs a docs.redirects entry) and a three-step recipe for adding a page. AGENTS.md, README.md and the pr.yml comments follow.
• File and folder names are URL-safe already — the address mirrors the tree verbatim, with no rewriting.

Guards (DocumentationWikiTests, 9 tests)

Every page lives in a topic folder (folders limited to the documented seven); the root pages are exactly the three contract pages; every file and folder name is URL-safe; the sidebar lists each page exactly once and Home.md reaches every page; sections mirror between _Sidebar.md and Home.md; every relative link resolves from the page that contains it; every page opens with a single # title. Mutation-tested: dropping a page, renaming a section, typo'ing a link, nesting a subfolder and adding URL Probe.md each fail with a message naming the file.

Dependency

Merge purview-dev/purview-dev.github.io#52 first. It teaches the sync to keep a page's folder in its slug, resolve links page-relatively, and honour docs.redirects; that PR also carries the 30-entry map that keeps every former flat URL alive (inert until the release that ships these folders is promoted to live).

Verification

• dotnet test src/tests/Repository.UnitTests --treenode-filter '/*/*/DocumentationWikiTests/*' → 9/9 pass
• csharpier check → clean
• End-to-end replay of this corpus through the site's real helpers: 33 pages, 34 sidebar entries, 216 internal links — none degraded to a GitHub blob URL, every href resolved from its published URL, every #fragment present on its target, every slug URL-safe