feat: Updating linting tools and documentation (nginx#1349)

This commit updates the Markdown linting configuration files, and adds
an explanation of the linting available in the repository to the process
documentation. The linter itself has been used on multiple files also
affected in this commit

There are a handful of peripheral changes made in the PR:

- Adding the latest catalogue tags to the Hugo archetype metadata
- Fixing a broken link for NGINX Amplify
- Fixing duplicate tabs caused by includes (Closes nginx#1343)
- Adding reload instructions to NGINX configuration (Closes nginx#1346)

Author: ADubhlaoich

.gitlint

@@ -3,7 +3,7 @@ ignore = body-is-missing
 contrib = contrib-title-conventional-commits
 
 [title-max-length] 
-line-length = 50
+line-length = 60
 
 [title-min-length]
 min-length = 5

.markdownlint.yaml

@@ -1,42 +1,40 @@
-default: true
+# markdownlint enables all rules by default
+# Setting default to false means that rules are
+# instead enabled on a case-by-case basis
+default: false
 
-MD002: false
+# Heading levels should only increment by one level at a time
+MD001: true
 
-MD003: false
+# Detects if link brackets are in the wrong order: ()[]
+MD011: true
 
-MD004:
-  style: dash
+# No multiple consecutive blank lines
+MD012: true
 
-MD009: false
+# Headings should be surrounded by blank lines
+MD022: true
 
-MD010: false
+# Headings must start at the beginning of a line
+MD023: true
 
-MD012: false
+# No trailing punctuation in headings
+MD026: true
 
-MD013:
-  line_length: 5000
-  heading_line_length: 60
-  code_block_line_length: 80
-  code_blocks: true
-  tables: false
-  headings: true
-  headers: true
-  strict: false
-  stern: false
+# Code blocks should be surrounded by blank lines
+MD031: true
 
-MD022: false
+# Lists should be surrounded by blank lines
+MD032: true
 
-MD024:
-  siblings_only: true
+# Emphasis should not be used instead of headings
+MD036: true
 
-MD029: false
+# No spaces on the outside of link text
+MD039: true
 
-MD033: false
+# All images should have alt text
+MD045: true
 
-MD034: false
-
-MD041: false
-
-MD046: false
-
-MD051: false
+# Tables shou ld be surrounded by blank lines
+MD058: true

.pre-commit-config.yaml

@@ -4,9 +4,13 @@ default_install_hook_types:
 
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0 
+    rev: v6.0.0 
     hooks:
     -   id: no-commit-to-branch
+-   repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.18.1
+    hooks:
+    - id: markdownlint-cli2
 -   repo: https://github.com/jorisroovers/gitlint
     rev:  v0.19.1
     hooks:

archetypes/concept.md

@@ -8,7 +8,7 @@ toc: false
 # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this
 nd-content-type: concept
 # Intended for internal catalogue and search, case sensitive:
-# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit
+# AGE, DOS, NAZ, NGC, NGF, NIC, NIM, NGF, ONE, NOS, NPL, SOL, WAF
 nd-product:
 ---
 
@@ -42,7 +42,7 @@ It is an example of a <other concept>, and is closely related to <third concept>
 # Read their documentation for usage: https://mermaid.js.org/intro/
 ```
 
-Starting from the <top/left> of the diagram, you can see that <thing> is connected to <other thing>: this relationship is established when configuring <parameter> as part of <file name>.
+Starting from the \<top/left\> of the diagram, you can see that \<thing\> is connected to \<other thing\>: this relationship is established when configuring \<parameter\> as part of \<file name\>.
 
 [//]: # "End a particular use case section with links to other pages, such as instructional documentation, other concepts, or reference information (Such as API specifications)."
 
@@ -52,7 +52,6 @@ Starting from the <top/left> of the diagram, you can see that <thing> is connect
 
 ### Use case 2
 
-
 ## Conclusion
 
 [//]: # "Summarize everything that the reader will have learned by reading this entire concept document."

archetypes/default.md

@@ -8,7 +8,7 @@ toc: false
 # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this
 nd-content-type: how-to
 # Intended for internal catalogue and search, case sensitive:
-# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit
+# AGE, DOS, NAZ, NGC, NGF, NIC, NIM, NGF, ONE, NOS, NPL, SOL, WAF
 nd-product:
 ---
 
@@ -39,6 +39,7 @@ To complete this guide, you will need the following prerequisites:
 ```shell
 # We typically show examples of commands or code in one code block, which can be easily copied by a reader using a button connected to the block.
 ```
+
 ```text
 # A second code block is used underneath the first to show what kind of example output to expect from the command. Truncate unnecessary output with ellipses (...).
 ```
@@ -57,17 +58,14 @@ To complete this guide, you will need the following prerequisites:
 
 ### Sub-step 1
 
-
 ### Sub-step 2
 
-
 ## Step 3
 
 [//]: # "The final step of a how-to guide is usually a final test, and summarizes all of the previous steps taken to accomplish the purpose of the guide."
 
 ### Sub-step 1
 
-
 ### Sub-step 2
 
 ## Next steps

archetypes/landing-page.md

@@ -14,11 +14,12 @@ nd-landing-page: true
 # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this
 nd-content-type: landing-page
 # Intended for internal catalogue and search, case sensitive:
-# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit
+# AGE, DOS, NAZ, NGC, NGF, NIC, NIM, NGF, ONE, NOS, NPL, SOL, WAF
 nd-product:
 ---
 
 ## About
+
 [//]: # "These are Markdown comments to guide you through document structure. Remove them as you go, as well as any unnecessary sections."
 [//]: # "Use underscores for _italics_, and double asterisks for **bold**."
 [//]: # "Backticks are for `monospace`, used sparingly and reserved mostly for executable names - they can cause formatting problems. Avoid them in tables: use italics instead."
@@ -27,6 +28,7 @@ nd-product:
 [//]: # "Name specific functionality it provides: avoid ambiguous descriptions such as 'enables efficiency', focus on what makes it unique."
 
 ## Featured content
+
 [//]: # "You can add a maximum of three cards: any extra will not display."
 [//]: # "One card will take full width page: two will take half width each. Three will stack like an inverse pyramid."
 [//]: # "Some examples of content could be the latest release note, the most common install path, and a popular new feature."

archetypes/tutorial.md

@@ -8,7 +8,7 @@ toc: false
 # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this
 nd-content-type: tutorial
 # Intended for internal catalogue and search, case sensitive:
-# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit
+# AGE, DOS, NAZ, NGC, NGF, NIC, NIM, NGF, ONE, NOS, NPL, SOL, WAF
 nd-product:
 ---
 
@@ -18,16 +18,16 @@ nd-product:
 
 [//]: # "Begin each document with a sentence or two explaining what the purpose of the guide is, and what high-level actions to expect. No need to adhere precisely the example text given anywhere in this template."
 
-This guide is a tutorial on how to set up <thing>. While going through the steps of this tutorial, <concept 1>, <concept 2> and <concept 3> will be introduced and explained to understand how <thing> works.
+This guide is a tutorial on how to set up \<thing\>. While going through the steps of this tutorial, \<concept 1\>, \<concept 2\> and \<concept 3\> will be introduced and explained to understand how \<thing\> works.
 
-By the end of the tutorial, you should have enough working knowledge of <thing> to develop your own <configuration/application/etc>.
+By the end of the tutorial, you should have enough working knowledge of \<thing\> to develop your own \<configuration/application/etc\>.
 
 ## Background
 
 [//]: # "The largest difference between a tutorial and a how-to document is the scope of detail included. While working on the tutorial, consider what overlap might exist with a concept document."
 [//]: # "We want to reduce the amount of context switching a reader has to go through, so it might be beneficial to convert some text content into an include for re-use between a tutorial and a concept document."
 
-<thing> is a common use for <product>: it enables the ability to use <feature 1>, <feature 2> and <feature 3>, which are important when configuring <product> for <use case>.
+\<thing\> is a common use for \<product\>: it enables the ability to use \<feature 1\>, \<feature 2\> and \<feature 3\>, which are important when configuring \<product\> for \<use case\>.
 
 ## Before you begin
 
@@ -46,7 +46,7 @@ To complete this guide, you will need the following prerequisites:
 [//]: # "The text immediately following a heading in a tutorial should likely explain a concept to build a mental model of what the reader is about to do."
 [//]: # "If it's a successive step (One after the first), you might refer to work already done to follow the sequence of operations."
 
-The first thing required for setting up <thing> is <step name>. This is the <service/host/etcetera> that the <thing> will run on. The <component> that is set-up from this step is necessary for <requirement>, and will be connected to <other component> and <third component> in a later step. The <thing> we are configuring will look something along the lines of this by the end:
+The first thing required for setting up \<thing\> is \<step name\>. This is the \<service/host/etcetera\> that the \<thing\> will run on. The \<component\> that is set-up from this step is necessary for \<requirement\>, and will be connected to \<other component\> and \<third component\> in a later step. The \<thing\> we are configuring will look something along the lines of this by the end:
 
 [//]: # "If it helps, include a diagram of some kind. Ensure your description provides all the context required, however: a diagram is an aid to explain things, not a replacement."
 
@@ -55,28 +55,30 @@ The first thing required for setting up <thing> is <step name>. This is the <ser
 # Read their documentation for usage: https://mermaid.js.org/intro/
 ```
 
-Starting from the <top/left> of the diagram, you can see that <thing> is connected to <other thing>: this relationship is established when configuring <parameter> as part of <file name>.
+Starting from the \<top/left\> of the diagram, you can see that \<thing\> is connected to \<other thing\>: this relationship is established when configuring \<parameter\> as part of \<file name\>.
 
 ### Sub-step 1
 
 [//]: # "The sub-steps of a tutorial should show the exact steps a reader should take to accomplish an action, and what to expect when doing so."
 [//]: # "Though there may be multiple ways to accomplish a task, focus on showing the reader the exact way to do one."
 [//]: # "You can mention alternative paths, but do not give unnecessary detail: it detracts from the task at hand."
 
-To set up <component>, start by running the following command. It will create <dependency 1>: take note of the <unique identifier> value, as it will be used for connecting <other component> in later steps.
+To set up \<component\>, start by running the following command. It will create \<dependency 1\>: take note of the \<unique identifier\> value, as it will be used for connecting \<other component\> in later steps.
 
 ```shell
 # We typically show examples of commands or code in one code block, which can be easily copied by a reader using a button connected to the block.
 ```
+
 ```text
 # A second code block is used underneath the first to show what kind of example output to expect from the command. Truncate unnecessary output with ellipses (...).
 ```
 
-To verify the creation of <component>, you can also inspect information about it using <command>. The output should look something like this:
+To verify the creation of \<component\>, you can also inspect information about it using \<command\>. The output should look something like this:
 
 ```shell
 <a copyable, single line command>
 ```
+
 ```
 <the output of that command, possibly truncated and with changed IPs or domains>
 ```
@@ -89,17 +91,14 @@ To verify the creation of <component>, you can also inspect information about it
 
 ### Sub-step 1
 
-
 ### Sub-step 2
 
-
 ## Conclusion
 
 [//]: # "Summarize everything that the reader will have learned and accomplished by the end of this tutorial."
 [//]: # "It should fulfill the promise made by the introductory paragraph at the top of the document."
 [//]: # "You may wish to link to another tutorial as the next logical step, but that could also be part of the 'See also' section."
 
-
 ## Next steps
 
 [//]: # "Link to related documents, such as concepts, reference material or specific use cases."

content/amplify/overview/overview-main-components.md

@@ -8,7 +8,7 @@ nd-docs: DOCS-976
 
 ## What Is F5 NGINX Amplify?
 
-[NGINX Amplify](https://amplify.nginx.com/signup/) offers in-depth monitoring for NGINX-based web applications. It simplifies the process of analyzing and resolving issues related to performance and scalability.
+[NGINX Amplify](https://amplify.nginx.com/) offers in-depth monitoring for NGINX-based web applications. It simplifies the process of analyzing and resolving issues related to performance and scalability.
 
 With NGINX Amplify, you can:
 

content/includes/waf/install-update-configuration.md

@@ -117,4 +117,9 @@ server {
 
 {{% /tab %}}
 
-{{< /tabs >}}
+{{< /tabs >}}
+
+Once you have updated your configuration files, you can reload NGINX to apply the changes. You have two options depending on your environment:
+
+- `nginx -s reload`
+- `sudo systemctl reload nginx`