DOCS: Documentation improvements (#1786)

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

docs/_functions/domain/SSHFP.md

@@ -11,6 +11,7 @@ parameters:
 SSHFP contains a fingerprint of a SSH server which can be validated before SSH clients are establishing the connection.
 
 **Algorithm** (type of the key)
+
 | ID | Algorithm |
 |----|-----------|
 | 0  | reserved  |
@@ -20,6 +21,7 @@ SSHFP contains a fingerprint of a SSH server which can be validated before SSH c
 | 4  | ED25519   |
 
 **Type** (fingerprint format)
+
 | ID | Algorithm |
 |----|-----------|
 | 0  | reserved  |

docs/_functions/domain/TXT.md

@@ -43,7 +43,7 @@ split into 255-octets chunks or the provider may report an error
 if it does not handle multiple strings.
 
 
-### TXT record edge cases.
+### TXT record edge cases
 
 Most providers do not support the full possibilities of what a TXT
 record can store.  DNSControl can not handle all the edge cases

docs/_functions/global/D_EXTEND.md

@@ -29,8 +29,6 @@ Some operators only act on an apex domain (e.g.
 `CF_REDIRECT` and `CF_TEMP_REDIRECT`). Using them
 in a `D_EXTEND` subdomain may not be what you expect.
 
-Example:
-
 {% capture example %}
 ```js
 D("domain.tld", REG, DnsProvider(DNS),

docs/_functions/global/NewDnsProvider.md

@@ -7,7 +7,7 @@ parameters:
 return: string
 ---
 
-NewDnsProvider activates a DNS Service Provider (DSP) specified in creds.json.
+NewDnsProvider activates a DNS Service Provider (DSP) specified in `creds.json`.
 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).
 

docs/_functions/global/require.md

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

docs/_functions/record/CAA_BUILDER.md

@@ -46,4 +46,3 @@ The parameters are:
   * `CAA("@", "issue", "letsencrypt.org")`
   * `CAA("@", "issue", "comodoca.com")`
   * `CAA("@", "issuewild", ";")`
-```

docs/_providers/dnsimple.md

@@ -52,12 +52,12 @@ DNSControl depends on a DNSimple account access token.
 
 As of July 2022, the DNSimple DNS does not accept spaces in CAA records. Putting spaces in the record will result in a 400 Validation Failed error.
 
-```
+```text
 0 issue "letsencrypt.org; validationmethods=dns-01; accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/1234"
 ```
 
 Removing the spaces will work.
-```
+```text
 0 issue "letsencrypt.org;validationmethods=dns-01;accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/1234"
 ```
 

docs/_providers/gandi_v5.md

@@ -30,7 +30,7 @@ the URL on the portal. Log into the Gandi website, click on "organizations" in
 the leftnav, and click on the organization name.  The URL will be something
 like:
 
-```
+```text
 https://admin.gandi.net/organizations/[not this hex string]/PLTS/[sharing id]/profile
 ```
 
@@ -88,7 +88,7 @@ This is the error you'll see if your `apikey` in `creds.json` is wrong or invali
 
 #### Domain does not exist in profile
 
-```
+```text
 WARNING: Domain 'example.com' does not exist in the 'secname' profile and will be added automatically.
 ```
 

docs/_providers/gcloud.md

@@ -44,7 +44,7 @@ Example:
 See [the Activation section](#activation) for some tips on obtaining these credentials.
 
 ### Using Application Default Credentials
-If you prefer to authenticate using ADC you only need to specify `project_id` in your creds.json file.
+If you prefer to authenticate using ADC you only need to specify `project_id` in your `creds.json` file.
 
 Example:
 

docs/_providers/hetzner.md

@@ -52,12 +52,12 @@ Create a new API Key in the
 
 As of June 2022, the Hetzner DNS Console API does not accept spaces in CAA
  records.
-```
+```text
 0 issue "letsencrypt.org; validationmethods=dns-01; accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/1234"
 ```
 
 Removing the spaces might still work for any consumer of the record.
-```
+```text
 0 issue "letsencrypt.org;validationmethods=dns-01;accounturi=https://acme-v02.api.letsencrypt.org/acme/acct/1234"
 ```
 

docs/_providers/namedotcom.md

@@ -82,7 +82,7 @@ In integration tests:
  * Wrong: `export NAMEDOTCOM_URL='api.name.com/api'`
  * Right: `export NAMEDOTCOM_URL='api.name.com'`
 
-In production, the `apiurl` setting in creds.json is wrong. You can
+In production, the `apiurl` setting in `creds.json` is wrong. You can
 simply leave this option out and use the default, which is correct.
 
 TODO(tlim): Improve the error message. (Volunteer needed!)
@@ -98,7 +98,7 @@ When running integration tests, this error
 means you included the `https://` in the `NAMEDOTCOM_URL` variable.
 You meant to do something like `export NAMEDOTCOM_URL='api.name.com' instead.
 
-In production, the `apiurl` setting in creds.json needs to be
+In production, the `apiurl` setting in `creds.json` needs to be
 adjusted. You can simply leave this option out and use the default,
 which is correct. If you are using the EO&T system, leave the
 protocol (`http://`) off the URL.

docs/_providers/route53.md

@@ -48,7 +48,7 @@ Alternatively, this provider supports [named profiles](https://docs.aws.amazon.c
 export AWS_PROFILE=ZZZZZZZZ
 ```
 
-and provide a minimal entry in creds.json:
+and provide a minimal entry in `creds.json`:
 
 Example:
 
@@ -192,7 +192,7 @@ Creating r53 dns provider: NoCredentialProviders: no valid providers in chain. D
     For verbose messaging see aws.Config.CredentialsChainVerboseErrors
 ```
 
-This means that the creds.json entry isn't found. Either there is no entry, or the entry name doesn't match the first parameter in the `NewDnsProvider()` call. In the above example, note
+This means that the `creds.json` entry isn't found. Either there is no entry, or the entry name doesn't match the first parameter in the `NewDnsProvider()` call. In the above example, note
 that the string `r53_main` is specified in `NewDnsProvider("r53_main")` and that is the exact key used in the creds file above.
 
 ### Invalid KeyId

docs/adding-new-rtypes.md

@@ -112,7 +112,7 @@ Anywhere a rtype requires special handling has been marked with a
 comment that includes the string `#rtype_variations`.  Search for
 this string and add your new type to this code.
 
-## Step 5: Add a `parse_tests` test case.
+## Step 5: Add a `parse_tests` test case
 
 Add at least one test case to the `pkg/js/parse_tests` directory.
 Test `013-mx.js` is a very simple one and is good for cloning.
@@ -133,7 +133,7 @@ The tests also verify that for every "capability" there is a
 validation. This is explained in Step 2 (search for
 `TestCapabilitiesAreFiltered` or `MISSING`)
 
-## Step 6: Add an `integrationTest` test case.
+## Step 6: Add an `integrationTest` test case
 
 Add at least one test case to the `integrationTest/integration_test.go`
 file. Look for `func makeTests` and add the test to the end of this

docs/ci-cd-gitlab.md

@@ -19,7 +19,7 @@ This is based on:
 For convenience, both configuration files are shown below.
 
 - `dnsconfig.js`
-  ```javascript
+  ```js
   var PROVIDER_NONE = NewRegistrar('none');
   var PROVIDER_TRANSIP = NewDnsProvider('transip', '-');
 

docs/creds-json.md

@@ -117,7 +117,7 @@ Usually this is to simply remove the second parameter to the function.
 Examples:
 
 
-```
+```js
 OLD: var REG_THING = NewRegistrar("thing", "THING");
 NEW: var REG_THING = NewRegistrar("thing");
 

docs/examples.md

@@ -161,7 +161,7 @@ In this example we need a macro that can dynamically change for each domain.
 
 Suppose you have many domains that use Fastmail as an MX. Here's a macro that sets the MX records.
 
-```
+```js
 var FASTMAIL_MX = [
   MX('@', 10, 'in1-smtp.messagingengine.com.'),
   MX('@', 20, 'in2-smtp.messagingengine.com.'),
@@ -173,7 +173,7 @@ that includes the domain name. We can't use a simple macro. Instead, we use
 a function that takes the domain name as a parameter to generate the right
 records dynamically.
 
-```
+```js
 var FASTMAIL_DKIM = function(the_domain){
   return [
     CNAME('fm1._domainkey', 'fm1.' + the_domain + '.dkim.fmhosted.com.'),
@@ -185,7 +185,7 @@ var FASTMAIL_DKIM = function(the_domain){
 
 We can then use the macros as such:
 
-```
+```js
 D("example.com", REG_NONE, DnsProvider(DSP_R53_MAIN),
     FASTMAIL_MX,
     FASTMAIL_DKIM('example.com')

docs/getting-started.md

@@ -42,7 +42,7 @@ docker run --rm -it -v $(pwd)/dnsconfig.js:/dns/dnsconfig.js -v $(pwd)/creds.jso
 ```
 
 
-## 2. Create a place for the config files.
+## 2. Create a place for the config files
 
 Create a directory where you'll be storing your configuration files.
 We highly recommend storing these files in a Git repo, but for
@@ -99,7 +99,7 @@ For example, to use both name.com and Cloudflare, you would have:
 }
 ```
 
-Note: Do **not** store your creds.json file in Git unencrypted.
+Note: Do **not** store your `creds.json` file in Git unencrypted.
 That is unsafe. Add `creds.json` to your
 `.gitignore` file as a precaution.  This file should be encrypted
 using something
@@ -152,17 +152,25 @@ and other formatting.  There are a few different ways to check for typos:
 
 Python:
 
-    python -m json.tool creds.json
+```bash
+python -m json.tool creds.json
+```
 
 jq:
 
-    jq . < creds.json
+```bash
+jq . < creds.json
+```
 
 FYI: `creds.json` fields can be read from an environment variable. The field must begin with a `$` followed by the variable name. No other text. For example:
 
-    "apikey": "$GANDI_V5_APIKEY",
+```json
+{
+    "apikey": "$GANDI_V5_APIKEY"
+}
+```
 
-## 5. Test the sample files.
+## 5. Test the sample files
 
 Before you edit the sample files, verify that the system is working.
 
@@ -176,8 +184,10 @@ exist.
 
 It should look something like this:
 
-```text
+```bash
 dnscontrol preview
+```
+```text
 Initialized 1 registrars and 1 dns service providers.
 ******************** Domain: example.com
 ----- Getting nameservers from: bind
@@ -195,6 +205,8 @@ previously exist.
 
 ```bash
 dnscontrol push
+```
+```text
 Initialized 1 registrars and 1 dns service providers.
 ******************** Domain: example.com
 ----- Getting nameservers from: bind
@@ -209,7 +221,7 @@ Done. 1 corrections.
 ```
 
 
-## 6. Make a change.
+## 6. Make a change
 
 Try making a change to `dnsconfig.js`. For example, change the IP
 address of in `A('@', '1.2.3.4')` or add an additional A record.
@@ -219,6 +231,8 @@ our change looks like this:
 
 ```bash
 dnscontrol preview
+```
+```text
 Initialized 1 registrars and 1 dns service providers.
 ******************** Domain: example.com
 ----- Getting nameservers from: bind
@@ -293,5 +307,5 @@ If you are going to use this in production, we highly recommend the following:
 * Store the configuration files in Git.
 * Encrypt the `creds.json` file before storing it in Git. Do NOT store
   API keys or other credentials without encrypting them.
-* Use a CI/CD tool like Jenkins/CircleCI/GitHub Actions/etc. to automatically push DNS changes.
-* Join the DNSControl community. File [issues and PRs](https://github.com/StackExchange/dnscontrol).
+* Use a CI/CD tool like [Gitlab]({{site.github.url}}/ci-cd-gitlab), Jenkins, CircleCI, [GitHub Actions](https://github.com/StackExchange/dnscontrol#via-github-actions-gha), etc. to automatically push DNS changes.
+* Join the DNSControl community. File [issues](https://github.com/StackExchange/dnscontrol/issues) and [PRs](https://github.com/StackExchange/dnscontrol/pulls).

docs/migrating.md

@@ -106,21 +106,32 @@ If `dnscontrol get-zones` could have done a better job, please
 Here is an example series of commands that would be used
 to convert a zone. Lines that start with `#` are comments.
 
-    # Note this command uses ">>" to append to dnsconfig.js.  Do
-    # not use ">" as that will erase the existing file.
-    dnscontrol get-zones --format=js --out=draft.js bind BIND foo.com
-    cat >>dnsconfig.js draft.js   # Append to dnsconfig.js
-    #
-    dnscontrol preview
-    vim dnsconfig.js
-    # (repeat these two commands until all warnings/errors are resolved)
-    #
-    # When everything is as you wish, push the changes live:
-    dnscontrol push
-    # (this should be a no-op)
-    #
-    # Make any changes you do desire:
-    vim dnsconfig.js
-    dnscontrol preview
-    # (repeat until all warnings/errors are resolved)
-    dnscontrol push
+
+```bash
+# Note this command uses ">>" to append to dnsconfig.js. Do not use ">" as that will erase the existing file.
+dnscontrol get-zones --format=js --out=draft.js bind BIND foo.com
+cat >>dnsconfig.js draft.js # Append to dnsconfig.js
+dnscontrol preview
+vim dnsconfig.js
+```
+
+Repeat these two commands until all warnings/errors are resolved.
+When everything is as you wish, push the changes live:
+
+```bash
+dnscontrol push
+```
+
+
+Make any changes you do desire:
+
+```bash
+vim dnsconfig.js
+dnscontrol preview
+```
+
+Repeat until all warnings/errors are resolved.
+
+```bash
+dnscontrol push
+```

docs/testing-txt-records.md

@@ -55,7 +55,7 @@ Step 3: Preview
 
 When you do a `dnscontrol preview`, you should see changes for t1 and t2.
 
-```
+```text
 #1: MODIFY TXT t1.example.com: ("test1" ttl=1) -> ("\"test1\"" ttl=1)
 #2: MODIFY TXT t2.example.com: ("\"test2\"" ttl=1) -> ("test2" ttl=1)
 ```
@@ -69,7 +69,7 @@ Step 3: Push
 Let's assume you DO see the changes.  Push them using `dnscontrol push`
 then check the webui to see that the changes are correct.
 
-```
+```text
 2 corrections
 #1: MODIFY TXT t1.stackoverflow.help: ("test1" ttl=1) -> ("\"test1\"" ttl=1)
 SUCCESS!

docs/v316.md

@@ -90,7 +90,7 @@ out entirely starting in v4.0.
 
 For check-creds:
 
-```
+```text
 Starting in v3.16 these forms are valid:
    dnscontrol check-creds myr53
    dnscontrol check-creds myr53 -
@@ -103,7 +103,7 @@ Starting in v4.0 this is the only valid form:
 
 For get-zones/get-zone:
 
-```
+```text
 Starting in v3.16 these forms are valid:
     dnscontrol get-zones gmain GANDI_V5 example.comn other.com
     dnscontrol get-zones gmain - example.comn other.com
@@ -167,7 +167,7 @@ Here are some examples:
 
 If you see something like...
 
-```
+```text
 WARNING: For future compatibility, update the "namedotcom_main" entry in `creds.json` by adding: "TYPE": "NAMEDOTCOM", (See https://stackexchange.github.io/dnscontrol/creds-json#missing)
 ```
 
@@ -176,7 +176,7 @@ WARNING: For future compatibility, update the "namedotcom_main" entry in `creds.
 
 If you see something like...
 
-```
+```text
 ERROR: Mismatch found! creds.json entry "namedotcom_main" has "TYPE" set to "ROUTE53" but dnsconfig.js specifies New*("namedotcom_main", "NAMEDOTCOM") (See https://stackexchange.github.io/dnscontrol/creds-json#mismatch)
 ```
 
@@ -185,7 +185,7 @@ ERROR: Mismatch found! creds.json entry "namedotcom_main" has "TYPE" set to "ROU
 
 After you correct some warnings, you may receive information messages like...
 
-```
+```text
 INFO: In dnsconfig.js New*("namedotcom_main", "NAMEDOTCOM") can be simplified to New*("namedotcom_main") (See https://stackexchange.github.io/dnscontrol/creds-json#cleanup)
 ```
 

docs/writing-providers.md

@@ -163,7 +163,7 @@ Run the unit tests with this command:
 This is the most important kind of testing when adding a new provider.
 Integration tests use a test account and a real domain.
 
-* Edit [integrationTest/providers.json](https://github.com/StackExchange/dnscontrol/blob/master/integrationTest/providers.json): Add the creds.json info required for this provider.
+* Edit [integrationTest/providers.json](https://github.com/StackExchange/dnscontrol/blob/master/integrationTest/providers.json): Add the `creds.json` info required for this provider.
 
 For example, this will run the tests using BIND:
 
@@ -282,7 +282,7 @@ for tips about managing modules and checking for outdated
 dependencies.
 
 
-## Step 14: Check your work.
+## Step 14: Check your work
 
 Here are some last-minute things to check before you submit your PR.
 

integrationTest/readme.md

@@ -8,7 +8,7 @@ For each step, it will run the config once and expect changes. It will run it ag
 
 ## Configuration
 
-`providers.json` should have an object for each provider type under test. This is identical to the json expected in creds.json for dnscontrol, except it also has a "domain" field specified for the domain to test. The domain does not even need to be registered for most providers. Note that `providers.json` expects environment variables to be specified with the relevant info.
+`providers.json` should have an object for each provider type under test. This is identical to the json expected in `creds.json` for dnscontrol, except it also has a "domain" field specified for the domain to test. The domain does not even need to be registered for most providers. Note that `providers.json` expects environment variables to be specified with the relevant info.
 
 ## Running a test
 

providers/octodns/TESTING.md

@@ -1,6 +1,6 @@
 # Testing:
 
-## Create the environment.
+## Create the environment
 
 These variables are used in all other sections of this doc.