Improves middleware documentation adding a diagram.

docs/middleware/custom.md

@@ -1,8 +1,10 @@
 ---
-layout: page
+layout: documentation
 title: "Writing Middleware"
 permalink: /middleware/custom
 hide: true
+prev_name: Available Middleware
+prev_link: ./list
 ---
 
 ## Writing middleware

docs/middleware/env.md

@@ -1,8 +0,0 @@
----
-layout: page
-title: "Faraday Env"
-permalink: /middleware/env
-hide: true
----
-
-Faraday loves the environment.

docs/middleware/index.md

@@ -1,8 +1,10 @@
 ---
-layout: page
-title: "Middleware Usage"
+layout: documentation
+title: "Middleware Introduction"
 permalink: /middleware
 hide: true
+next_name: Available Middleware
+next_link: ./list
 ---
 
 A `Faraday::Connection` uses a `Faraday::RackBuilder` to assemble a
@@ -10,7 +12,7 @@ Rack-inspired middleware stack for making HTTP requests. Each middleware runs
 and passes an Env object around to the next one. After the final middleware has
 run, Faraday will return a `Faraday::Response` to the end user.
 
-## Advanced middleware usage
+![Middleware](../assets/img/middleware.png)
 
 The order in which middleware is stacked is important. Like with Rack, the
 first middleware on the list wraps all others, while the last middleware is the
@@ -47,39 +49,3 @@ payload[:profile_pic] = Faraday::UploadIO.new('/path/to/avatar.jpg', 'image/jpeg
 # "Multipart" middleware detects files and encodes with "multipart/form-data":
 conn.put '/profile', payload
 ```
-
-## Middleware Types
-
-### Request
-
-**Request middleware** can modify Request details before the Adapter runs. Most
-middleware set Header values or transform the request body based on the
-content type.
-
-* [`BasicAuthentication`][authentication] sets the `Authorization` header to the `user:password`
-base64 representation.
-* [`TokenAuthentication`][authentication] sets the `Authorization` header to the specified token.
-* [`Multipart`][multipart] converts a `Faraday::Request#body` hash of key/value pairs into a
-multipart form request.
-* [`UrlEncoded`][url_encoded] converts a `Faraday::Request#body` hash of key/value pairs into a url-encoded request body.
-* [`Retry`][retry] automatically retries requests that fail due to intermittent client
-or server errors (such as network hiccups).
-* [`Instrumentation`][instrumentation] allows to instrument requests using different tools.
-
-
-### Response
-
-**Response middleware** receives the response from the adapter and can modify its details
-before returning it.
-
-* [`Logger`][logger] logs both the request and the response body and headers.
-* [`RaiseError`][raise_error] checks the response HTTP code and raises an exception if it is a 4xx or 5xx code.
-
-
-[authentication]:       ./authentication
-[multipart]:            ./multipart
-[url_encoded]:          ./url-encoded
-[retry]:                ./retry
-[instrumentation]:      ./instrumentation
-[logger]:               ./logger
-[raise_error]:          ./raise-error

docs/middleware/list.md

@@ -0,0 +1,50 @@
+---
+layout: documentation
+title: "Available Middleware"
+permalink: /middleware/list
+hide: true
+prev_name: Middleware Introduction
+prev_link: ./
+next_name: Writing Middleware
+next_link: ./custom
+---
+
+Faraday ships with some useful middleware that you can use to customize your request/response lifecycle.
+Middleware are separated into two macro-categories: Request Middleware and Response Middleware.
+The former usually deal with the request, encoding the parameters or setting headers.
+The latter instead activate after the request is completed and a response has been received, like
+parsing the response body, logging useful info or checking the response status.  
+
+### Request Middleware
+
+**Request middleware** can modify Request details before the Adapter runs. Most
+middleware set Header values or transform the request body based on the
+content type.
+
+* [`BasicAuthentication`][authentication] sets the `Authorization` header to the `user:password`
+base64 representation.
+* [`TokenAuthentication`][authentication] sets the `Authorization` header to the specified token.
+* [`Multipart`][multipart] converts a `Faraday::Request#body` hash of key/value pairs into a
+multipart form request.
+* [`UrlEncoded`][url_encoded] converts a `Faraday::Request#body` hash of key/value pairs into a url-encoded request body.
+* [`Retry`][retry] automatically retries requests that fail due to intermittent client
+or server errors (such as network hiccups).
+* [`Instrumentation`][instrumentation] allows to instrument requests using different tools.
+
+
+### Response Middleware
+
+**Response middleware** receives the response from the adapter and can modify its details
+before returning it.
+
+* [`Logger`][logger] logs both the request and the response body and headers.
+* [`RaiseError`][raise_error] checks the response HTTP code and raises an exception if it is a 4xx or 5xx code.
+
+
+[authentication]:       ./authentication
+[multipart]:            ./multipart
+[url_encoded]:          ./url-encoded
+[retry]:                ./retry
+[instrumentation]:      ./instrumentation
+[logger]:               ./logger
+[raise_error]:          ./raise-error

docs/middleware/request/authentication.md

@@ -6,7 +6,7 @@ hide: true
 next_name: Multipart Middleware
 next_link: ./multipart
 top_name: Back to Middleware
-top_link: ./
+top_link: ./list
 ---
 
 Basic and Token authentication are handled by Faraday::Request::BasicAuthentication

docs/middleware/request/instrumentation.md

@@ -8,7 +8,7 @@ prev_link: ./retry
 next_name: Logger Middleware
 next_link: ./logger
 top_name: Back to Middleware
-top_link: ./
+top_link: ./list
 ---
 
 The `Instrumentation` middleware allows to instrument requests using different tools.

docs/middleware/request/multipart.md

@@ -8,7 +8,7 @@ prev_link: ./authentication
 next_name: UrlEncoded Middleware
 next_link: ./url-encoded
 top_name: Back to Middleware
-top_link: ./
+top_link: ./list
 ---
 
 The `Multipart` middleware converts a `Faraday::Request#body` hash of key/value pairs into a multipart form request.

docs/middleware/request/retry.md

@@ -8,7 +8,7 @@ prev_link: ./url-encoded
 next_name: Instrumentation Middleware
 next_link: ./instrumentation
 top_name: Back to Middleware
-top_link: ./
+top_link: ./list
 ---
 
 The `Retry` middleware automatically retries requests that fail due to intermittent client

docs/middleware/request/url_encoded.md

@@ -8,7 +8,7 @@ prev_link: ./multipart
 next_name: Retry Middleware
 next_link: ./retry
 top_name: Back to Middleware
-top_link: ./
+top_link: ./list
 ---
 
 The `UrlEncoded` middleware converts a `Faraday::Request#body` hash of key/value pairs into a url-encoded request body.

docs/middleware/response/logger.md

@@ -8,7 +8,7 @@ prev_link: ./instrumentation
 next_name: RaiseError Middleware
 next_link: ./raise-error
 top_name: Back to Middleware
-top_link: ./
+top_link: ./list
 ---
 
 The `Logger` middleware logs both the request and the response body and headers.

docs/middleware/response/raise_error.md

@@ -6,7 +6,7 @@ hide: true
 prev_name: Logger Middleware
 prev_link: ./logger
 top_name: Back to Middleware
-top_link: ./
+top_link: ./list
 ---
 
 The `RaiseError` middleware checks the response HTTP code and raises an exception if it is a 4xx or 5xx code.