16 files changed, 101 insertions, 78 deletions
diff --git a/plugin/auto/README.md b/plugin/auto/README.md
index 6d65cff1d..9902ffe8c 100644
--- a/plugin/auto/README.md
+++ b/plugin/auto/README.md
@@ -37,9 +37,11 @@ are used.
 All directives from the *file* plugin are supported. Note that *auto* will load all zones found,
 even though the directive might only receive queries for a specific zone. I.e:
 
-~~~
-auto example.org {
-    directory /etc/coredns/zones
+~~~ corefile
+. {
+    auto example.org {
+        directory /etc/coredns/zones
+    }
 }
 ~~~
 Will happily pick up a zone for `example.COM`, except it will never be queried, because the *auto*
diff --git a/plugin/autopath/README.md b/plugin/autopath/README.md
index 4d3125dbf..a1a87981c 100644
--- a/plugin/autopath/README.md
+++ b/plugin/autopath/README.md
@@ -11,7 +11,7 @@ element in it) to the name of this answer.
 ## Syntax
 
 ~~~
-autopath [ZONE..] RESOLV-CONF
+autopath [ZONE...] RESOLV-CONF
 ~~~
 
 * **ZONES** zones *autopath* should be authoritative for.
diff --git a/plugin/cache/README.md b/plugin/cache/README.md
index 81cadcedb..9adb4582f 100644
--- a/plugin/cache/README.md
+++ b/plugin/cache/README.md
@@ -10,7 +10,7 @@ cache [TTL] [ZONES...]
 
 * **TTL** max TTL in seconds. If not specified, the maximum TTL will be used which is 3600 for
     noerror responses and 1800 for denial of existence ones.
-    Setting a TTL of 300 *cache 300* would cache the record up to 300 seconds.
+    Setting a TTL of 300: `cache 300` would cache the record up to 300 seconds.
 * **ZONES** zones it should cache for. If empty, the zones from the configuration block are used.
 
 Each element in the cache is cached according to its TTL (with **TTL** as the max).
@@ -45,10 +45,10 @@ The minimum TTL allowed on resource records is 5 seconds.
 
 If monitoring is enabled (via the *prometheus* directive) then the following metrics are exported:
 
-* coredns_cache_size{type} - Total elements in the cache by cache type.
-* coredns_cache_capacity{type} - Total capacity of the cache by cache type.
-* coredns_cache_hits_total{type} - Counter of cache hits by cache type.
-* coredns_cache_misses_total - Counter of cache misses.
+* `coredns_cache_size{type}` - Total elements in the cache by cache type.
+* `coredns_cache_capacity{type}` - Total capacity of the cache by cache type.
+* `coredns_cache_hits_total{type}` - Counter of cache hits by cache type.
+* `coredns_cache_misses_total{}` - Counter of cache misses.
 
 Cache types are either "denial" or "success".
 
@@ -56,8 +56,11 @@ Cache types are either "denial" or "success".
 
 Enable caching for all zones, but cap everything to a TTL of 10 seconds:
 
-~~~
-cache 10
+~~~ corefile
+. {
+    cache 10
+    whoami
+}
 ~~~
 
 Proxy to Google Public DNS and only cache responses for example.org (or below).
diff --git a/plugin/debug/README.md b/plugin/debug/README.md
index 47ee9b761..b3dab62d9 100644
--- a/plugin/debug/README.md
+++ b/plugin/debug/README.md
@@ -2,8 +2,8 @@
 
 *debug* disables the automatic recovery upon a CoreDNS crash so that you'll get a nice stack trace.
 
-Note that the *errors* plugin (if loaded) will also set a `recover` negating this setting.
-The main use of *debug* is to help testing.
+Note that the *errors* plugin (if loaded) will also set a `recover` negating this setting. The main
+use of *debug* is to help testing.
 
 ## Syntax
 
diff --git a/plugin/dnssec/README.md b/plugin/dnssec/README.md
index e087f6c9a..bf560464d 100644
--- a/plugin/dnssec/README.md
+++ b/plugin/dnssec/README.md
@@ -17,33 +17,31 @@ Authenticated denial of existence is implemented with NSEC black lies. Using ECD
 is preferred as this leads to smaller signatures (compared to RSA). NSEC3 is *not* supported.
 
 If multiple *dnssec* plugins are specified in the same zone, the last one specified will be
-used ( see [bugs](#bugs) ).
+used (See [bugs](#bugs)).
 
-* `ZONES` zones that should be signed. If empty, the zones from the configuration block
+* **ZONES** zones that should be signed. If empty, the zones from the configuration block
     are used.
 
-* `key file` indicates that key file(s) should be read from disk. When multiple keys are specified, RRsets
+* `key file` indicates that **KEY** file(s) should be read from disk. When multiple keys are specified, RRsets
   will be signed with all keys. Generating a key can be done with `dnssec-keygen`: `dnssec-keygen -a
   ECDSAP256SHA256 <zonename>`. A key created for zone *A* can be safely used for zone *B*. The name of the
   key file can be specified as one of the following formats
 
     * basename of the generated key `Kexample.org+013+45330`
-
     * generated public key `Kexample.org+013+45330.key`
-
     * generated private key `Kexample.org+013+45330.private`
 
 * `cache_capacity` indicates the capacity of the cache. The dnssec plugin uses a cache to store
-  RRSIGs. The default capacity is 10000.
+  RRSIGs. The default for **CAPACITY** is 10000.
 
 ## Metrics
 
 If monitoring is enabled (via the *prometheus* directive) then the following metrics are exported:
 
-* coredns_dnssec_cache_size{type} - total elements in the cache, type is "signature".
-* coredns_dnssec_cache_capacity{type} - total capacity of the cache, type is "signature".
-* coredns_dnssec_cache_hits_total - Counter of cache hits.
-* coredns_dnssec_cache_misses_total - Counter of cache misses.
+* `coredns_dnssec_cache_size{type}` - total elements in the cache, type is "signature".
+* `coredns_dnssec_cache_capacity{type}` - total capacity of the cache, type is "signature".
+* `coredns_dnssec_cache_hits_total{}` - Counter of cache hits.
+* `coredns_dnssec_cache_misses_total{}` - Counter of cache misses.
 
 ## Examples
 
diff --git a/plugin/dnstap/README.md b/plugin/dnstap/README.md
index d91c9422c..15c2b4f38 100644
--- a/plugin/dnstap/README.md
+++ b/plugin/dnstap/README.md
@@ -36,26 +36,26 @@ dnstap tcp://127.0.0.1:6000 full
 ## Dnstap command line tool
 
 ~~~ sh
-go get github.com/dnstap/golang-dnstap
-cd $GOPATH/src/github.com/dnstap/golang-dnstap/dnstap
-go build
-./dnstap
+% go get github.com/dnstap/golang-dnstap
+% cd $GOPATH/src/github.com/dnstap/golang-dnstap/dnstap
+% go build
+% ./dnstap
 ~~~
 
 The following command listens on the given socket and decodes messages to stdout.
 
 ~~~ sh
-dnstap -u /tmp/dnstap.sock
+% dnstap -u /tmp/dnstap.sock
 ~~~
 
 The following command listens on the given socket and saves message payloads to a binary dnstap-format log file.
 
 ~~~ sh
-dnstap -u /tmp/dnstap.sock -w /tmp/test.dnstap
+% dnstap -u /tmp/dnstap.sock -w /tmp/test.dnstap
 ~~~
 
 Listen for dnstap messages on port 6000.
 
 ~~~ sh
-dnstap -l 127.0.0.1:6000
+% dnstap -l 127.0.0.1:6000
 ~~~
diff --git a/plugin/etcd/README.md b/plugin/etcd/README.md
index 383200771..8b8680f25 100644
--- a/plugin/etcd/README.md
+++ b/plugin/etcd/README.md
@@ -4,8 +4,8 @@
 a [message](https://github.com/skynetservices/skydns/blob/2fcff74cdc9f9a7dd64189a447ef27ac354b725f/msg/service.go#L26)
 like [SkyDNS](https://github.com/skynetservices/skydns). It should also work just like SkyDNS.
 
-The etcd plugin makes extensive use of the proxy plugin to forward and query other servers
-in the network.
+The etcd plugin makes extensive use of the proxy plugin to forward and query other servers in the
+network.
 
 ## Syntax
 
@@ -15,8 +15,8 @@ etcd [ZONES...]
 
 * **ZONES** zones etcd should be authoritative for.
 
-The path will default to `/skydns` the local etcd proxy (http://localhost:2379).
-If no zones are specified the block's zone will be used as the zone.
+The path will default to `/skydns` the local etcd proxy (http://localhost:2379). If no zones are
+specified the block's zone will be used as the zone.
 
 If you want to `round robin` A and AAAA responses look at the `loadbalance` plugin.
 
@@ -103,7 +103,7 @@ Next you'll need to populate the zone with reverse records, here we add a revers
 
 Querying with dig:
 
-~~~
+~~~ sh
 % dig @localhost -x 10.0.0.127 +short
-reverse.atoom.net.
+reverse.skydns.local.
 ~~~
diff --git a/plugin/health/README.md b/plugin/health/README.md
index b386491bb..8212aab9f 100644
--- a/plugin/health/README.md
+++ b/plugin/health/README.md
@@ -18,6 +18,8 @@ supports health checks has a section "Health" in their README.
 
 Run another health endpoint on http://localhost:8091.
 
-~~~
-health localhost:8091
+~~~ corefile
+. {
+    health localhost:8091
+}
 ~~~
diff --git a/plugin/hosts/README.md b/plugin/hosts/README.md
index 5e6ab0ec7..e792ff207 100644
--- a/plugin/hosts/README.md
+++ b/plugin/hosts/README.md
@@ -29,8 +29,10 @@ hosts [FILE [ZONES...]] {
 
 Load `/etc/hosts` file.
 
-~~~
-hosts
+~~~ corefile
+. {
+    hosts
+}
 ~~~
 
 Load `example.hosts` file in the current directory.
diff --git a/plugin/kubernetes/README.md b/plugin/kubernetes/README.md
index cc8f09c49..f7887f74d 100644
--- a/plugin/kubernetes/README.md
+++ b/plugin/kubernetes/README.md
@@ -36,6 +36,7 @@ kubernetes [ZONES...] {
     fallthrough
 }
 ```
+
 * `resyncperiod` specifies the Kubernetes data API **DURATION** period.
 * `endpoint` specifies the **URL** for a remove k8s API endpoint.
    If omitted, it will connect to k8s in-cluster using the cluster service account.
diff --git a/plugin/loadbalance/README.md b/plugin/loadbalance/README.md
index 1cce54ebf..35a0a396c 100644
--- a/plugin/loadbalance/README.md
+++ b/plugin/loadbalance/README.md
@@ -17,6 +17,11 @@ loadbalance [POLICY]
 
 ## Examples
 
-~~~
-loadbalance round_robin
+Load balance replies coming back from Google Public DNS:
+
+~~~ corefile
+. {
+    loadbalance round_robin
+    proxy . 8.8.8.8 8.8.4.4
+}
 ~~~
diff --git a/plugin/log/README.md b/plugin/log/README.md
index 223888ccc..aeeca4929 100644
--- a/plugin/log/README.md
+++ b/plugin/log/README.md
@@ -11,23 +11,22 @@ log
 * With no arguments, a query log entry is written to *stdout* in the common log format for all requests
 
 ~~~ txt
-log FILE
+log [stdout]
 ~~~
 
-* **FILE** is the log file to create (or append to). The *only* valid name for **FILE** is *stdout*.
+Or if you want/need slightly more control:
 
 ~~~ txt
-log [NAME] FILE [FORMAT]
+log [NAME] stdout [FORMAT]
 ~~~
 
 * `NAME` is the name to match in order to be logged
-* `FILE` is the log file (again only *stdout* is allowed here).
 * `FORMAT` is the log format to use (default is Common Log Format)
 
 You can further specify the class of responses that get logged:
 
 ~~~ txt
-log [NAME] FILE [FORMAT] {
+log [NAME] stdout [FORMAT] {
     class [success|denial|error|all]
 }
 ~~~
@@ -43,11 +42,6 @@ classes have the following meaning:
 
 If no class is specified, it defaults to *all*.
 
-## Log File
-
-The "log file" can only be *stdout*. CoreDNS expects another service to pick up this output and deal
-with it, i.e. journald when using systemd or Docker's logging capabilities.
-
 ## Log Format
 
 You can specify a custom log format with any placeholder values. Log supports both request and
@@ -83,20 +77,27 @@ The default Common Log Format is:
 
 Log all requests to stdout
 
-~~~
-log stdout
+~~~ corefile
+. {
+    log
+    whoami
+}
 ~~~
 
 Custom log format, for all zones (`.`)
 
-~~~
-log . stdout "{proto} Request: {name} {type} {>id}"
+~~~ corefile
+. {
+    log . stdout "{proto} Request: {name} {type} {>id}"
+}
 ~~~
 
 Only log denials for example.org (and below to a file)
 
-~~~
-log example.org stdout {
-    class denial
+~~~ corefile
+. {
+    log example.org stdout {
+        class denial
+    }
 }
 ~~~
diff --git a/plugin/metrics/README.md b/plugin/metrics/README.md
index 8e84c57bf..714b17bd2 100644
--- a/plugin/metrics/README.md
+++ b/plugin/metrics/README.md
@@ -5,13 +5,13 @@
 The default location for the metrics is `localhost:9153`. The metrics path is fixed to `/metrics`.
 The following metrics are exported:
 
-* coredns_dns_request_count_total{zone, proto, family}
-* coredns_dns_request_duration_milliseconds{zone}
-* coredns_dns_request_size_bytes{zone, proto}
-* coredns_dns_request_do_count_total{zone}
-* coredns_dns_request_type_count_total{zone, type}
-* coredns_dns_response_size_bytes{zone, proto}
-* coredns_dns_response_rcode_count_total{zone, rcode}
+* `coredns_dns_request_count_total{zone, proto, family}` - total query count.
+* `coredns_dns_request_duration_milliseconds{zone}` - duration to process each query.
+* `coredns_dns_request_size_bytes{zone, proto}` - size of the request in bytes.
+* `coredns_dns_request_do_count_total{zone}` -  queries that have the DO bit set
+* `coredns_dns_request_type_count_total{zone, type}` - counter of queries per zone and type.
+* `coredns_dns_response_size_bytes{zone, proto}` - response size in bytes.
+* `coredns_dns_response_rcode_count_total{zone, rcode}` - response per zone and rcode.
 
 Each counter has a label `zone` which is the zonename used for the request/response.
 
@@ -27,7 +27,6 @@ Extra labels used are:
 If monitoring is enabled, queries that do not enter the plugin chain are exported under the fake
 name "dropped" (without a closing dot - this is never a valid domain name).
 
-
 ## Syntax
 
 ~~~
diff --git a/plugin/pprof/README.md b/plugin/pprof/README.md
index c1da992ca..8e57d25d0 100644
--- a/plugin/pprof/README.md
+++ b/plugin/pprof/README.md
@@ -6,7 +6,7 @@ You can visit `/debug/pprof` on your site for an index of the available endpoint
 will listen on localhost:6053.
 
 > This is a debugging tool. Certain requests (such as collecting execution traces) can be slow. If
-> you use pprof on a live site, consider restricting access or enabling it only temporarily.
+> you use pprof on a live server, consider restricting access or enabling it only temporarily.
 
 For more information, please see [Go's pprof
 documentation](https://golang.org/pkg/net/http/pprof/) and read
@@ -25,12 +25,14 @@ If not specified, ADDRESS defaults to localhost:6053.
 Enable pprof endpoints:
 
 ~~~
-pprof
+. {
+    pprof
+}
 ~~~
 
 Listen on an alternate address:
 
-~~~
+~~~ txt
 . {
     pprof 10.9.8.7:6060
 }
@@ -38,6 +40,8 @@ Listen on an alternate address:
 
 Listen on an all addresses on port 6060:
 
-~~~
-pprof :6060
+~~~ txt
+. {
+    pprof :6060
+}
 ~~~
diff --git a/plugin/rewrite/README.md b/plugin/rewrite/README.md
index 747e58e11..00f263fb9 100644
--- a/plugin/rewrite/README.md
+++ b/plugin/rewrite/README.md
@@ -48,14 +48,19 @@ This has two fields, code and data. A match is defined as having the same code.
 
 * A string data can be treated as hex if it starts with `0x`. Example:
 
-~~~
-rewrite edns0 local set 0xffee 0x61626364
+~~~ corefile
+. {
+    rewrite edns0 local set 0xffee 0x61626364
+    whoami
+}
 ~~~
 
 rewrites the first local option with code 0xffee, setting the data to "abcd". Equivalent:
 
-~~~
-rewrite edns0 local set 0xffee abcd
+~~~ corefile
+. {
+    rewrite edns0 local set 0xffee abcd
+}
 ~~~
 
 * A variable data is specified with a pair of curly brackets `{}`. Following are the supported variables:
@@ -86,9 +91,8 @@ length is used to extract the client subnet from the source IP address in the qu
 Example:
 
 ~~~
-   rewrite edns0 subnet set 24 56
+rewrite edns0 subnet set 24 56
 ~~~
 
 * If the query has source IP as IPv4, the first 24 bits in the IP will be the network subnet.
 * If the query has source IP as IPv6, the first 56 bits in the IP will be the network subnet.
-
diff --git a/plugin/whoami/README.md b/plugin/whoami/README.md
index d16a93766..7d231ba26 100644
--- a/plugin/whoami/README.md
+++ b/plugin/whoami/README.md
@@ -3,6 +3,8 @@
 *whoami* returns your resolver's local IP address, port and transport. Your IP address is returned
  in the additional section as either an A or AAAA record.
 
+When CoreDNS can find a Corefile to load, this is the default plugin it loads.
+
 The reply always has an empty answer section. The port and transport are included in the additional
 section as a SRV record, transport can be "tcp" or "udp".