feat: Update NGINX Gateway Fabric information architecture (#600)

This commit partially restructures the NGINX Gateway Fabric documentation
to flatten the folder structure, reducing the amount of steps a reader must 
navigate to get to useful instructions.

The majority of the effort is concentrated on the Install section, simplifying 
the URL structure and creating logical links in the sequence of pages presented 
and the linear connection of pre-requisites and next steps when a user is onboarding a cluster.

Additional work will follow this effort, once identifying more common user 
journeys and how individual documents can be grouped together logically.

---------

Co-authored-by: Saylor Berman <[email protected]>

Author: ADubhlaoich

_banners/ngf-2.0-release.md

@@ -1,7 +1,7 @@
 {{< banner "notice" "NGINX Gateway Fabric 2.0 is now available" >}}
 
-NGINX Gateway Fabric 2.0 has released! Follow [this guide]({{< ref "/ngf/upgrading-ngf.md" >}}) to upgrade from 1.x to 2.0.
+NGINX Gateway Fabric 2.0 has released! Follow [these instructions]({{< ref "/ngf/install/upgrade-version.md#upgrade-from-v1x-to-v2x" >}}) to upgrade from 1.x to 2.0.
 
-For 1.x, checkout [an older version](https://github.com/nginx/documentation/commit/0be97114d93be0f44acff8711f31bf0b6448dd94) of documentation.
+For 1.x, checkout [an older version]({{< ref "/ngf/install/upgrade-version.md#access-nginx-gateway-fabric-1x-documentation" >}}) of documentation.
 
 {{< /banner >}}

content/includes/ngf/installation/helm/pulling-the-chart.md

@@ -2,11 +2,9 @@
 docs: "DOCS-1439"
 ---
 
-Pull the latest stable release of the NGINX Gateway Fabric chart:
+```shell
+helm pull oci://ghcr.io/nginx/charts/nginx-gateway-fabric --untar
+cd nginx-gateway-fabric
+```
 
-   ```shell
-   helm pull oci://ghcr.io/nginx/charts/nginx-gateway-fabric --untar
-   cd nginx-gateway-fabric
-   ```
-
-   If you want the latest version from the **main** branch, add `--version 0.0.0-edge` to your pull command.
+For the latest version from the **main** branch, add _--version 0.0.0-edge_ to your pull command.

content/includes/ngf/installation/install-gateway-api-experimental-features.md

@@ -17,7 +17,7 @@ kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gate
 To enable experimental features on NGINX Gateway Fabric:
 
 Using Helm: Set `nginxGateway.gwAPIExperimentalFeatures.enable` to true. An example can be found
-in the [Installation with Helm]({{< ref "/ngf/installation/installing-ngf/helm.md#custom-installation-options" >}}) guide.
+in the [Installation with Helm]({{< ref "/ngf/install/helm.md#custom-installation-options" >}}) guide.
 
 Using Kubernetes manifests: Add the `--gateway-api-experimental-features` command-line flag to the deployment manifest args.
-An example can be found in the [Installation with Kubernetes manifests]({{< ref "/ngf/installation/installing-ngf/manifests.md#3-deploy-nginx-gateway-fabric" >}}) guide.
+An example can be found in the [Installation with Kubernetes manifests]({{< ref "/ngf/install/manifests.md#3-deploy-nginx-gateway-fabric" >}}) guide.

content/includes/ngf/installation/nginx-plus/docker-registry-secret.md

@@ -2,7 +2,7 @@
 docs: "DOCS-000"
 ---
 
-{{< note >}} If you would rather pull the NGINX Plus image and push to a private registry, you can skip this specific step and instead follow [this step]({{< ref "/ngf/installation/nginx-plus-jwt.md#pulling-an-image-for-local-use" >}}). {{< /note >}}
+{{< note >}} If you would rather pull the NGINX Plus image and push to a private registry, you can skip this specific step and instead follow [this step]({{< ref "/ngf/install/nginx-plus.md#pulling-an-image-for-local-use" >}}). {{< /note >}}
 
 If the `nginx-gateway` namespace does not yet exist, create it:
 

content/ngf/releases.md renamed to content/ngf/changelog.md

@@ -1,11 +1,10 @@
 ---
-title: Releases
-description: "NGINX Gateway Fabric releases."
-weight: 800
+title: Changelog
 toc: true
-type: reference
-product: NGF
-docs: "DOCS-1359"
+weight: 900
+nd-content-type: reference
+nd-product: NGF
+nd-docs: "DOCS-1359"
 ---
 
 See the NGINX Gateway Fabric changelog page:

content/ngf/get-started.md

@@ -2,15 +2,15 @@
 title: Get started
 weight: 200
 toc: true
-type: how-to
-product: NGF
-docs: DOCS-000
+nd-content-type: how-to
+nd-product: NGF
+nd-docs: DOCS-000
 ---
 
 {{< important >}}
 This document is for trying out NGINX Gateway Fabric, and not intended for a production environment. 
 
-For standard deployments, you should read the [Install NGINX Gateway Fabric]({{< ref "/ngf/installation/installing-ngf" >}}) section.
+For standard deployments, you should read the [Install NGINX Gateway Fabric]({{< ref "/ngf/install/" >}}) section.
 {{< /important >}}
 
 This is a guide for getting started with NGINX Gateway Fabric. It explains how to:
@@ -21,8 +21,6 @@ This is a guide for getting started with NGINX Gateway Fabric. It explains how t
 
 By following the steps in order, you will finish with a functional NGINX Gateway Fabric cluster.
 
----
-
 ## Before you begin
 
 To complete this guide, you need the following prerequisites installed:
@@ -84,8 +82,6 @@ make create-kind-cluster
 
 {{< /note >}}
 
----
-
 ## Install NGINX Gateway Fabric
 
 ### Add Gateway API resources
@@ -104,8 +100,6 @@ customresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s.
 customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking.k8s.io created
 ```
 
----
-
 ### Install the Helm chart
 
 Use `helm` to install NGINX Gateway Fabric, specifying the NodePort configuration that will be set on the 
@@ -128,8 +122,6 @@ REVISION: 1
 TEST SUITE: None
 ```
 
----
-
 ## Create an example application
 
 In the previous section, you deployed NGINX Gateway Fabric to a local cluster. This section shows you how to deploy a simple web application to test that NGINX Gateway Fabric works.
@@ -138,8 +130,6 @@ In the previous section, you deployed NGINX Gateway Fabric to a local cluster. T
 The YAML code in the following sections can be found in the [cafe-example folder](https://github.com/nginx/nginx-gateway-fabric/tree/main/examples/cafe-example) of the GitHub repository.
 {{< /note >}}
 
----
-
 ### Create the application resources
 
 Create the file _cafe.yaml_ with the following contents:
@@ -171,8 +161,6 @@ coffee-676c9f8944-k2bmd   1/1     Running   0          9s
 tea-6fbfdcb95d-9lhbj      1/1     Running   0          9s
 ```
 
----
-
 ### Create Gateway and HTTPRoute resources
 
 Create the file _gateway.yaml_ with the following contents:
@@ -217,8 +205,6 @@ httproute.gateway.networking.k8s.io/coffee created
 httproute.gateway.networking.k8s.io/tea created
 ```
 
----
-
 ### Verify the configuration
 
 You can check that all of the expected services are available using `kubectl get`:
@@ -431,8 +417,6 @@ Status:
 Events:       <none>
 ```
 
----
-
 ## Test NGINX Gateway Fabric
 
 By configuring the cluster with the port `31437`, there is implicit port forwarding from your local machine to NodePort, allowing for direct communication to the NGINX Gateway Fabric service.
@@ -463,10 +447,8 @@ URI: /tea
 Request ID: 1b5c8f3a4532ea7d7510cf14ffeb27af
 ```
 
----
-
-## See also
+## Next steps
 
-- [Install NGINX Gateway Fabric]({{< ref "/ngf/installation/installing-ngf/" >}}), for additional ways to install NGINX Gateway Fabric
-- [How-to guides]({{< ref "/ngf/how-to/" >}}), for configuring your cluster
-- [Traffic management]({{< ref "/ngf/how-to/traffic-management/" >}}), for more in-depth traffic management configuration
+- [Install NGINX Gateway Fabric]({{< ref "/ngf/install/" >}}), for additional ways to install NGINX Gateway Fabric
+- [Traffic management]({{< ref "/ngf/traffic-management/" >}}), for more in-depth traffic management configuration
+- [How-to guides]({{< ref "/ngf/how-to/" >}}), for configuring your cluster

content/ngf/how-to/_index.md

@@ -1,5 +1,5 @@
 ---
 title: "How-to guides"
 url: /nginx-gateway-fabric/how-to/
-weight: 500
+weight: 550
 ---

content/ngf/how-to/control-plane-configuration.md

@@ -13,7 +13,7 @@ Learn how to dynamically update the NGINX Gateway Fabric control plane configura
 
 NGINX Gateway Fabric can dynamically update the control plane configuration without restarting. The control plane configuration is stored in the NginxGateway custom resource, created during the installation of NGINX Gateway Fabric.
 
-NginxGateway is deployed in the same namespace as the controller (Default: `nginx-gateway`). The resource's default name is based on your [installation method]({{< ref "/ngf/installation/installing-ngf" >}}):
+NginxGateway is deployed in the same namespace as the controller (Default: `nginx-gateway`). The resource's default name is based on your [installation method]({{< ref "/ngf/install/" >}}):
 
 - Helm: `<release-name>-config`
 - Manifests: `nginx-gateway-config`

content/ngf/how-to/data-plane-configuration.md

@@ -178,7 +178,9 @@ By default, an `NginxProxy` resource is created in the same namespace where NGIN
 
 When installed using the Helm chart, the NginxProxy resource is named `<release-name>-proxy-config` and is created in the release Namespace.
 
-{{< note >}} Some global configuration also requires an [associated policy]({{< ref "/ngf/overview/custom-policies.md" >}}) to fully enable a feature (such as [tracing]({{< ref "/ngf/how-to/monitoring/tracing.md" >}}), for example). {{< /note >}}
+**For a full list of configuration options that can be set, see the `NginxProxy spec` in the [API reference]({{< ref "/ngf/reference/api.md" >}}).**
+
+{{< note >}} Some global configuration also requires an [associated policy]({{< ref "/ngf/overview/custom-policies.md" >}}) to fully enable a feature (such as [tracing]({{< ref "/ngf/monitoring/tracing.md" >}}), for example). {{< /note >}}
 
 ---
 
@@ -272,15 +274,14 @@ of a few arguments. {{</ note >}}
 
 ### Run NGINX Gateway Fabric with NGINX in debug mode
 
-To run NGINX Gateway Fabric with NGINX in debug mode, follow the [installation document]({{< ref "/ngf/installation/installing-ngf" >}}) with these additional steps:
-
-Using Helm: Set `nginx.debug` to true.
+To run NGINX Gateway Fabric with NGINX in debug mode, during [installation]({{< ref "/ngf/install/" >}}), follow these additional steps:
 
-Using Kubernetes Manifests: In the deployment manifest, set the `spec.kubernetes.deployment.container.debug` field in the `NginxProxy` resource to true.
+- **Helm**: Set _nginx.debug_ to _true_.
+- **Manifests**: Set  _spec.kubernetes.deployment.container.debug_ field in the _NginxProxy_ resource to _true_.
 
-If you want to change the NGINX mode after deploying NGINX Gateway Fabric, you can do so through the `NginxProxy` `spec.kubernetes.deployment.container.debug` field.
+To change NGINX mode **after** deploying NGINX Gateway Fabric, use the _NginxProxy_ _spec.kubernetes.deployment.container.debug_ field.
 
-The following command creates a basic `NginxProxy` configuration that both sets the NGINX log level to `debug` and runs NGINX in `debug` mode.
+The following command creates a basic _NginxProxy_ configuration that sets both the NGINX mode and log level to _debug_.
 
 ```yaml
 kubectl apply -f - <<EOF
@@ -298,7 +299,7 @@ spec:
 EOF
 ```
 
-{{< note >}} When modifying any `deployment` field in the `NginxProxy` resource, any corresponding NGINX instances will be restarted. {{< /note >}}
+{{< note >}} When modifying any _deployment_ field in the _NginxProxy_ resource, any corresponding NGINX instances will be restarted. {{< /note >}}
 
 ---
 

content/ngf/how-to/monitoring/_index.md

@@ -0,0 +1,5 @@
+---
+title: "Install"
+url: /nginx-gateway-fabric/install/
+weight: 300
+---

content/ngf/how-to/monitoring/dashboard.md

@@ -1,17 +1,15 @@
 ---
 title: Build NGINX Gateway Fabric
-weight: 500
+weight: 400
 toc: true
-type: how-to
-product: NGF
-docs: DOCS-1431
+nd-content-type: how-to
+nd-product: NGF
+nd-docs: DOCS-1431
 ---
 
 ## Overview
 
-While most users will install NGINX Gateway Fabric [with Helm]({{< ref "/ngf/installation/installing-ngf/helm.md" >}}) or [Kubernetes manifests]({{< ref "/ngf/installation/installing-ngf/manifests.md" >}}), manually building the [NGINX Gateway Fabric and NGINX images]({{< ref "/ngf/overview/gateway-architecture.md#the-nginx-gateway-fabric-pod" >}}) can be helpful for testing and development purposes. Follow the steps in this document to build the NGINX Gateway Fabric and NGINX images.
-
----
+While most users will install NGINX Gateway Fabric [with Helm]({{< ref "/ngf/install/helm.md" >}}) or [Kubernetes manifests]({{< ref "/ngf/install/manifests.md" >}}), manually building the [NGINX Gateway Fabric and NGINX images]({{< ref "/ngf/overview/gateway-architecture.md#the-nginx-gateway-fabric-pod" >}}) can be helpful for testing and development purposes. Follow the steps in this document to build the NGINX Gateway Fabric and NGINX images.
 
 ## Before you begin
 
@@ -25,7 +23,6 @@ installed on your machine:
 
 If building the NGINX Plus image, you will also need a valid NGINX Plus license certificate (`nginx-repo.crt`) and key (`nginx-repo.key`) in the root of the repo.
 
----
 
 ## Steps
 

content/ngf/how-to/traffic-management/_index.md

@@ -1,10 +1,10 @@
 ---
 title: Deploy a Gateway for data plane instances
-weight: 500
+weight: 600
 toc: true
-type: how-to
-product: NGF
-docs: DOCS-000
+nd-content-type: how-to
+nd-product: NGF
+nd-docs: DOCS-000
 ---
 
 ## Overview
@@ -19,7 +19,7 @@ A single GatewayClass can have multiple Gateways: each Gateway will create a sep
 
 ## Before you begin
 
-- [Install]({{< ref "/ngf/installation/" >}}) NGINX Gateway Fabric.
+- [Install]({{< ref "/ngf/install/" >}}) NGINX Gateway Fabric.
 
 ## Create a Gateway
 
@@ -98,7 +98,7 @@ cafe-nginx   LoadBalancer    10.96.125.117   <pending>     80:30180/TCP   5m2s
 
 The Service type can be changed, as explained in the next section.
 
-## How to modify provisioned NGINX instances
+## Modify provisioned NGINX instances
 
 The NginxProxy custom resource can modify the provisioning of the Service object and NGINX deployment when a Gateway is created.
 
@@ -180,7 +180,7 @@ NAME         TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
 cafe-nginx   NodePort       10.96.172.204   <none>        80:32615/TCP   3h5m
 ```
 
-### How to set annotations and labels on provisioned resources
+### Set annotations and labels on provisioned resources
 
 While the majority of configuration will happen on the NginxProxy resource, that is not always the case. Uniquely, if
 you want to set any annotations or labels on the NGINX Deployment or Service, you need to set those annotations on the Gateway which
@@ -236,7 +236,7 @@ Annotations:              annotationKey: annotationValue
 
 For more guides on routing traffic to applications and more information on Data Plane configuration, check out the following resources:
 
-- [Routing traffic to applications]({{< ref "/ngf/how-to/traffic-management/routing-traffic-to-your-app.md" >}})
-- [Application routes using HTTP matching conditions]({{< ref "/ngf/how-to/traffic-management/advanced-routing.md" >}})
+- [Routing traffic to applications]({{< ref "/ngf/traffic-management/basic-routing.md" >}})
+- [Application routes using HTTP matching conditions]({{< ref "/ngf/traffic-management/advanced-routing.md" >}})
 - [Data plane configuration]({{< ref "/ngf/how-to/data-plane-configuration.md" >}})
 - [API reference]({{< ref "/ngf/reference/api.md" >}})