diff --git a/docs/nameservers.md b/docs/nameservers.md
index ad6e53c8d..ddac2684e 100644
--- a/docs/nameservers.md
+++ b/docs/nameservers.md
@@ -5,28 +5,29 @@ title: Nameservers
 
 # Nameservers
 
-DNSControl can handle a variety of provider scenarios for you.
+{% highlight javascript %}
+{% endhighlight %}
 
-- The same provider is the registrar and DNS server
-- Different providers for the registrar and DNS server
-- A registrar plus multiple DNS servers
-- Additional "shadow" DNS servers (non-authoratative DNS servers,
-  often used as backups or as a local cache)
+DNSControl can handle a variety of provider scenarios. The registrar and DNS
+provider can be the same company, different company, they can even be unknown!
+The document shows examples of many common and uncommon configurations.
 
-# Examples:
+* TOC
+{:toc}
 
-{% include startExample.html %}
-{% highlight js %}
+## Constants
 
+All the examples use the variables.  Substitute your own.
+
+{% highlight javascript %}
 // ========== Registrars:
 
-// A normal registrar.
+// A typical registrar.
 var REG_NAMECOM = NewRegistrar("namedotcom_main", "NAMEDOTCOM");
-// The "NONE" registrar is a "fake" registrar that makes no changes.
-// This is useful if you don't want DNSControl to control who the
-// nameservers are for a domain, or if you use a registrar that doesn't
-// offer an API, or if the registrar's API is not implemented in
-// DNSControl.
+
+// The "NONE" registrar is a "fake" registrar.
+// This is useful if the registrar is not supported by DNSControl,
+// or if you don't want to control the domain's delegation.
 var REG_THIRDPARTY = NewRegistrar("ThirdParty", "NONE");
 
 // ========== DNS Providers:
@@ -36,137 +37,209 @@ var DNS_AWS = NewDnsProvider("aws_main", "ROUTE53");
 var DNS_GOOGLE = NewDnsProvider("gcp_main", "GCLOUD");
 var DNS_CLOUDFLARE = NewDnsProvider("cloudflare_main", "CLOUDFLAREAPI");
 var DNS_BIND = NewDnsProvider("bind", "BIND");
+{% endhighlight %}
 
-// ========== Domains:
+## Same provider for REG and DNS
 
-// ========== Same provider for REG and DNS.
+Purpose:
+Use the same provider as a registrar and DNS service.
 
-// Keep it simple: Use the same provider as a registrar and DNS service.
-// Why? Simplicity.
+Why?
+Simplicity.
+
+{% highlight javascript %}
 D("example1.com", REG_NAMECOM,
   DnsProvider(DNS_NAMECOM),
   A("@", "10.2.3.4")
 );
+{% endhighlight %}
 
-// ========== Different provider for REG and DNS.
+## Different provider for REG and DNS
 
-// "Separate DNS server": Use one provider as registrar, a different for DNS service.
-// Why? Use any registrar but a preferred DNS provider.
-// This is the most common situation.
+Purpose:
+Use one provider as registrar, a different for DNS service.
+
+Why?
+Some registrars do not provide DNS server, or their service is sub-standard and
+you want to use a high-performance DNS server.
+
+
+{% highlight javascript %}
 D("example1.com", REG_NAMECOM,
   DnsProvider(DNS_AWS),
   A("@", "10.2.3.4")
 );
+{% endhighlight %}
 
-// ========== Registrar is elsewhere.
+## Registrar is elsewhere
 
-// "DNS only": Let someone else manage the NS records for a dommain.
-// Why? Because you don't have access to the registrar, or the registrar is not
-// supported by DNSControl. However you do have API access for
-// updating the zone's records (most likely at a different provider).
+Purpose:
+This is a "DNS only" configuration.  Use it when you don't control the
+registrar but you do control the DNS records.
+
+Why?
+You don't have access to the registrar, or the registrar is not
+supported by DNSControl. However you do have API access for
+updating the zone's records (most likely at a different provider).
+
+{% highlight javascript %}
 D("example1.com", REG_THIRDPARTY,
   DnsProvider(DNS_NAMECOM),
   A("@", "10.2.3.4")
 );
+{% endhighlight %}
 
-// ========== Zone is elsewhere.
+## Zone is elsewhere
 
-// "Registrar only": Direct the registrar to point to some other DNS provider.
-// Why? In this example we're pointing the domain to the nsone.net DNS
-// service, which someone else is controlling.
+Purpose:
+This is a "Registar only" configuration.  Use it when you control the registar but want to delegate the zone to someone else.
+
+Why?
+We are delegating the domain to someone else. In this example we're
+pointing the domain to the nsone.net DNS service, which someone else is
+controlling.
+
+{% highlight javascript %}
 D("example1.com", REG_NAMECOM,
   NAMESERVER("dns1.p03.nsone.net."),
   NAMESERVER("dns2.p03.nsone.net."),
   NAMESERVER("dns3.p03.nsone.net."),
   NAMESERVER("dns4.p03.nsone.net."),
 );
+{% endhighlight %}
 
-// ========== Override nameservers.
+## Override nameservers
 
-// "Custom nameservers": Ignore the provider's default nameservers and substitute our own.
-// Why? Rarely used unless the DNS provider's API does not support
-// querying what the nameservers are, or the API is returning invalid
-// data, or if during initial setup the API returns no information.
+Purpose:
+Ignore the provider's default nameservers and substitute our own.
+
+Why?
+Rarely used unless the DNS provider's API does not support querying what the
+nameservers are, or the API is returning invalid data, or if the API returns no
+information.  Sometimes APIs return no (useful) information when the domain
+is new; this is a good temporary work-around until the API starts working.
+
+{% highlight javascript %}
 D("example1.com", REG_NAMECOM,
-  DnsProvider(DNS_CLOUDFLARE, 0),  // Set the DNS provider but ignore the nameservers it suggests (0 == take zero of the names it reports)
+  DnsProvider(DNS_CLOUDFLARE, 0),  // Set the DNS provider but ignore the nameservers it suggests (0 == take none of the names it reports)
   NAMESERVER("kim.ns.cloudflare.com."),
   NAMESERVER("walt.ns.cloudflare.com."),
   A("@", "10.2.3.4")
 );
+{% endhighlight %}
 
-// ========== Add nameservers.
+## Add nameservers
 
-// "Add additional nameservers." Use the default nameservers from the registrar but add additional ones.
-// Why? Usually only to correct a bug or misconfiguration elsewhere.
+Purpose:
+Use the default nameservers from the registrar but add additional ones.
+
+Why?
+Usually only to correct a bug or misconfiguration elsewhere.
+
+{% highlight javascript %}
 D("example1.com", REG_NAMECOM,
   DnsProvider(DNS_NAMECOM),
   NAMESERVER("ns1.myexample.tld"),
   A("@", "10.2.3.4")
 );
+{% endhighlight %}
 
-// ========== Shadow nameservers.
+## Shadow nameservers
 
-// "Shadow DNS servers."  Secretly send your DNS records to another server.
-// Why? Many possibilities:
-/  * You are preparing to move to a different DNS provider and want to test it before you cut over.
-/  * You want your DNS records stored somewhere else in case you have to switch over in an emergency.
-/  * You are sending the zone to a local caching DNS server.
+Purpose:
+Secretly publish your DNS zone records to another server.
+
+Why?
+There are many reasons to do this:
+
+* You are preparing to move to a different DNS provider and want to test it before you cut over.
+* You want your DNS records stored somewhere else in case you have to switch over in an emergency.
+* You are sending the zone to a local caching DNS server.
+
+{% highlight javascript %}
 D("example1.com", REG_NAMECOM,
   DnsProvider(DNS_NAMECOM), // Our real DNS server
   DnsProvider(DNS_CLOUDFLARE, 0), // Quietly send a copy of the zone here.
   DnsProvider(DNS_BIND, 0), // And here too!
   A("@", "10.2.3.4")
 );
+{% endhighlight %}
 
-// ========== Backup your zone.
+## Backup your zone
 
-// "Zonefile backups." Make backups of the exact DNS records in zone-file format.
-// Why? In addition to the usual configuration, write out a BIND-style
-// zonefile perhaps for debugging, historical, or auditing purposes.
-// NOTE: This won't work if you use pseudo rtypes that BIND doesn't support.
+Purpose:
+Make backups of DNS records in a zone.  This generates a zonefile listing all
+the records in the zone.
+
+Why?
+You want to write out a BIND-style zonefile for debugging, historical, or
+auditing purposes. Some sites do backups of these zonefiles to create a history
+of changes. This is different than keeping a history of `dnsconfig.js` because
+this is the output of DNSControl, not the input.
+
+NOTE: This won't work if you use pseudo rtypes that BIND doesn't support.
+
+{% highlight javascript %}
 D("example1.com", REG_NAMECOM,
   DnsProvider(DNS_NAMECOM),
   DnsProvider(DNS_BIND, 0), // Don't activate any nameservers related to BIND.
   A("@", "10.2.3.4")
 );
+{% endhighlight %}
 
-// ========== Dual DNS Providers.
+## Dual DNS Providers
 
-// "Dual DNS Providers": Use two different DNS services:
-// Why? Diversity. If one DNS provider goes down, the other will be used.
-// Little known fact: Most DNS recursive resolvers monitor which DNS
-// servers are performing the best and automatically start avoiding
-// the slow or down servers. This means that if you use this technique
-// and one DNS provider goes down (like the famous Dyn outage), after a
-// while your users won't be affected.  Not all software does this
-// properly.
-// More info: https://www.dns-oarc.net/files/workshop-201203/OARC-workshop-London-2012-NS-selection.pdf
-// NOTE: This is overkill unless you have millions of users and strict up-time requirements.
+Purpose:
+Use two different DNS services:
+
+Why?
+Diversity. If one DNS provider goes down, the other will be used.
+
+Little known fact: Most DNS recursive resolvers monitor which DNS
+servers are performing the best and automatically start avoiding
+servers that are slow or down. This means that if you use this technique
+and one DNS provider goes down, after a
+while your users won't be affected.  Not all software does this properly.
+More info: https://www.dns-oarc.net/files/workshop-201203/OARC-workshop-London-2012-NS-selection.pdf
+
+NOTE: This is overkill unless you have millions of users and strict up-time requirements.
+
+{% highlight javascript %}
 D("example1.com", REG_NAMECOM,
   DnsProvider(DNS_AWS, 2),  // Take 2 nameservers from AWS
   DnsProvider(DNS_GOOGLE, 2),  // Take 2 nameservers from GCP
   A("@", "10.2.3.4")
 );
+{% endhighlight %}
 
-// ========== Fancy macros
+# Helper macros
 
-// There are some built-in macros that you might find useful.
+DNSControl has some built-in macros that you might find useful.
 
-// DOMAIN_ELSEWHERE: This macro points the domain's delegation
-// (nameservers) to a list of DNS servers.
+## `DOMAIN_ELSEWHERE`
+
+Easily delegate a domain to a specific list of nameservers.
+
+{% highlight javascript %}
 DOMAIN_ELSEWHERE("example1.com", REG_NAMECOM, [
     "dns1.example.net.",
     "dns2.example.net.",
     "dns3.example.net.",
 ]);
+{% endhighlight %}
 
-// DOMAIN_ELSEWHERE_AUTO: Similar to DOMAIN_ELSEWHERE but the list
-// of nameservers is queried from the API of a DNS provider.
+## `DOMAIN_ELSEWHERE_AUTO`
+
+Easily delegate a domain to a nameservers via an API query.
+
+This is similar to `DOMAIN_ELSEWHERE` but the list
+of nameservers is queried from the API of a single DNS provider.
+
+{% highlight javascript %}
 DOMAIN_ELSEWHERE_AUTO("example1.com", REG_NAMECOM, DNS_AWS);
 DOMAIN_ELSEWHERE_AUTO("example2.com", REG_NAMECOM, DNS_GOOGLE);
+{% endhighlight %}
 
-{%endhighlight%}
-{% include endExample.html %}
-
+# Warning!
 
 {% include alert.html text="Note: Not all providers allow full control over the NS records of your zone. It is not recommended to use these providers in complicated scenarios such as hosting across multiple providers. See individual provider docs for more info." %}