DOCS: Clean up formatting and punctuation (#1776)

Co-authored-by: Tom Limoncelli <tlimoncelli@stackoverflow.com>

docs/_functions/domain/A.md

@@ -10,7 +10,7 @@ A adds an A record To a domain. The name should be the relative label for the re
 
 The address should be an ip address, either a string, or a numeric value obtained via [IP](#IP).
 
-Modifiers can be any number of [record modifiers](#record-modifiers) or json objects, which will be merged into the record's metadata.
+Modifiers can be any number of [record modifiers](#record-modifiers) or JSON objects, which will be merged into the record's metadata.
 
 {% capture example %}
 ```js

docs/_functions/domain/AAAA.md

@@ -10,7 +10,7 @@ AAAA adds an AAAA record To a domain. The name should be the relative label for
 
 The address should be an IPv6 address as a string.
 
-Modifiers can be any number of [record modifiers](#record-modifiers) or json objects, which will be merged into the record's metadata.
+Modifiers can be any number of [record modifiers](#record-modifiers) or JSON objects, which will be merged into the record's metadata.
 
 {% capture example %}
 ```js

docs/_functions/domain/TXT.md

@@ -16,7 +16,7 @@ Each string is a JavaScript string (quoted using single or double
 quotes).  The (somewhat complex) quoting rules of the DNS protocol
 will be done for you.
 
-Modifiers can be any number of [record modifiers](#record-modifiers) or json objects, which will be merged into the record's metadata.
+Modifiers can be any number of [record modifiers](#record-modifiers) or JSON objects, which will be merged into the record's metadata.
 
 {% capture example %}
 ```js

docs/_functions/global/FETCH.md

@@ -7,7 +7,7 @@ parameters:
 
 `FETCH` is a wrapper for the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). This allows dynamically setting DNS records based on an external data source, e.g. the API of your cloud provider.
 
-Compared to `fetch` from Fetch API, `FETCH` will call [PANIC](#PANIC) to terminate the execution of the script, and therefore DnsControl, if a network error occurs.
+Compared to `fetch` from Fetch API, `FETCH` will call [PANIC](#PANIC) to terminate the execution of the script, and therefore DNSControl, if a network error occurs.
 
 Otherwise the syntax of `FETCH` is the same as `fetch`.
 
@@ -16,7 +16,7 @@ Otherwise the syntax of `FETCH` is the same as `fetch`.
 > WARNING:
 >
 > 1. Relying on external sources adds a point of failure. If the external source doesn't work, your script won't either. Please make sure you are aware of the consequences.
-> 2. Make sure DnsControl only uses verified configuration if you want to use `FETCH`. For example, an attacker can send Pull Requests to your config repo, and have your CI test malicious configurations and make arbitrary HTTP requests. Therefore, `FETCH` must be explicitly enabled with flag `--allow-fetch` on DnsControl invocation.
+> 2. Make sure DNSControl only uses verified configuration if you want to use `FETCH`. For example, an attacker can send Pull Requests to your config repo, and have your CI test malicious configurations and make arbitrary HTTP requests. Therefore, `FETCH` must be explicitly enabled with flag `--allow-fetch` on DNSControl invocation.
 
 {% capture example %}
 ```js

docs/_functions/global/NewDnsProvider.md

@@ -12,7 +12,7 @@ A DSP stores a DNS zone's records and provides DNS service for the zone (i.e.
 answers on port 53 to queries related to the zone).
 
 * `name` must match the name of an entry in `creds.json`.
-* `type` specifies a valid DNS provider type identifier listed on the [provider page.]({{site.github.url}}/provider-list).
+* `type` specifies a valid DNS provider type identifier listed on the [provider page]({{site.github.url}}/provider-list).
   * Starting with v3.16, the type is optional. If it is absent, the `TYPE` field in `creds.json` is used instead. You can leave it out. (Thanks to JavaScript magic, you can leave it out even when there are more fields).
   * Starting with v4.0, specifying the type may be an error. Please add the `TYPE` field to `creds.json` and remove this parameter from `dnsconfig.js` to prepare.
 * `meta` is a way to send additional parameters to the provider.  It is optional and only certain providers use it.  See the [individual provider docs]({{site.github.url}}/provider-list) for details.

docs/_functions/global/NewRegistrar.md

@@ -12,7 +12,7 @@ A registrar maintains the domain's registration and delegation (i.e. the
 nameservers for the domain).  DNSControl only manages the delegation.
 
 * `name` must match the name of an entry in `creds.json`.
-* `type` specifies a valid DNS provider type identifier listed on the [provider page.]({{site.github.url}}/provider-list).
+* `type` specifies a valid DNS provider type identifier listed on the [provider page]({{site.github.url}}/provider-list).
   * Starting with v3.16, the type is optional. If it is absent, the `TYPE` field in `creds.json` is used instead. You can leave it out. (Thanks to JavaScript magic, you can leave it out even when there are more fields).
   * Starting with v4.0, specifying the type may be an error. Please add the `TYPE` field to `creds.json` and remove this parameter from `dnsconfig.js` to prepare.
 * `meta` is a way to send additional parameters to the provider.  It is optional and only certain providers use it.  See the [individual provider docs]({{site.github.url}}/provider-list) for details.

docs/_functions/global/PANIC.md

@@ -4,7 +4,7 @@ parameters:
   - message
 ---
 
-`PANIC` terminates the script and therefore DnsControl with an exit code of 1. This should be used if your script cannot gather enough information to generate records, for example when a HTTP request failed.
+`PANIC` terminates the script and therefore DNSControl with an exit code of 1. This should be used if your script cannot gather enough information to generate records, for example when a HTTP request failed.
 
 {% capture example %}
 ```js

docs/_functions/global/require.md

@@ -55,7 +55,7 @@ function includeK8Sdev() {
 
 {% include example.html content=example %}
 
-You can also use it to require json files and initialize variables with it:
+You can also use it to require JSON files and initialize variables with it:
 For Example:
 
 {% capture example %}

docs/_functions/global/require_glob.md

@@ -27,13 +27,13 @@ require_glob("./domains/", false);
 One more important thing to note: `require_glob()` is as smart as `require()` is. It loads files always relative to the JavaScript
 file where it's being executed in. Let's go with an example, as it describes it better:
 
-dnscontrol.js:
+`dnscontrol.js`:
 
 ```js
 require("domains/index.js");
 ```
 
-domains/index.js:
+`domains/index.js`:
 
 ```js
 require_glob("./user1/");

docs/_functions/record/R53_ZONE.md

@@ -8,8 +8,4 @@ R53_ZONE lets you specify the AWS Zone ID for an entire domain (D()) or a specif
 
 When used with D(), it sets the zone id of the domain. This can be used to differentiate between split horizon domains in public and private zones.
 
-When used with R53_ALIAS() it sets the required Route53 hosted zone id in a R53_ALIAS record. See [https://stackexchange.github.io/dnscontrol/js#R53_ALIAS](R53_ALIAS's documentation) for details.
-
-
-
-
+When used with R53_ALIAS() it sets the required Route53 hosted zone id in a R53_ALIAS record. See [R53_ALIAS's documentation](https://stackexchange.github.io/dnscontrol/js#R53_ALIAS) for details.

docs/_providers/autodns.md

@@ -14,7 +14,7 @@ To use this provider, add an entry to `creds.json` with `TYPE` set to `AUTODNS`
 
 Example:
 
-{% highlight json %}
+```json
 {
   "autodns": {
     "TYPE": "AUTODNS",
@@ -23,17 +23,17 @@ Example:
     "context": "33004"
   }
 }
-{% endhighlight %}
+```
 
 ## Usage
 
 An example `dnsconfig.js` configuration:
 
-{% highlight js %}
+```js
 var REG_NONE = NewRegistrar("none");
 var DSP_AUTODNS = NewDnsProvider("autodns");
 
 D("example.tld", REG_NONE, DnsProvider(DSP_AUTODNS),
     A("test", "1.2.3.4")
 );
-{%endhighlight%}
+```

docs/_providers/gcloud.md

@@ -39,7 +39,7 @@ Example:
 
 **Note:** Don't confuse the `TYPE` and `type` fields.  `TYPE` is set to `GCLOUD` and specifies which provider type to use.  `type` specifies the type of account in use.
 
-**Note**: The `project_id`, `private_key`, and `client_email`, are the only fields that are strictly required, but it is sometimes easier to just paste the entire json object in. Either way is fine.  `name_server_set` is optional and requires special permission from your TAM at Google in order to setup (See [Name server sets](#name_server_sets) below)
+**Note**: The `project_id`, `private_key`, and `client_email`, are the only fields that are strictly required, but it is sometimes easier to just paste the entire JSON object in. Either way is fine.  `name_server_set` is optional and requires special permission from your TAM at Google in order to setup (See [Name server sets](#name_server_sets) below)
 
 See [the Activation section](#activation) for some tips on obtaining these credentials.
 

docs/adding-new-rtypes.md

@@ -102,7 +102,7 @@ The dnscontrol `-dev` flag ignores `pkg/js/static.go` and reads
 `pkg/js/helpers.js` directly. This is useful when debugging since it
 is one less step.
 
-Likewise, if you are debugging helpers.js and you can't figure out why
+Likewise, if you are debugging `helpers.js` and you can't figure out why
 your changes aren't making a difference, it usually means you aren't
 running `go generate` after any change, or using the `-dev` flag.
 

docs/code-tricks.md

@@ -82,7 +82,7 @@ _.each(
 
 # Caveats about getting too fancy.
 
-The dnsconfig.js language is JavaScript. On the plus side, this means
+The `dnsconfig.js` language is JavaScript. On the plus side, this means
 you can use loops and variables and anything else you want.
 
 However, we don't recommend you get too fancy.

docs/creds-json.md

@@ -35,7 +35,7 @@ Here's a sample file:
 ## Format
 
 * Primary keys: (e.g. `cloudflare_tal`, `inside`, `hexonet`)
-  * ...refer to the first parameter in the `NewRegistrar()` or `NewDnsProvider()` functions in a dnsconfig.js file.
+  * ...refer to the first parameter in the `NewRegistrar()` or `NewDnsProvider()` functions in a `dnsconfig.js` file.
   * ...may include any printable character except colon (`:`)
   * Convention: all lower case, usually the name of the provider or the username at the provider or both.
 * Subkeys: (e.g. `apikey`, `apiuser` and etc.)

docs/get-certs.md

@@ -55,7 +55,7 @@ time.
 This file should be provided to specify which names you would like to get certificates for. You can
 specify any number of certificates, with up to 100 SAN entries each. Subject names can contain wildcards if you wish.
 
-The format of the file is a simple json array of objects:
+The format of the file is a simple JSON array of objects:
 
 ```json
 [
@@ -128,7 +128,7 @@ The working directory should generally contain:
 - `--acme {url}`: URL of the acme server you wish to use. For *Let's Encrypt* you can use the presets `live` or `staging` for the standard services. If you are using a custom boulder instance or other acme server, you may specify the full **directory** url. Must be an acme **v2** server.
 - `--renew {n}`: `get-certs` will renew certs with less than this many **days** remaining. The default is 15, and certs will be renewed when they are within 15 days of expiration.
 - `--dir {d}`: Root directory holding all certificate and account data as described above. Default is current working directory.
-- `--certConfig {j}`: Location of certificate config json file as described above. Default is `./certs.json`
+- `--certConfig {j}`: Location of certificate config JSON file as described above. Default is `./certs.json`
 - `--vault` Store certificates as secrets in hashicorp vault instead of on disk. (default: false)
 - `--vaultPath {value}` Path in vault to store certificates (default: "/secret/certs")
 - `--skip {p}`: DNS Provider names (comma separated) to skip using as challenge providers. We use this to avoid unnecessary changes to our backup or internal dns providers that wouldn't be a part of the validation flow.

docs/notifications.md

@@ -11,7 +11,7 @@ new types or destinations.
 
 ## Configuration
 
-Notifications are set up in your credentials json file. They will use the `notifications` key to look for keys or configuration needed for various notification types.
+Notifications are set up in your credentials JSON file. They will use the `notifications` key to look for keys or configuration needed for various notification types.
 
 ```json
   "r53": {

docs/opinions.md

@@ -48,7 +48,7 @@ knowledge.  That's your job.
 Your coworkers should not have to know what happens in ambiguous
 situations.  That's your job.
 
-Your coworkers should be able to submit PRs to dnsconfig.js for you
+Your coworkers should be able to submit PRs to `dnsconfig.js` for you
 to approve; preferably via a CI system that does rudimentary checks
 before you even have to see the PR.
 
@@ -63,7 +63,7 @@ A zonefile can list any kind of DNS record. It has no judgement and
 no morals. It will let you do bad practices as long as the bits are
 RFC-compliant.
 
-dnsconfig.js is a high-level description of your DNS zone data.
+`dnsconfig.js` is a high-level description of your DNS zone data.
 Being high-level permits the code to understand intent, and stop
 bad behavior.
 
@@ -74,7 +74,7 @@ TODO: List an example.
 
 DNSControl downcases all DNS names (domains, labels, and targets).  #sorrynotsorry
 
-When the system reads dnsconfig.js or receives data from DNS providers,
+When the system reads `dnsconfig.js` or receives data from DNS providers,
 the DNS names are downcased.
 
 This reduces code complexity, reduces the number of edge-cases that must
@@ -85,7 +85,7 @@ Yes, we know that DNS is case insensitive.  See Opinion #3.
 
 # Opinion #5: Users should state what they want, and DNSControl should do the rest.
 
-When possible, dnsconfig.js lists a high-level description of what
+When possible, `dnsconfig.js` lists a high-level description of what
 is desired and the compiler does the hard work for you.
 
 Some examples:

docs/v316.md

@@ -23,14 +23,14 @@ in [Request for Comments: Include the provider type in creds.json, remove it fro
 In a nutshell, `NewRegistrar()` and `NewDnsProvider()` will lose the 2nd
 parameter:
 
-OLD dnsconfig.js:
+OLD `dnsconfig.js`:
 
 ```js
 var REG_GANDI = NewRegistrar("gandi", "GANDI_V5");
 var DSP_CF = NewDnsProvider("cloudflare_tal", "CLOUDFLAREAPI");
 ```
 
-NEW dnsconfig.js:
+NEW `dnsconfig.js`:
 
 ```js
 var REG_GANDI = NewRegistrar("gandi");
@@ -41,7 +41,7 @@ The second paramter (`GANDI_V5` and `CLOUDFLAREAPI` in the
 above examples) has moved to `creds.json` instead.  It will be in a `TYPE`
 field, which all providers have.  It can appear in both places for backwards compatibility for now.
 
-NEW creds.json:
+NEW `creds.json`:
 
 ```json
 {

docs/writing-providers.md

@@ -36,7 +36,7 @@ Pretty cool, eh?
 
 So how does `GetDomainCorrections()` work?
 
-First, some terminology: The DNS records specified in the dnsconfig.js
+First, some terminology: The DNS records specified in the `dnsconfig.js`
 file are called the "desired" records. The DNS records stored at
 the DNS service provider are called the "existing" records.