diff --git a/book/SUMMARY.md b/book/SUMMARY.md
index d3461cd5..6b222857 100644
--- a/book/SUMMARY.md
+++ b/book/SUMMARY.md
@@ -14,14 +14,14 @@
- [Retry](./providers/retry.md)
- [RW](./providers/rw.md)
- [WebSocket](./providers/ws.md)
-- [Middleware]()
- - [Builder]()
- - [Create custom middleware]()
- - [Gas escalator]()
- - [Gas oracle]()
- - [Nonce manager]()
- - [Policy]()
- - [Signer]()
+- [Middleware](./middleware/middleware.md)
+ - [Builder](./middleware/builder.md)
+ - [Create custom middleware](./middleware/custom.md)
+ - [Gas escalator](./middleware/gas-escalator.md)
+ - [Gas oracle](./middleware/gas-oracle.md)
+ - [Nonce manager](./middleware/nonce-manager.md)
+ - [Policy](./middleware/policy.md)
+ - [Signer](./middleware/signer.md)
- [Time lag]()
- [Transformer]()
- [Contracts]()
diff --git a/book/getting-started/intro.md b/book/getting-started/intro.md
index 245df94a..9d40f99a 100644
--- a/book/getting-started/intro.md
+++ b/book/getting-started/intro.md
@@ -14,24 +14,19 @@ We hope that these docs will help you get started with ethers-rs and give you a
The following is a brief overview diagram of the topis covered in this guide.
```mermaid
-graph LR
- %% The code below is for styling the graph
- %%-------------------------------------------------
- %%{init: {'theme':'dark', 'themeVariables':{'textColor':' #ffffff ', 'nodeBorder':'#ff2d00', 'edgeLabelBackground':'#000000' ,'lineColor':'#87ff00', 'fontSize':'14px', 'curve':'linear'}}}%%
+{{#include ../mermaid-style.txt}}
- %%-------------------------------------------------
- %% Actual Diagram code is below
-
- A[Ethers-rs
Manual] --> A1[Providers]
+graph LR
+ A[Ethers-rs
Manual] --> A1[Providers]
A --> A2[Middleware]
- A --> A3[Contracts]
- A --> A4[Events]
- A --> A5[Subscriptions]
- A --> A6[Queries]
- A --> A7[Transactions]
- A --> A8[Wallets]
- A --> A9[Big numbers]
- A --> A10[Anvil]
+ A --> A3[Contracts]
+ A --> A4[Events]
+ A --> A5[Subscriptions]
+ A --> A6[Queries]
+ A --> A7[Transactions]
+ A --> A8[Wallets]
+ A --> A9[Big numbers]
+ A --> A10[Anvil]
```
```admonish bug
This diagram is incomplete and will undergo continuous changes.
diff --git a/book/mermaid-style.txt b/book/mermaid-style.txt
new file mode 100644
index 00000000..cca1d9cf
--- /dev/null
+++ b/book/mermaid-style.txt
@@ -0,0 +1,13 @@
+%%{
+ init: {
+ 'theme':'dark',
+ 'themeVariables': {
+ 'textColor':' #ffffff',
+ 'nodeBorder':'#ff2d00',
+ 'edgeLabelBackground':'#00000',
+ 'lineColor':'#87ff00',
+ 'fontSize':'14px',
+ 'curve':'linear'
+ }
+ }
+}%%
\ No newline at end of file
diff --git a/book/middleware/builder.md b/book/middleware/builder.md
new file mode 100644
index 00000000..b12ee2df
--- /dev/null
+++ b/book/middleware/builder.md
@@ -0,0 +1,5 @@
+# Middleware builder
+
+```rust
+{{#include ../../examples/middleware/examples/builder.rs}}
+```
diff --git a/book/middleware/custom.md b/book/middleware/custom.md
new file mode 100644
index 00000000..451c0867
--- /dev/null
+++ b/book/middleware/custom.md
@@ -0,0 +1,5 @@
+# Create custom middleware
+
+```rust
+{{#include ../../examples/middleware/examples/create_custom_middleware.rs}}
+```
diff --git a/book/middleware/gas-escalator.md b/book/middleware/gas-escalator.md
new file mode 100644
index 00000000..def07126
--- /dev/null
+++ b/book/middleware/gas-escalator.md
@@ -0,0 +1,5 @@
+# Gas escalator
+
+```rust
+{{#include ../../examples/middleware/examples/gas_escalator.rs}}
+```
\ No newline at end of file
diff --git a/book/middleware/gas-oracle.md b/book/middleware/gas-oracle.md
new file mode 100644
index 00000000..9925b398
--- /dev/null
+++ b/book/middleware/gas-oracle.md
@@ -0,0 +1,5 @@
+# Gas oracle
+
+```rust
+{{#include ../../examples/middleware/examples/gas_oracle.rs}}
+```
\ No newline at end of file
diff --git a/book/middleware/middleware.md b/book/middleware/middleware.md
new file mode 100644
index 00000000..dce9c03f
--- /dev/null
+++ b/book/middleware/middleware.md
@@ -0,0 +1,37 @@
+# Middlewares
+In ethers-rs, middleware is a way to customize the behavior of certain aspects of the library by
+injecting custom logic into the process of interacting with the Ethereum JSON-RPC API.
+Middlewares act in a chain of responsibility and can be combined to achieve the desired behavior.
+
+The library allows developers to create [custom middlewares](./custom.md), going beyond
+standard operations and unlocking powerful use cases.
+
+A JSON-RPC client instance can be constructed as a stack of middlewares, backed by a common instance of `Provider` of one specific type among `JsonRpcClient` and `PubSubClient`.
+
+```mermaid
+{{#include ../mermaid-style.txt}}
+
+flowchart TB
+ subgraph ide1 [Client]
+ middleware2--inner-->middleware1--inner-->middleware0--inner-->provider
+ end
+ subgraph ide2 [Transport]
+ provider--PubSubClient-->ws
+ provider--PubSubClient-->ipc
+ provider--JsonRpcClient
PubSubClient-->http
+ provider--JsonRpcClient
PubSubClient-->retry
+ provider--JsonRpcClient
PubSubClient-->quorum
+ provider--JsonRpcClient
PubSubClient-->rw
+ end
+```
+
+The following middlewares are currently supported:
+
+- [Gas Escalator](./gas-escalator.md): Avoids transactions being stucked in the mempool, by bumping the gas price in background.
+- [Gas Oracle](./gas-oracle.md): Allows retrieving the current gas price from common RESTful APIs, instead of retrieving it from blocks.
+- [Nonce Manager](./nonce-manager.md): Manages nonces of transactions locally, without waiting for them to hit the mempool.
+- [Policy](./policy.md): Allows to define rules or policies that should be followed when submitting JSON-RPC API calls.
+- [Signer](./signer.md): Signs transactions locally, with a private key or a hardware wallet.
+- [Time lag](./time-lag.md): Poses a block delay on JSON-RPC interactions, allowing to shift the block number back of a predefined offset.
+- [Transformer](./transformer.md): Allows intercepting and
+ transforming a transaction to be broadcasted via a proxy wallet.
\ No newline at end of file
diff --git a/book/middleware/nonce-manager.md b/book/middleware/nonce-manager.md
new file mode 100644
index 00000000..b51c26bc
--- /dev/null
+++ b/book/middleware/nonce-manager.md
@@ -0,0 +1,5 @@
+# Nonce manager
+
+```rust
+{{#include ../../examples/middleware/examples/nonce_manager.rs}}
+```
\ No newline at end of file
diff --git a/book/middleware/policy.md b/book/middleware/policy.md
new file mode 100644
index 00000000..cad251f7
--- /dev/null
+++ b/book/middleware/policy.md
@@ -0,0 +1,5 @@
+# Policy middleware
+
+```rust
+{{#include ../../examples/middleware/examples/policy.rs}}
+```
\ No newline at end of file
diff --git a/book/middleware/signer.md b/book/middleware/signer.md
new file mode 100644
index 00000000..4d27808e
--- /dev/null
+++ b/book/middleware/signer.md
@@ -0,0 +1,5 @@
+# Signer
+
+```rust
+{{#include ../../examples/middleware/examples/signer.rs}}
+```
\ No newline at end of file
diff --git a/book/middleware/time-lag.md b/book/middleware/time-lag.md
new file mode 100644
index 00000000..c2d3769b
--- /dev/null
+++ b/book/middleware/time-lag.md
@@ -0,0 +1,3 @@
+# Time lag
+
+TODO
\ No newline at end of file
diff --git a/book/middleware/transformer.md b/book/middleware/transformer.md
new file mode 100644
index 00000000..83319ef3
--- /dev/null
+++ b/book/middleware/transformer.md
@@ -0,0 +1,3 @@
+# Transformer
+
+TODO
\ No newline at end of file