Fix markdownlint in site (#1499)

Problem: The configuration for the `site` directory didn't have a
standard name and wasn't getting picked up by markdownlint-cli. The
Makefile was also referencing .markdownlint.yaml that doesn't exist.

Also the configuration for .pre-commit-config.yaml was invalid and the
autoupdate wasn't working correctly.

Solution: Change the name of the configuration to a standard one that
can be used automatically be the tool.
Update pre-commit config and Makefile and run the linter to fix the
existing problems.

Author: lucacome

.pre-commit-config.yaml

@@ -43,9 +43,9 @@ repos:
   # Rules are in .markdownlint-cli2.yaml file
   # See https://github.com./DavidAnson/markdownlint/blob/main/doc/Rules.md for rule descriptions
   - repo: https://github.com./DavidAnson/markdownlint-cli2
-    rev: v0.11.0
+    rev: v0.12.1
     hooks:
-      - id: markdownlint-cli2-fix
+      - id: markdownlint-cli2
 
   # Rules are in .yamllint.yaml file
   # See https://yamllint.readthedocs.io/en/stable/rules.html# for rule descriptions
@@ -55,5 +55,5 @@ repos:
       - id: yamllint
 
 ci:
-  skip: [golangci-lint-full, prettier, markdownlint-cli2-fix, yamllint]
+  skip: [golangci-lint-full, prettier, markdownlint-cli2, yamllint]
   autofix_prs: false

site/mdlint_conf.json renamed to site/.markdownlint.json

@@ -16,5 +16,7 @@
   },
   "MD046": false,
   "MD001": false,
-  "MD049": false
+  "MD049": false,
+  "MD055": false,
+  "MD056": false
 }

site/Makefile

@@ -69,7 +69,7 @@ link-check:
 	${MARKDOWNLINKCHECK} $(shell find content -name '*.md')
 
 lint-markdown:
-	${MARKDOWNLINT} -c .markdownlint.yaml  -- content
+	${MARKDOWNLINT} -c .markdownlint.json  -- content
 
 # Commands used by Netlify CI
 hugo-mod:

site/README.md

@@ -21,7 +21,7 @@ If you have [Docker](https://www.docker.com/get-started/) installed, there are f
 The configuration files are as follows:
 
 - *Hugo*: `config/default/config.toml`
-- *markdownlint-cli*: `mdlint_conf.json`
+- *markdownlint-cli*: `.markdownlint.json`
 - *markdown-link-check* `md-linkcheck-config.json`
 
 ## Repository guidelines

site/content/how-to/traffic-management/integrating-cert-manager.md

@@ -33,8 +33,8 @@ At a high level, the process looks like this:
 1. We create a gateway resource for our domain (cafe.example.com) and configure cert-manager integration using an annotation.
 1. This starts the certificate issuance process – cert-manager contacts Let’s Encrypt to obtain a certificate, and Let’s Encrypt starts the ACME challenge. As part of this challenge, cert-manager creates a temporary HTTPRoute resource which directs the traffic through NGINX Gateway Fabric to verify we control the domain name in the certificate request.
 1. Once the domain has been verified, the certificate is issued. Cert-manager stores the keypair in a Kubernetes secret that is referenced by the gateway resource. As a result, NGINX is configured to terminate HTTPS traffic from clients using this signed keypair.
-1. We deploy our application and our HTTPRoute which defines our routing rules. The routing rules defined configure NGINX to direct requests to https://cafe.example.com/coffee to our coffee-app application, and to use the HTTPS listener defined in our gateway resource.
-1. When the client connects to https://cafe.example.com/coffee, the request is routed to the coffee-app application and the communication is secured using the signed keypair contained in the cafe-secret secret.
+1. We deploy our application and our HTTPRoute which defines our routing rules. The routing rules defined configure NGINX to direct requests to `https://cafe.example.com/coffee` to our coffee-app application, and to use the HTTPS listener defined in our gateway resource.
+1. When the client connects to `https://cafe.example.com/coffee`, the request is routed to the coffee-app application and the communication is secured using the signed keypair contained in the cafe-secret secret.
 1. The certificate will be automatically renewed when it is close to expiry, the secret will be updated using the new certificate, and NGINX Gateway Fabric will dynamically update the keypair on the filesystem used by NGINX for HTTPS termination once the secret is updated.
 
 ## Securing Traffic
@@ -205,7 +205,7 @@ spec:
 
 ## Testing
 
-To test everything has worked correctly, we can use curl to the navigate to our endpoint, for example, https://cafe.example.com/coffee. To verify using curl, we can use the `-v` option to increase verbosity and inspect the presented certificate.
+To test everything has worked correctly, we can use curl to the navigate to our endpoint, for example, `https://cafe.example.com/coffee`. To verify using curl, we can use the `-v` option to increase verbosity and inspect the presented certificate.
 
 ```shell
 curl https://cafe.example.com/coffee -v

site/content/reference/technical-specifications.md

@@ -10,4 +10,4 @@ docs: "DOCS-000"
 
 See the NGINX Gateway Fabric technical specifications page:
 
-https://github.com./nginxinc/nginx-gateway-fabric#technical-specifications
+<https://github.com./nginxinc/nginx-gateway-fabric#technical-specifications>

site/content/releases.md

@@ -10,4 +10,4 @@ docs: "DOCS-1359"
 
 See the NGINX Gateway Fabric changelog page:
 
-https://github.com./nginxinc/nginx-gateway-fabric/blob/main/CHANGELOG.md
+<https://github.com./nginxinc/nginx-gateway-fabric/blob/main/CHANGELOG.md>