Merge branch 'as-issue-99' of github.com:madebydna/nginx-documentation into as-issue-99

Author: madebydna

.github/workflows/ossf_scorecard.yml

@@ -56,6 +56,6 @@ jobs:
 
       # Upload the results to GitHub's code scanning dashboard.
       - name: Upload SARIF results to code scanning
-        uses: github/codeql-action/upload-sarif@dd746615b3b9d728a6a37ca2045b68ca76d4841a # v3.28.8
+        uses: github/codeql-action/upload-sarif@9e8d0789d4a0fa9ceb6b1738f7e269594bdd67f0 # v3.28.9
         with:
           sarif_file: results.sarif

archetypes/concept.md

@@ -0,0 +1,74 @@
+---
+# We use sentence case and present imperative tone
+title: "{{ replace .Name "-" " " | title }}"
+# Weights are assigned in increments of 100: determines sorting order
+weight: i00
+# Creates a table of contents and sidebar, useful for large documents
+toc: false
+# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this
+type: concept
+# Intended for internal catalogue and search, case sensitive:
+# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit
+product:
+# Intended for internal catalogue
+docs: "DOCS-000"
+---
+
+[//]: # "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."
+
+[//]: # "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 provides an overview of <concept>, which is used <for/in> <action 1>, <action 2> and <action 3>.
+
+It is an example of a <other concept>, and is closely related to <third concept>.
+
+---
+
+## Background
+
+[//]: # "Explain what the concept is. If possible, relate it to another commonly known concept or software."
+[//]: # "This relates the new idea to the reader using their existing knowledge, helping their understanding of it and thus what its purpose is in context."
+
+---
+
+## Use cases
+
+[//]: # "Name the individual use case sections after the actual use case itself, e.g "Route traffic between applications"
+
+### Use case 1
+
+[//]: # "A description for a use case should be a high level outline of a particular problem, then explain how the subject concept is the solution for the issue."
+
+[//]: # "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."
+
+```mermaid
+# You can use Mermaid to draw diagrams in a codeblock with mermaid as the language.
+# 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>.
+
+[//]: # "End a particular use case section with links to other pages, such as instructional documentation, other concepts, or reference information (Such as API specifications)."
+
+- [Additional reading 1](some-external-link)
+- [Additional reading 2]({{< ref "/some/internal/link.md" >}})
+- Additional reading 3
+
+### Use case 2
+
+---
+
+## Conclusion
+
+[//]: # "Summarize everything that the reader will have learned by reading this entire concept document."
+[//]: # "It should fulfill the promise made by the introductory paragraph at the top of the document."
+[//]: # "Since each use case provides links to additional documents, you may not need to link to more,"
+[//]: # "or even include the final 'See also' section."
+
+---
+
+## See also
+
+[//]: # "Link to related documents, such as concepts, reference material or similar use cases."

archetypes/default.md

@@ -0,0 +1,90 @@
+---
+# We use sentence case and present imperative tone
+title: "{{ replace .Name "-" " " | title }}"
+# Weights are assigned in increments of 100: determines sorting order
+weight: i00
+# Creates a table of contents and sidebar, useful for large documents
+toc: false
+# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this
+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
+product:
+# Intended for internal catalogue
+docs: "DOCS-000"
+---
+
+[//]: # "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."
+
+[//]: # "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 explains how to <X> with <Y>. In involves the use of <A>, <B> and <C>, demonstrating how <X> works with an example <Z>.
+
+---
+
+## Before you begin
+
+[//]: # "List everything someone will need installed or configured before it's required. Link directly to installation guides where possible."
+
+To complete this guide, you will need the following prerequisites:
+
+- [Requirement 1](some-external-link)
+- [Requirement 2]({{< ref "/some/internal/link.md" >}})
+- Requirement 3
+
+[//]: # "Note the style of link for requirement two: keep the markdown extension. Links are resolved from the root of the documentation folder, often /site."
+
+---
+
+## Step 1
+
+[//]: # "Explain the initial step: this is usually creating or configuring a resource. Sub-steps may not be necessary, depending on complexity."
+
+```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 (...).
+```
+
+### Sub-step 1
+
+[//]: # "Sub-steps are ways of breaking steps into even smaller sections. Each step or sub-step should focus on one thing at a time: a user should be able to stop at the end of section and come back afterwards without leaving their software in a non-functional state."
+
+---
+
+### Sub-step 2
+
+[//]: # "A useful final sub-step for a given section is some kind of verification or testing, so the reader is confident the steps have been successful."
+
+---
+
+## Step 2
+
+[//]: # "Explain any additional steps required. If the how-to guide involves multiple components, each component can have its own step for delineation."
+
+### 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
+
+---
+
+## See also
+
+[//]: # "Link to related documents, such as concepts, reference material or similar use cases."

archetypes/tutorial.md

@@ -0,0 +1,122 @@
+---
+# We use sentence case and present imperative tone
+title: "{{ replace .Name "-" " " | title }}"
+# Weights are assigned in increments of 100: determines sorting order
+weight: i00
+# Creates a table of contents and sidebar, useful for large documents
+toc: false
+# Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this
+type: tutorial
+# Intended for internal catalogue and search, case sensitive:
+# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit
+product:
+# Intended for internal catalogue
+docs: "DOCS-000"
+---
+
+[//]: # "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."
+
+[//]: # "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.
+
+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>.
+
+---
+
+## Before you begin
+
+[//]: # "List everything someone will need installed or configured before it's required. Link directly to installation guides where possible."
+
+To complete this guide, you will need the following prerequisites:
+
+- [Requirement 1](some-external-link)
+- [Requirement 2]({{< ref "/some/internal/link.md" >}})
+- Requirement 3
+
+[//]: # "Note the style of link for requirement two: keep the markdown extension. Links are resolved from the root of the documentation folder, often /site."
+
+---
+
+## Step 1
+
+[//]: # "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:
+
+[//]: # "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."
+
+```mermaid
+# You can use Mermaid to draw diagrams in a codeblock with mermaid as the language.
+# 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>.
+
+---
+
+### 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.
+
+```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:
+
+```shell
+<a copyable, single line command>
+```
+```
+<the output of that command, possibly truncated and with changed IPs or domains>
+```
+
+---
+
+### Sub-step 2
+
+---
+
+## Step 2
+
+[//]: # "Explain any additional steps required. If the tutorial involves multiple components, each component can have its own step for delineation."
+
+---
+
+### 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."
+
+---
+
+## See also
+
+[//]: # "Link to related documents, such as concepts, reference material or similar use cases."

config/_default/config.toml

@@ -16,6 +16,7 @@ enableGitInfo = true
   ngf = '/nginx-gateway-fabric/:sections[1:]/:filename'
   nim = '/nginx-instance-manager/:sections[1:]/:filename'
   nms = '/nginx-management-suite/:sections[1:]/:filename'
+  agent = '/nginx-agent/:sections[1:]/:filename'
 
 [caches]
   [caches.modules]

content/agent/_index.md

@@ -0,0 +1,9 @@
+---
+title: "NGINX Agent"
+description: "NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus instance."
+linkTitle: "NGINX Agent"
+menu: docs
+url: /nginx-agent/
+cascade:
+  logo: "NGINX-product-icon.png"
+---