Agent V3 documentation changes

.github/workflows/docs-build-push.yml

@@ -0,0 +1,44 @@
+name: Build and deploy (docs)
+on:
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: 'Environment to deploy to'
+        required: false
+        default: 'preview'
+        type: choice
+        options:
+        - preview
+        - dev
+        - staging
+        - prod
+  pull_request:
+    branches:
+      - "*"
+    paths:
+      - site/**
+  push:
+    branches:
+      - "main"
+
+permissions:
+  contents: read
+
+jobs:
+  call-docs-build-push:
+    uses: nginxinc/docs-actions/.github/workflows/docs-build-push.yml@69843fb5d009e99750e50c23e90c23a899e4637e # v1.0.6
+    permissions:
+      pull-requests: write # needed to write preview url comment to PR
+      contents: read
+    with:
+      production_url_path: "/nginx-agent"
+      preview_url_path: "/previews/nginx-agent"
+      docs_source_path: "public/nginx-agent"
+      docs_build_path: "./site"
+      doc_type: "hugo"
+      environment: ${{inputs.environment}}
+      auto_deploy_branch: "main"
+      auto_deploy_env: "staging"
+    secrets:
+      AZURE_CREDENTIALS: ${{secrets.AZURE_CREDENTIALS_DOCS}}
+      AZURE_KEY_VAULT: ${{secrets.AZURE_KEY_VAULT_DOCS}}

README.md

@@ -12,7 +12,10 @@ NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus insta
 - Collection and reporting of real-time NGINX performance and operating system metrics
 - Notifications of NGINX events
 
+> **Note**: There is a separate [README for Agent version 2](README_v2.md) and earlier.
+
 ## Development Environment Setup
+
 ### Installing Prerequisite Packages
 The following packages need to be installed:
  - make

README_v2.md

@@ -0,0 +1,57 @@
+![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/nginx/agent)
+![GitHub License](https://img.shields.io/github/license/nginx/agent)
+![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)
+[![Slack](https://img.shields.io/badge/slack-join%20us-brightgreen.svg?logo=slack)](https://nginxcommunity.slack.com/channels/nginx-agent)
+![coverage](https://raw.githubusercontent.com/nginx/agent/badges/.badges/v3/coverage.svg)
+
+# NGINX Agent
+
+NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus instance. It enables:
+
+- Remote management of NGINX configurations
+- Collection and reporting of real-time NGINX performance and operating system metrics
+- Notifications of NGINX events
+
+> **Note**: There is a separate [README for Agent version 3](README.md) and later.
+
+## NGINX Agent Technical Specifications
+
+## Supported Distributions
+
+NGINX Agent can run in most environments. For a list of supported distributions, see the [NGINX Technical Specs](https://docs.nginx.com/nginx/technical-specs/#supported-distributions) guide.
+
+## Supported Deployment Environments
+
+NGINX Agent can be deployed in the following environments:
+
+- Bare Metal
+- Container
+- Public Cloud: AWS, Google Cloud Platform, and Microsoft Azure
+- Virtual Machine
+
+## Supported NGINX Product Versions
+
+NGINX Agent works with all supported versions of NGINX Open Source and NGINX Plus.
+
+## Sizing Recommendations
+
+Minimum system sizing recommendations for NGINX Agent:
+TBD
+
+## Community
+
+- Our [Slack channel #nginx-agent](https://nginxcommunity.slack.com/), is the go-to place to start asking questions and sharing your thoughts.
+
+- Our [GitHub issues page](https://github.com/nginx/agent/issues) offers space for a more technical discussion at your own pace.
+
+## Contributing
+
+Get involved with the project by contributing! Please see our [contributing guide](CONTRIBUTING.md) for details.
+
+## Change Log
+
+See our [release page](https://github.com/nginx/agent/releases) to keep track of updates.
+
+## License
+
+[Apache License, Version 2.0](LICENSE)

site/Makefile

@@ -0,0 +1,64 @@
+HUGO?=hugo
+HUGO_VERSION?=$(shell hugo version 2>/dev/null | awk '{print $$2}' | cut -d '.' -f 2)
+HUGO_IMG?=hugomods/hugo:std-go-git-0.134.3
+
+THEME_MODULE = github.com/nginxinc/nginx-hugo-theme
+
+ifeq ($(shell [ $(HUGO_VERSION) -gt 133 2>/dev/null ] && echo true || echo false), true)
+    $(info Hugo is available and has a version greater than 133. Proceeding with build.)
+else
+    $(warning Hugo is not available or using a version less than 134. Attempting to use docker. HUGO_VERSION=$(HUGO_VERSION))
+    HUGO=docker run --rm -it -v ${CURDIR}:/src -p 1313:1313 ${HUGO_IMG} /src/hugo-entrypoint.sh
+    ifeq (, $(shell docker version 2> /dev/null))
+        $(error Hugo (>0.134) or Docker are required to build the local previews.)
+    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))
+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))
+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 -u github.com/nginxinc/nginx-hugo-theme
+
+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) and host them on [Netlify](https://www.netlify.com/).
+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/config/_default/config.toml

@@ -1,5 +1,5 @@
 title = "NGINX Agent"
-enableGitInfo = false
+enableGitInfo = true
 baseURL = "/"
 publishDir = "public/nginx-agent"
 staticDir = ["static"]

site/config/docker/config.toml

@@ -0,0 +1 @@
+enableGitInfo = false

site/content/_index.md

@@ -1,6 +1,6 @@
 ---
-title: "Welcome to the NGINX Agent documentation"
-description: "NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus instance."
-linkTitle: "NGINX Agent"
-menu: docs
----
+title: "NGINX Agent Documentation"
+weight: 900
+---
+
+NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus instance