From 0e1b207db4fb63cc37cf94df022326e3d5a2ddb7 Mon Sep 17 00:00:00 2001
From: Luca Palmieri <20745048+LukeMathWalker@users.noreply.github.com>
Date: Sun, 31 Dec 2023 08:47:34 +0000
Subject: [PATCH] Restructure

---
 .../request_data/body/deserializers/index.md  | 15 ++++++++++++++
 .../json.md}                                  | 20 +++++++------------
 mkdocs.yml                                    |  4 +++-
 3 files changed, 25 insertions(+), 14 deletions(-)
 create mode 100644 docs/guide/request_data/body/deserializers/index.md
 rename docs/guide/request_data/body/{deserializers.md => deserializers/json.md} (80%)

diff --git a/docs/guide/request_data/body/deserializers/index.md b/docs/guide/request_data/body/deserializers/index.md
new file mode 100644
index 000000000..8bc730157
--- /dev/null
+++ b/docs/guide/request_data/body/deserializers/index.md
@@ -0,0 +1,15 @@
+# Overview
+
+Deserializers transform the raw body into a Rust type.  
+They take care of parsing, basic validation and security safeguards.
+They're the family of extractors you'll use most often in your Pavex application.
+
+Out of the box, Pavex supports the following formats:
+
+* [JSON](json.md)
+
+## Tower of abstractions
+
+All deserializers are built on top of Pavex's [low-level primitives](../byte_wrappers.md).  
+As such, they all share the same security safeguards, such as body size limits.  
+Check out [the relevant guide](../byte_wrappers.md) for details on how to configure them.
\ No newline at end of file
diff --git a/docs/guide/request_data/body/deserializers.md b/docs/guide/request_data/body/deserializers/json.md
similarity index 80%
rename from docs/guide/request_data/body/deserializers.md
rename to docs/guide/request_data/body/deserializers/json.md
index 3d2136d46..3550190ee 100644
--- a/docs/guide/request_data/body/deserializers.md
+++ b/docs/guide/request_data/body/deserializers/json.md
@@ -1,34 +1,28 @@
-# Deserializers
-
-Deserializers transform the raw body into a Rust type.  
-They take care of parsing, basic validation and security safeguards.
-They're the family of extractors you'll use most often in your Pavex application.
-
-## Json
+# Json
 
 [`JsonBody<T>`][JsonBody] buffers the body in memory and deserializes it as JSON, 
 according to the type `T` you specify.  
 
-### Extraction 
+## Extraction 
 
 You inject [`JsonBody<T>`][JsonBody] in your handler to access the parsed body:
 
 --8<-- "doc_examples/guide/request_data/json/project-extraction.snap"
 
-### Deserialization
+## Deserialization
 
 The newly defined struct must be **deserializable**—i.e. it must implement the [`serde::Deserialize`][serde::Deserialize] trait.  
 You can derive [`serde::Deserialize`][serde::Deserialize] in most cases.
 
 --8<-- "doc_examples/guide/request_data/json/project-struct_with_attr.snap"
 
-### Avoiding allocations
+## Avoiding allocations
 
 If you want to minimize memory usage, you can try to avoid unnecessary heap memory allocations when deserializing 
 string-like fields from the body of the incoming request.
 Pavex supports this use case—**you can borrow from the request body**.
 
-#### Escape sequences
+### Escape sequences
 
 It is not always possible to avoid allocations, though.
 In particular,
@@ -36,7 +30,7 @@ Pavex must allocate a new `String` if the JSON string you are trying to deserial
 such as `\n` or a `\"`.
 Using a `&str` in this case would result in a runtime error when attempting the deserialization.
 
-#### Cow
+### Cow
 
 We recommend using [`Cow<'_, str>`][Cow] as your field type for string-like parameters.
 It borrows from the request's body if possible, it allocates a new `String` if it can't be avoided.
@@ -44,6 +38,6 @@ It borrows from the request's body if possible, it allocates a new `String` if i
 [`Cow<'_, str>`][Cow] strikes a balance between performance and robustness: you don't have to worry about a runtime error 
 if the field contains escape sequences, but you tried to use `&str` as its field type.
 
-[JsonBody]: ../../../api_reference/pavex/request/body/struct.JsonBody.html
+[JsonBody]: ../../../../api_reference/pavex/request/body/struct.JsonBody.html
 [serde::Deserialize]: https://docs.rs/serde/latest/serde/trait.Deserialize.html
 [Cow]: https://doc.rust-lang.org/std/borrow/enum.Cow.html
diff --git a/mkdocs.yml b/mkdocs.yml
index 14562fc76..39f2d7f6d 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -92,7 +92,9 @@ nav:
               - guide/request_data/query/query_parameters.md
           - "Body":
               - guide/request_data/body/index.md
-              - guide/request_data/body/deserializers.md
+              - "Deserializers":
+                  - guide/request_data/body/deserializers/index.md
+                  - guide/request_data/body/deserializers/json.md
               - guide/request_data/body/byte_wrappers.md
       - "Dependency injection":
           - guide/dependency_injection/index.md