' + + member.author.login + + '
' + + '' + + 'Page not found :(
+The requested page could not be found.
++ {% if page.prev_link %} + {{ page.prev_name }} + {% endif %} +
++ {% if page.top_link %} + {{ page.top_name }} + {% endif %} +
++ {% if page.next_link %} + {{ page.next_name }} + {% endif %} +
+' + + member.author.login + + '
' + + '' + + '
+feature-img: "assets/img/featured-bg.svg"
+hide: true
+---
+
+Faraday is an HTTP client library that provides a common interface over many adapters (such as Net::HTTP)
+and embraces the concept of Rack middleware when processing the request/response cycle.
+
+{: .text-center}
+[ Fork on GitHub][github]{: .btn}
+[ Chat with us][gitter]{: .btn}
+
+{: .mt-60}
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'faraday'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install faraday
+```
+
+You can also install the [`faraday_middleware`][faraday_middleware]
+extension gem to access a collection of useful Faraday middleware.
+
+{: .mt-60}
+
+{: .text-center}
+[ Read the docs][usage]{: .btn}
+
+[github]: https://github.com/lostisland/faraday
+[gitter]: https://gitter.im/lostisland/faraday
+[faraday_middleware]: https://github.com/lostisland/faraday_middleware
+[usage]: ./usage
diff --git a/docs/middleware/custom.md b/docs/middleware/custom.md
new file mode 100644
index 000000000..5fa82b78c
--- /dev/null
+++ b/docs/middleware/custom.md
@@ -0,0 +1,45 @@
+---
+layout: documentation
+title: "Writing Middleware"
+permalink: /middleware/custom
+hide: true
+top_name: Middleware
+top_link: ./
+prev_name: Available Middleware
+prev_link: ./list
+---
+
+Middleware are classes that implement a `call` instance method. They hook into
+the request/response cycle.
+
+```ruby
+def call(request_env)
+ # do something with the request
+ # request_env[:request_headers].merge!(...)
+
+ @app.call(request_env).on_complete do |response_env|
+ # do something with the response
+ # response_env[:response_headers].merge!(...)
+ end
+end
+```
+
+It's important to do all processing of the response only in the `on_complete`
+block. This enables middleware to work in parallel mode where requests are
+asynchronous.
+
+The `env` is a hash with symbol keys that contains info about the request and,
+later, response. Some keys are:
+
+```
+# request phase
+:method - :get, :post, ...
+:url - URI for the current request; also contains GET parameters
+:body - POST parameters for :post/:put requests
+:request_headers
+
+# response phase
+:status - HTTP response status code, such as 200
+:body - the response body
+:response_headers
+```
diff --git a/docs/middleware/index.md b/docs/middleware/index.md
new file mode 100644
index 000000000..5630c0244
--- /dev/null
+++ b/docs/middleware/index.md
@@ -0,0 +1,51 @@
+---
+layout: documentation
+title: "Middleware"
+permalink: /middleware
+next_name: Available Middleware
+next_link: ./list
+order: 3
+---
+
+A `Faraday::Connection` uses a `Faraday::RackBuilder` to assemble a
+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.
+
+
+
+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
+innermost one, so that must be the adapter.
+
+```ruby
+Faraday.new(...) do |conn|
+ # POST/PUT params encoders:
+ conn.request :multipart
+ conn.request :url_encoded
+
+ # Last middleware must be the adapter:
+ conn.adapter :net_http
+end
+```
+
+This request middleware setup affects POST/PUT requests in the following way:
+
+1. `Request::Multipart` checks for files in the payload, otherwise leaves
+ everything untouched;
+2. `Request::UrlEncoded` encodes as "application/x-www-form-urlencoded" if not
+ already encoded or of another type
+
+Swapping middleware means giving the other priority. Specifying the
+"Content-Type" for the request is explicitly stating which middleware should
+process it.
+
+Examples:
+
+```ruby
+# uploading a file:
+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
+```
diff --git a/docs/middleware/list.md b/docs/middleware/list.md
new file mode 100644
index 000000000..e912c195c
--- /dev/null
+++ b/docs/middleware/list.md
@@ -0,0 +1,50 @@
+---
+layout: documentation
+title: "Available Middleware"
+permalink: /middleware/list
+hide: true
+top_name: Middleware
+top_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
diff --git a/docs/middleware/request/authentication.md b/docs/middleware/request/authentication.md
new file mode 100644
index 000000000..00771c71f
--- /dev/null
+++ b/docs/middleware/request/authentication.md
@@ -0,0 +1,30 @@
+---
+layout: documentation
+title: "Authentication Middleware"
+permalink: /middleware/authentication
+hide: true
+next_name: Multipart Middleware
+next_link: ./multipart
+top_name: Back to Middleware
+top_link: ./list
+---
+
+Basic and Token authentication are handled by Faraday::Request::BasicAuthentication
+and Faraday::Request::TokenAuthentication respectively.
+These can be added as middleware manually or through the helper methods.
+
+### Basic Authentication
+
+```ruby
+Faraday.new(...) do |conn|
+ conn.basic_auth('username', 'password')
+end
+```
+
+### Token Authentication
+
+```ruby
+Faraday.new(...) do |conn|
+ conn.token_auth('authentication-token')
+end
+```
\ No newline at end of file
diff --git a/docs/middleware/request/instrumentation.md b/docs/middleware/request/instrumentation.md
new file mode 100644
index 000000000..33fcaae08
--- /dev/null
+++ b/docs/middleware/request/instrumentation.md
@@ -0,0 +1,45 @@
+---
+layout: documentation
+title: "Instrumentation Middleware"
+permalink: /middleware/instrumentation
+hide: true
+prev_name: Retry Middleware
+prev_link: ./retry
+next_name: Logger Middleware
+next_link: ./logger
+top_name: Back to Middleware
+top_link: ./list
+---
+
+The `Instrumentation` middleware allows to instrument requests using different tools.
+Options for this middleware include the instrumentation `name` and the `instrumenter` you want to use.
+They default to `request.faraday` and `ActiveSupport::Notifications` respectively, but you can provide your own:
+
+```ruby
+conn = Faraday.new(...) do |f|
+ f.request :instrumentation, name: 'custom_name', instrumenter: MyInstrumenter
+ ...
+end
+```
+
+### Example Usage
+
+The `Instrumentation` middleware will use `ActiveSupport::Notifications` by default as instrumenter,
+allowing you to subscribe to the default event name and instrument requests:
+
+```ruby
+conn = Faraday.new('http://example.com') do |f|
+ f.request :instrumentation
+ ...
+end
+
+ActiveSupport::Notifications.subscribe('request.faraday') do |name, starts, ends, _, env|
+ url = env[:url]
+ http_method = env[:method].to_s.upcase
+ duration = ends - starts
+ $stdout.puts '[%s] %s %s (%.3f s)' % [url.host, http_method, url.request_uri, duration]
+end
+
+conn.get('/search', { a: 1, b: 2 })
+#=> [example.com] GET /search?a=1&b=2 (0.529 s)
+```
diff --git a/docs/middleware/request/multipart.md b/docs/middleware/request/multipart.md
new file mode 100644
index 000000000..227246724
--- /dev/null
+++ b/docs/middleware/request/multipart.md
@@ -0,0 +1,43 @@
+---
+layout: documentation
+title: "Multipart Middleware"
+permalink: /middleware/multipart
+hide: true
+prev_name: Authentication Middleware
+prev_link: ./authentication
+next_name: UrlEncoded Middleware
+next_link: ./url-encoded
+top_name: Back to Middleware
+top_link: ./list
+---
+
+The `Multipart` middleware converts a `Faraday::Request#body` hash of key/value pairs into a multipart form request.
+This only happens if the middleware finds an object in the request body that responds to `content_type`.
+The middleware also automatically adds the boundary to the request body.
+You can use `Faraday::UploadIO` or `Faraday::CompositeReadIO` to wrap your multipart parameters,
+which are in turn wrappers of the equivalent classes from the [`multipart-post`][multipart_post] gem.
+
+### Example Usage
+
+```ruby
+conn = Faraday.new(...) do |f|
+ f.request :multipart
+ ...
+end
+```
+
+Payload can be a mix of POST data and UploadIO objects.
+
+```ruby
+payload = {
+ file_name: 'multipart_example.rb',
+ file: Faraday::UploadIO.new(__FILE__, 'text/x-ruby')
+}
+
+conn.post('/', payload)
+# POST with
+# Content-Type: "multipart/form-data; boundary=-----------RubyMultipartPost-b7f5d9a9b5f201e7af7d7af730ac4bf4"
+# Body: #Website and branding design: Elena Lo Piccolo
+