solution: update docs layout to better suit github formatter

docs/06-methods.adoc

@@ -107,6 +107,7 @@ Where:
 Subscribes to changes of the balance for a single address or a set of addresses
 
 .Request
+[source,proto]
 ----
 message BalanceRequest {
     Asset asset = 1;
@@ -124,6 +125,7 @@ message AnyAddress {
 ----
 
 .Response
+[source,proto]
 ----
 message AddressBalance {
     Asset asset = 1;
@@ -138,6 +140,7 @@ Subscribes to transaction confirmations. Allows to send a transactions and then
 gets enough confirmations. Changes is `NOTFOUND -> BROADCASTED <- -> MINED <- -> CONFIRMED`
 
 .Request
+[source,proto]
 ----
 message TxStatusRequest {
     ChainRef chain = 1;
@@ -147,6 +150,7 @@ message TxStatusRequest {
 ----
 
 .Response (stream of)
+[source,proto]
 ----
 message TxStatus {
     string tx_id = 1;

docs/07-authentication.adoc

@@ -13,6 +13,7 @@ generate certificates, but traditional `openssl` tool can be used as well.
 ==== Setup Server certificate
 
 .Generate a server certificate
+[source,bash]
 ----
 SERVER_CA="ca.myhost.dev"
 SERVER_IP="127.0.0.1"
@@ -27,6 +28,7 @@ openssl pkcs8 -topk8 -inform PEM -outform PEM -in out/$SERVER_IP.key -out out/$S
 ----
 
 .Update dshackle.yaml to have:
+[source,yaml]
 ----
 version: v1
 port: 9001
@@ -38,6 +40,7 @@ tls:
 ----
 
 .Verify that server uses the certificate
+[source,bash]
 ----
 openssl s_client -alpn h2 -connect 127.0.0.1:9001 -CAfile out/ca.myhost.dev.crt
 ----
@@ -52,6 +55,7 @@ To have authentication in both ways you'll need to configure client side certifi
 will also verify each incoming connection and allow to connect only by a client with a trusted certificate.
 
 .Generate a client certificate
+[source,bash]
 ----
 CLIENT_CA="client-ca.myhost.dev"
 CLIENT_ID="client_1"
@@ -64,6 +68,7 @@ certstrap sign "$CLIENT_ID" --CA $CLIENT_CA
 ----
 
 .Update dshackle.yaml to have:
+[source,yaml]
 ----
 version: v1
 port: 9001
@@ -78,6 +83,7 @@ tls:
 ----
 
 .Verify connection with client certificate
+[source,bash]
 ----
 openssl s_client -alpn h2 -connect 127.0.0.1:9001 -CAfile out/ca.myhost.dev.crt -cert out/client_1.crt -key out/client_1.key
 ----

docs/README.adoc

@@ -1,6 +1,35 @@
 = Dshackle Documentation
 
-include::00-intro.adoc[]
+== What is Dshackle
+
+Dshackle is a L7 Load Balancer for Blockchain APIs with automatic discovery, health checking, secure access, TLS with
+client authentication, and many other features. It can be configured as an edge proxy, middle proxy or API gateway.
+
+Dshackle provided a high level aggregated API on top of several underlying upstreams (blockchain nodes or providers,
+such as Geth, Parity, Infura, etc), automatically verifies their availability and the current status of the network,
+it routes requests to available node, and makes sure the response is consistent and/or data successfully broadcasted to
+the networks.
+
+Example use cases:
+
+- Query for a _transaction_ (block, etc) tries to find it on different nodes and/or retry until it's found or there is
+a consistent answer from upstreams
+- Getting _nonce_ to send a transaction makes sure it's larges value over several nodes
+- Sending _transaction_ distributes it to several nodes in parallel
+
+Availability and fault tolerance:
+
+- Dshackle connects to several upstreams via JSON RPC, Websockets or gRPC protocols
+- It verifies if a node ("upstream") is fully synchronized (not in initial sync mode), has enough peers and its height
+is not behind other nodes
+- If an upstream lags behind, lost peers, started to resync, or simply goes down then Dshackle temporarily excludes it from
+routing and returns back when the the upstream's problem is fixed
+
+Main goals:
+
+- stable and fault tolerant access to blockchain nodes
+- secure connections and authentication
+- allow to build scalable APIs with nodes distributed over multiple data centers
 
 == Table of Content
 
@@ -15,4 +44,14 @@ include::00-intro.adoc[]
 . link:09-caching.adoc[Caching]
 . link:10-client-libraries.adoc[Client Libraries]
 
-include::99-ending.adoc[]
+== Chat
+
+image:https://badges.gitter.im/emeraldpay/community.svg[link="https://gitter.im/emeraldpay/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge]
+
+== Support
+
+Contact splix@emeraldpay.io if you want to integrate Dshackle into your project or want to sponsor the development.
+
+== Links
+
+- Github: https://github.com/emeraldpay/dshackle