[FOLD]

vinniefalco · vinniefalco · commit 6fec0f2c5bff · 2026-02-07T17:31:48.000-08:00
diff --git a/doc/modules/ROOT/nav.adoc b/doc/modules/ROOT/nav.adoc
@@ -1,21 +1,21 @@
-* xref:2.http-tutorial.adoc[HTTP Tutorial]
-* xref:3.messages.adoc[HTTP Messages]
-** xref:3a.containers.adoc[Containers]
-** xref:3b.serializing.adoc[Serializing]
-** xref:3c.parsing.adoc[Parsing]
-* xref:4.servers.adoc[HTTP Servers]
-** xref:4a.http-worker.adoc[HTTP Worker]
-** xref:4b.route-handlers.adoc[Route Handlers]
-** xref:4c.routers.adoc[Routers]
-** xref:4d.route-patterns.adoc[Route Patterns]
-** xref:4e.serve-static.adoc[Serving Static Files]
-** xref:4f.serve-index.adoc[Directory Listings]
-** xref:4g.bcrypt.adoc[BCrypt]
-* xref:5.compression.adoc[Compression]
-** xref:5a.zlib.adoc[ZLib]
-** xref:5b.brotli.adoc[Brotli]
+* xref:2.http-tutorial/http-tutorial.adoc[HTTP Tutorial]
+* xref:3.messages/messages.adoc[HTTP Messages]
+** xref:3.messages/containers.adoc[Containers]
+** xref:3.messages/serializing.adoc[Serializing]
+** xref:3.messages/parsing.adoc[Parsing]
+* xref:4.servers/servers.adoc[HTTP Servers]
+** xref:4.servers/http-worker.adoc[HTTP Worker]
+** xref:4.servers/route-handlers.adoc[Route Handlers]
+** xref:4.servers/routers.adoc[Routers]
+** xref:4.servers/route-patterns.adoc[Route Patterns]
+** xref:4.servers/serve-static.adoc[Serving Static Files]
+** xref:4.servers/serve-index.adoc[Directory Listings]
+** xref:4.servers/bcrypt.adoc[BCrypt]
+* xref:5.compression/compression.adoc[Compression]
+** xref:5.compression/zlib.adoc[ZLib]
+** xref:5.compression/brotli.adoc[Brotli]
 * Design
-** xref:6a.sans-io.adoc[Sans-I/O Philosophy]
-** xref:6b.parser.adoc[Parser]
-** xref:6c.serializer.adoc[Serializer]
-* xref:7.reference.adoc[Reference]
+** xref:6.design/sans-io.adoc[Sans-I/O Philosophy]
+** xref:6.design/parser.adoc[Parser]
+** xref:6.design/serializer.adoc[Serializer]
+* xref:7.reference/reference.adoc[Reference]
diff --git a/doc/modules/ROOT/pages/2.http-tutorial/http-tutorial.adoc b/doc/modules/ROOT/pages/2.http-tutorial/http-tutorial.adoc
@@ -215,4 +215,4 @@ headers.
 Now that you understand HTTP message structure and session management,
 learn how to work with the library's message containers:
 
-* xref:containers.adoc[Containers] — request, response, and fields types
+* xref:3.messages/containers.adoc[Containers] — request, response, and fields types
diff --git a/doc/modules/ROOT/pages/3.messages/containers.adoc b/doc/modules/ROOT/pages/3.messages/containers.adoc
@@ -511,4 +511,4 @@ container is modified.
 Now that you can build and inspect HTTP messages, learn how to parse
 incoming messages from the network:
 
-* xref:parsing.adoc[Parsing] — parse request and response messages
+* xref:3.messages/parsing.adoc[Parsing] — parse request and response messages
diff --git a/doc/modules/ROOT/pages/3.messages/messages.adoc b/doc/modules/ROOT/pages/3.messages/messages.adoc
@@ -96,9 +96,9 @@ that feeds canned data — without recompilation or abstraction layers.
 
 == Pages in This Section
 
-* xref:3a.containers.adoc[Containers] — build and inspect requests,
+* xref:3.messages/containers.adoc[Containers] — build and inspect requests,
   responses, and header field collections
-* xref:3b.serializing.adoc[Serializing] — transform messages and body
+* xref:3.messages/serializing.adoc[Serializing] — transform messages and body
   data into bytes for the wire
-* xref:3c.parsing.adoc[Parsing] — transform bytes from the wire into
+* xref:3.messages/parsing.adoc[Parsing] — transform bytes from the wire into
   messages and body data
diff --git a/doc/modules/ROOT/pages/3.messages/parsing.adoc b/doc/modules/ROOT/pages/3.messages/parsing.adoc
@@ -224,8 +224,8 @@ you receive is the decoded content.
 
 For detailed information on compression services, see:
 
-* xref:compression/zlib.adoc[ZLib] — DEFLATE and gzip decompression
-* xref:compression/brotli.adoc[Brotli] — Brotli decompression
+* xref:5.compression/zlib.adoc[ZLib] — DEFLATE and gzip decompression
+* xref:5.compression/brotli.adoc[Brotli] — Brotli decompression
 
 == Handling Multiple Messages
 
@@ -303,4 +303,4 @@ Common errors include:
 Now that you can parse incoming messages, learn how to produce outgoing
 messages:
 
-* xref:serializing.adoc[Serializing] — produce HTTP messages for transmission
+* xref:3.messages/serializing.adoc[Serializing] — produce HTTP messages for transmission
diff --git a/doc/modules/ROOT/pages/3.messages/serializing.adoc b/doc/modules/ROOT/pages/3.messages/serializing.adoc
@@ -221,8 +221,8 @@ co_await sink.write_eof(
 
 For detailed information on compression services, see:
 
-* xref:compression/zlib.adoc[ZLib] — DEFLATE and gzip compression
-* xref:compression/brotli.adoc[Brotli] — Brotli compression
+* xref:5.compression/zlib.adoc[ZLib] — DEFLATE and gzip compression
+* xref:5.compression/brotli.adoc[Brotli] — Brotli compression
 
 == Expect: 100-continue
 
diff --git a/doc/modules/ROOT/pages/4.servers/bcrypt.adoc b/doc/modules/ROOT/pages/4.servers/bcrypt.adoc
diff --git a/doc/modules/ROOT/pages/4.servers/http-worker.adoc b/doc/modules/ROOT/pages/4.servers/http-worker.adoc
diff --git a/doc/modules/ROOT/pages/4.servers/route-handlers.adoc b/doc/modules/ROOT/pages/4.servers/route-handlers.adoc
@@ -866,4 +866,4 @@ to _install_ a handler -- how to tell the router "when a `GET` request
 arrives at `/posts/:id`, call _this_ function."
 
 That is the job of the router, and it is the subject of the
-xref:4c.routers.adoc[next page].
+xref:4.servers/routers.adoc[next page].
diff --git a/doc/modules/ROOT/pages/4.servers/route-patterns.adoc b/doc/modules/ROOT/pages/4.servers/route-patterns.adoc
@@ -505,4 +505,4 @@ These patterns are invalid and produce parse errors:
 
 == See Also
 
-* xref:4c.routers.adoc[Routers] - request dispatch and handler registration
+* xref:4.servers/routers.adoc[Routers] - request dispatch and handler registration
diff --git a/doc/modules/ROOT/pages/4.servers/routers.adoc b/doc/modules/ROOT/pages/4.servers/routers.adoc
@@ -1171,9 +1171,9 @@ size.
 
 == See Also
 
-* xref:4b.route-handlers.adoc[Route Handlers] -- the handler
+* xref:4.servers/route-handlers.adoc[Route Handlers] -- the handler
   signature, `route_params`, and the `send()` method
-* xref:4d.route-patterns.adoc[Route Patterns] -- the complete
+* xref:4.servers/route-patterns.adoc[Route Patterns] -- the complete
   pattern syntax with detailed matching examples
-* xref:4e.serve-static.adoc[Serving Static Files] -- the
+* xref:4.servers/serve-static.adoc[Serving Static Files] -- the
   `serve_static` middleware
diff --git a/doc/modules/ROOT/pages/4.servers/serve-index.adoc b/doc/modules/ROOT/pages/4.servers/serve-index.adoc
@@ -254,7 +254,7 @@ appropriate for local development but not for production.
 
 == See Also
 
-* xref:server/serve-static.adoc[Serving Static Files] — file serving
+* xref:4.servers/serve-static.adoc[Serving Static Files] — file serving
   middleware that pairs with `serve_index`
-* xref:server/route-patterns.adoc[Route Patterns] — how request paths
+* xref:4.servers/route-patterns.adoc[Route Patterns] — how request paths
   are matched to handlers
diff --git a/doc/modules/ROOT/pages/4.servers/serve-static.adoc b/doc/modules/ROOT/pages/4.servers/serve-static.adoc
@@ -308,5 +308,5 @@ This configuration:
 
 == See Also
 
-* xref:server/route-patterns.adoc[Route Patterns] — how request paths
+* xref:4.servers/route-patterns.adoc[Route Patterns] — how request paths
   are matched to handlers
diff --git a/doc/modules/ROOT/pages/4.servers/servers.adoc b/doc/modules/ROOT/pages/4.servers/servers.adoc
@@ -214,7 +214,7 @@ and passes it to the handler. This is how a single route definition
 handles thousands of different URLs.
 
 Patterns can also include wildcards, optional groups, and literal
-segments. The xref:4d.route-patterns.adoc[Route Patterns] page
+segments. The xref:4.servers/route-patterns.adoc[Route Patterns] page
 explores the full syntax. For now, the key insight is that routing
 transforms a flat stream of requests into organized, purpose-built
 handler functions.
@@ -496,14 +496,14 @@ effortlessly.
 
 The pages that follow dive into each component in detail:
 
-* xref:4c.routers.adoc[Routers] -- the dispatch engine that maps
+* xref:4.servers/routers.adoc[Routers] -- the dispatch engine that maps
   requests to handlers, with method matching, handler chaining,
   middleware, nested routers, and error handling
-* xref:4d.route-patterns.adoc[Route Patterns] -- the full pattern
+* xref:4.servers/route-patterns.adoc[Route Patterns] -- the full pattern
   syntax including named parameters, wildcards, and optional groups
-* xref:4e.serve-static.adoc[Serving Static Files] -- efficient
+* xref:4.servers/serve-static.adoc[Serving Static Files] -- efficient
   file serving with caching, range requests, and content negotiation
-* xref:4f.serve-index.adoc[Directory Listings] -- browsable
+* xref:4.servers/serve-index.adoc[Directory Listings] -- browsable
   directory views in HTML, JSON, or plain text
 
 Each page builds on the foundation laid here. The router page shows
diff --git a/doc/modules/ROOT/pages/5.compression/brotli.adoc b/doc/modules/ROOT/pages/5.compression/brotli.adoc
@@ -160,4 +160,4 @@ ser_cfg.apply_brotli_encoder = true;
 
 == See Also
 
-* xref:zlib.adoc[ZLib] — DEFLATE/gzip compression
+* xref:5.compression/zlib.adoc[ZLib] — DEFLATE/gzip compression
diff --git a/doc/modules/ROOT/pages/5.compression/compression.adoc b/doc/modules/ROOT/pages/5.compression/compression.adoc
diff --git a/doc/modules/ROOT/pages/5.compression/zlib.adoc b/doc/modules/ROOT/pages/5.compression/zlib.adoc
@@ -213,4 +213,4 @@ ser_cfg.apply_gzip_encoder = true;
 
 == See Also
 
-* xref:brotli.adoc[Brotli] — Higher compression ratio
+* xref:5.compression/brotli.adoc[Brotli] — Higher compression ratio
diff --git a/doc/modules/ROOT/pages/6.design/parser.adoc b/doc/modules/ROOT/pages/6.design/parser.adoc
diff --git a/doc/modules/ROOT/pages/6.design/sans-io.adoc b/doc/modules/ROOT/pages/6.design/sans-io.adoc
diff --git a/doc/modules/ROOT/pages/6.design/serializer.adoc b/doc/modules/ROOT/pages/6.design/serializer.adoc
diff --git a/doc/modules/ROOT/pages/7.reference/reference.adoc b/doc/modules/ROOT/pages/7.reference/reference.adoc
diff --git a/doc/modules/ROOT/pages/index.adoc b/doc/modules/ROOT/pages/index.adoc
@@ -129,11 +129,11 @@ Content-Length: 42
 
 == Next Steps
 
-* xref:2.http-tutorial.adoc[HTTP Tutorial] — learn the HTTP protocol
-* xref:3.messages.adoc[HTTP Messages] — containers, serializing, and parsing
-* xref:4.servers.adoc[HTTP Servers] — workers, route handlers, routers, and built-in middleware
-* xref:5.compression.adoc[Compression] — gzip, deflate, brotli
-* xref:7.reference.adoc[Reference] — complete API reference
+* xref:2.http-tutorial/http-tutorial.adoc[HTTP Tutorial] — learn the HTTP protocol
+* xref:3.messages/messages.adoc[HTTP Messages] — containers, serializing, and parsing
+* xref:4.servers/servers.adoc[HTTP Servers] — workers, route handlers, routers, and built-in middleware
+* xref:5.compression/compression.adoc[Compression] — gzip, deflate, brotli
+* xref:7.reference/reference.adoc[Reference] — complete API reference
 
 == Acknowledgments
 
diff --git a/doc/modules/ROOT/pages/router.adoc b/doc/modules/ROOT/pages/router.adoc
@@ -138,7 +138,7 @@ Route paths support named parameters and wildcards:
 |===
 
 For the complete pattern syntax including optional groups, escaping, and
-quoted names, see xref:server/route-patterns.adoc[Route Patterns].
+quoted names, see xref:4.servers/route-patterns.adoc[Route Patterns].
 
 Access captured parameters in handlers:
 
@@ -538,5 +538,5 @@ int main()
 
 == Next Steps
 
-* xref:bcrypt.adoc[BCrypt] — secure password hashing for authentication
-* xref:sans_io_philosophy.adoc[Sans-I/O Philosophy] — design rationale
+* xref:4.servers/bcrypt.adoc[BCrypt] — secure password hashing for authentication
+* xref:6.design/sans-io.adoc[Sans-I/O Philosophy] — design rationale

Original file line number	Diff line number	Diff line change
`@@ -505,4 +505,4 @@ These patterns are invalid and produce parse errors:`
`505`	`505`
`506`	`506`	`== See Also`
`507`	`507`
`508`		`-* xref:4c.routers.adoc[Routers] - request dispatch and handler registration`
	`508`	`+* xref:4.servers/routers.adoc[Routers] - request dispatch and handler registration`