Update documentation Makefile and README

site/Makefile

@@ -0,0 +1,65 @@
+HUGO?=hugo
+HUGO_IMG?=hugomods/hugo:0.115.3
+
+THEME_MODULE = github.com/nginxinc/nginx-hugo-theme
+THEME_VERSION = 0.41.14
+
+ifeq (, $(shell ${HUGO} version 2> /dev/null))
+ifeq (, $(shell docker version 2> /dev/null))
+    $(error Docker and Hugo are not installed. Hugo (<0.91) or Docker are required to build the local preview.)
+else
+    HUGO=docker run --rm -it -v ${CURDIR}:/src -p 1313:1313 ${HUGO_IMG} hugo --bind 0.0.0.0 -p 1313
+endif
+endif
+
+MARKDOWNLINT?=markdownlint
+MARKDOWNLINT_IMG?=ghcr.io/igorshubovych/markdownlint-cli:latest
+
+ifeq (, $(shell ${MARKDOWNLINT} version 2> /dev/null))
+ifeq (, $(shell docker version 2> /dev/null))
+    $(error Docker and markdownlint are not installed. markdownlint or Docker are required to lint.)
+endif
+else
+    MARKDOWNLINT=docker run --rm -i -v ${CURDIR}:/src --workdir /src ${MARKDOWNLINT_IMG}
+endif
+endif
+
+MARKDOWNLINKCHECK?=markdown-link-check
+MARKDOWNLINKCHECK_IMG?=ghcr.io/tcort/markdown-link-check:stable
+
+ifeq (, $(shell ${MARKDOWNLINKCHECK} --version 2> /dev/null))
+ifeq (, $(shell docker version 2> /dev/null))
+    $(error Docker and markdown-link-check are not installed. markdown-link-check or Docker are required to check links.)
+endif
+else
+    MARKDOWNLINKCHECK=docker run --rm -it -v ${CURDIR}:/docs --workdir /docs ${MARKDOWNLINKCHECK_IMG}
+endif
+endif
+
+.PHONY: docs docs-draft docs-local clean hugo-get hugo-tidy lint-markdown link-check
+
+docs:
+	${HUGO}
+
+watch:
+	${HUGO} --bind 0.0.0.0 -p 1313 server --disableFastRender
+
+drafts:
+	${HUGO} --bind 0.0.0.0 -p 1313 server -D --disableFastRender
+
+clean:
+	[ -d "public" ] && rm -rf "public" 
+
+hugo-get:
+	hugo mod get $(THEME_MODULE)@v$(THEME_VERSION)
+
+hugo-tidy:
+	hugo mod tidy
+
+hugo-update: hugo-get hugo-tidy
+
+lint-markdown:
+	${MARKDOWNLINT} -c .markdownlint.yaml  -- content
+
+link-check:
+	${MARKDOWNLINKCHECK} $(shell find content -name '*.md')

site/README.md

@@ -1,47 +1,52 @@
-# NGINX Agent Docs
+# NGINX Agent Documentation
 
 This directory contains all of the user documentation for NGINX Agent, as well as the requirements for linting, building, and publishing the documentation.
 
-Docs are written in Markdown. We build the docs using [Hugo](https://gohugo.io). Previews and deployments are handled by the [docs-actions](https://github.com/nginxinc/docs-actions?tab=readme-ov-file#docs-actions) workflow.
+We write our documentation in Markdown. We build it with [Hugo](https://gohugo.io) and our custom [NGINX Hugo theme](https://github.com/nginxinc/nginx-hugo-theme). We set up previews and deployments using our [docs-actions](https://github.com/nginxinc/docs-actions?tab=readme-ov-file#docs-actions) workflow.
 
 ## Setup
 
 1. To install Hugo locally, refer to the [Hugo installation instructions](https://gohugo.io/getting-started/installing/).
 
-    > **NOTE**: We are currently running [Hugo v0.115.3](https://github.com/gohugoio/hugo/releases/tag/v0.115.3) in production.
+    > **Note**: We currently use [Hugo v0.115.3](https://github.com/gohugoio/hugo/releases/tag/v0.115.3) in production.
 
 2. We use markdownlint to check that Markdown files are correct. Use `npm` to install markdownlint-cli:
 
     ```shell
     npm install -g markdownlint-cli   
     ```
 
-## Local Docs Development
+## Develop documentation locally
 
-To build the docs locally, run the desired `make` command from the docs directory:
+To build the docs locally, use the `make` command in the documentation folder with these targets:
 
 ```text
-make clean          -   removes the local `public` directory, which is the default output path used by Hugo
-make docs           -   runs a local hugo server so you can view docs in your browser while you work
-make hugo-mod       -   cleans the Hugo module cache and fetches the latest version of the theme module
-make docs-drafts    -   runs the local hugo server and includes all docs marked with `draft: true`
+make docs           - Builds the documentation
+make watch          - Runs a local Hugo server to automatically preview changes
+make drafts         - Runs a local Hugo server, and displays documentation marked as drafts
+make clean          - Removes the output 'public' directory created by Hugo
+make hugo-get       - Updates the go module file with the latest version of the theme
+make hugo-tidy      - Removes unnecessary dependencies from the go module file
+make hugo-update    - Runs the hugo-get and hugo-tidy targets in sequence
+make lint-markdown  - Runs markdownlint on the content folder
+make link-check     - Runs markdown-link-check on all Markdown files
 ```
 
 ## Linting
 
-- To run the markdownlint check, run the following command from the docs directory:
+- To use markdownlint, use the following command in the documentation directory:
 
     ```bash
     markdownlint -c docs/mdlint_conf.json content
     ```
 
-    Note: You can run this tool on an entire directory or on an individual file.
+    > **Note**: You can run this tool on an entire directory or on an individual file.
 
-## Add new docs
+## Add new documentation
 
-### Generate a new doc file using Hugo
+### Generate a new documentation file using Hugo
 
-To create a new doc file that contains all of the pre-configured Hugo front-matter and the docs task template, **run the following command in the docs directory**:
+To create a new documentation file containing the pre-configured Hugo front-matter with the task template, **run the following command in the documentation directory**:
 
 `hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>`
 
@@ -51,7 +56,7 @@ For example:
 hugo new getting-started/install.md
 ```
 
-The default template -- task -- should be used for most docs. To create docs using the other content templates, you can use the `--kind` flag:
+The default template -- task -- should be used for most documentation. To create documentation using the other content templates, you can use the `--kind` flag:
 
 ```shell
 hugo new tutorials/deploy.md --kind tutorial
@@ -65,52 +70,63 @@ The available content types (`kind`) are:
 - troubleshooting: Helps a customer solve a specific problem.
 - openapi: Contains front-matter and shortcode for rendering an openapi.yaml spec
 
-## How to format docs
+## Documentation formatting
 
-### How to format internal links
+### Basic markdown formatting
 
-Format links as [Hugo refs](https://gohugo.io/content-management/cross-references/).
+There are multiple ways to format text: for consistency and clarity, these are our conventions:
 
-- File extensions are optional.
-- You can use relative paths or just the filename. (**Paths without a leading / are first resolved relative to the current page, then to the remainder of the site.**)
-- Anchors are supported.
+- Bold: Two asterisks on each side - `**Bolded text**`.
+- Italic: One underscore on each side - `_Italicized text_`.
+- Unordered lists: One dash - `- Unordered list item`.
+- Ordered lists: The 1 character followed by a stop - `1. Ordered list item`.
 
-For example:
+> **Note**: The ordered notation automatically enumerates lists when built by Hugo.
 
-```md
-To install <product>, refer to the [installation instructions]({{< ref "install" >}}).
-```
+Close every section with a horizontal line by using three dashes: `---`.
+
+### How to format internal links
 
-### How to include images
+Internal links should use Hugo [ref and relref shortcodes](https://gohugo.io/content-management/cross-references/).
 
-You can use the `img` [shortcode](#how-to-use-hugo-shortcodes) to add images into your documentation.
+- Although file extensions are optional for Hugo, we include them as best practice for page anchors.
+- Relative paths are preferred, but just the filename is permissible.
+- Paths without a leading forward slash (`/`) are first resolved relative to the current page, then the remainder of the website.
 
-1. Add the image to the static/img directory, or to the same directory as the doc you want to use it in.
+Here are two examples:
 
-   - **DO NOT include a forward slash at the beginning of the file path.** This will break the image when it's rendered.
-     See the docs for the [Hugo relURL Function](https://gohugo.io/functions/relurl/#input-begins-with-a-slash) to learn more.
+```md
+To install <software>, refer to the [installation instructions]({{< ref "install.md" >}}).
+To install <integation>, refer to the [integration instructions]({{< relref "/integration/thing.md#section" >}}).
+```
 
-1. Add the img shortcode:
+### How to add images
 
-    {{< img src="<img-file.png>" >}}
+Use the `img` [shortcode](#using-hugo-shortcodes) to add images into your documentation.
 
-> Note: The shortcode accepts all of the same parameters as the [Hugo figure shortcode](https://gohugo.io/content-management/shortcodes/#figure).
+1. Add the image to the `/static/img` directory.
+1. Add the `img` shortcode:
+    `{{< img src="<img-file.png>" >}}`
+   - **Do not include a forward slash at the beginning of the file path.**
+   - This will break the image when it's rendered: read about the  [Hugo relURL Function](https://gohugo.io/functions/relurl/#input-begins-with-a-slash) to learn more.
 
-### How to use Hugo shortcodes
+> **Note**: The `img` shortcode accepts all of the same parameters as the Hugo [figure shortcode](https://gohugo.io/content-management/shortcodes/#figure).
 
-You can use [Hugo shortcodes](/docs/themes/f5-hugo/layouts/shortcodes/) to do things like format callouts, add images, and reuse content across different docs.
+### Using Hugo shortcodes
 
-For example, to use the note callout:
+[Hugo shortcodes](https://github.com/nginxinc/nginx-hugo-theme/tree/main/layouts/shortcodes) are used to format callouts, add images, and reuse content across different pages.
+
+For example, to use the `note` callout:
 
 ```md
-{{< note >}}Provide the text of the note here. {{< /note >}}
+{{< note >}}Provide the text of the note here.{{< /note >}}
 ```
 
-The callout shortcodes also support multi-line blocks:
+The callout shortcodes support multi-line blocks:
 
 ```md
 {{< caution >}}
-You should probably never do this specific thing in a production environment. 
+You should probably never do this specific thing in a production environment.
 
 If you do, and things break, don't say we didn't warn you.
 {{< /caution >}}
@@ -125,12 +141,14 @@ Supported callouts:
 - `tip`
 - `warning`
 
-A few more fun shortcodes:
-
-- `fa`: inserts a Font Awesome icon
-- `img`: include an image and define things like alt text and dimensions
-- `include`: include the content of a file in another file; the included file must be present in the content/includes directory
-- `link`: makes it possible to link to a file and prepend the path with the Hugo baseUrl
-- `openapi`: loads an OpenAPI spec and renders as HTML using ReDoc
-- `raw-html`: makes it possible to include a block of raw HTML
-- `readfile`: includes the content of another file in the current file; does not require the included file to be in a specific location
+Here are some other shortcodes:
+
+- `fa`: Inserts a Font Awesome icon
+- `collapse`: Make a section collapsible
+- `tab`: Create mutually exclusive tabbed window panes, useful for parallel instructions
+- `table`: Add scrollbars to wide tables for browsers with smaller viewports
+- `link`: Link to a file, prepending its path with the Hugo baseUrl
+- `openapi`: Loads an OpenAPI specifcation and render it as HTML using ReDoc
+- `include`: Include the content of a file in another file; the included file must be present in the '/content/includes/' directory
+- `raw-html`: Include a block of raw HTML
+- `readfile`: Include the content of another file in the current file, which can be in an arbitrary location.

site/go.sum

@@ -1,16 +1,2 @@
-github.com/nginxinc/nginx-hugo-theme v0.28.0 h1:RHHvBmFk2Uptk+efLPSIuBd2elc3IOZPElkJbkkpAHo=
-github.com/nginxinc/nginx-hugo-theme v0.28.0/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M=
-github.com/nginxinc/nginx-hugo-theme v0.33.0 h1:6mZdgxf5kNhInsrAXXiSlWXRy3fsP51lWKOdrvmkR6U=
-github.com/nginxinc/nginx-hugo-theme v0.33.0/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M=
-github.com/nginxinc/nginx-hugo-theme v0.34.0-alpha h1:8tKWnkhxP5Nk0V64v8rE9T3crusycohXl3wmOWc4uFk=
-github.com/nginxinc/nginx-hugo-theme v0.34.0-alpha/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M=
-github.com/nginxinc/nginx-hugo-theme v0.34.0 h1:G7LPVq7w1ls6IS4+OkTwjhFb67rLCzPdfZvW1/sn2Cw=
-github.com/nginxinc/nginx-hugo-theme v0.34.0/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M=
-github.com/nginxinc/nginx-hugo-theme v0.35.0 h1:7XB2GMy6qeJgKEJy9wOS3SYKYpfvLW3/H+UHRPLM4FU=
-github.com/nginxinc/nginx-hugo-theme v0.35.0/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M=
-github.com/nginxinc/nginx-hugo-theme v0.40.8 h1:VtoSAtf9k67tI2jzbLRo0oFBAMHZBUPRh/xV4MYullI=
-github.com/nginxinc/nginx-hugo-theme v0.40.8/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M=
-github.com/nginxinc/nginx-hugo-theme v0.41.9 h1:8TKgjocF95ZSRP0PHkyvk9TyJvwPrdz1k0FB5RfKT3I=
-github.com/nginxinc/nginx-hugo-theme v0.41.9/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M=
 github.com/nginxinc/nginx-hugo-theme v0.41.14 h1:OraNB01CdMJXufPddvIVt6qn6Mj38Z/XCVIWBgVtuY0=
 github.com/nginxinc/nginx-hugo-theme v0.41.14/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M=