Update documentation for style consistency (#2256)

This commit updates most of the documentation set to adhere to some contemporary documentation style standards: - Sentence case for titles and headings - Initial headings for how-to guides as "Overview" and "Before you begin" - Moving any frontmatter descriptions to the body of text - Removing unnecessary frontmatter data altogether - Removing unnecessary custom style tag (Incorporated into the theme by default) It also collapses a few single document directories (Adding an unnecessary "hop" for users) and re-orders some sections.
nginxinc · Jul 25, 2024 · 5b3ac4f · 5b3ac4f
1 parent d76d8eb
commit 5b3ac4f
Show file tree

Hide file tree

Showing 38 changed files with 148 additions and 159 deletions.
diff --git a/site/config/api/pkg.tpl b/site/config/api/pkg.tpl
@@ -1,11 +1,14 @@
 {{ define "packages" }}
 ---
-title: "API Reference"
-description: "NGINX Gateway API Reference"
+title: "API reference"
 weight: 100
 toc: false
 ---
 
+## Overview
+
+NGINX Gateway API Reference
+
 {{ with .packages}}
 <p>Packages:</p>
 <ul>

diff --git a/site/content/how-to/_index.md b/site/content/how-to/_index.md
@@ -1,9 +1,4 @@
 ---
-title: "How-To Guides"
-description:
+title: "How-to guides"
 weight: 300
-linkTitle: "Guides"
-menu:
-  docs:
-    parent: NGINX Gateway Fabric
 ---
diff --git a/site/content/how-to/configuration/_index.md b/site/content/how-to/configuration/_index.md
diff --git a/...figuration/control-plane-configuration.md → ...ent/how-to/control-plane-configuration.md b/...figuration/control-plane-configuration.md → ...ent/how-to/control-plane-configuration.md
@@ -1,11 +1,12 @@
 ---
-title: "Control Plane Configuration"
-description: "Learn how to dynamically update the Gateway Fabric control plane configuration."
-weight: 100
+title: "Control plane configuration"
+weight: 300
 toc: true
 docs: "DOCS-1416"
 ---
 
+Learn how to dynamically update the Gateway Fabric control plane configuration.
+
 ## Overview
 
 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.

diff --git a/site/content/how-to/maintenance/_index.md b/site/content/how-to/maintenance/_index.md
diff --git a/site/content/how-to/monitoring/_index.md b/site/content/how-to/monitoring/_index.md
@@ -1,9 +1,4 @@
 ---
-title: "Monitoring and Troubleshooting"
-description:
-weight: 400
-linkTitle: "Monitoring and Troubleshooting"
-menu:
-  docs:
-    parent: How-To Guides
+title: "Monitoring and troubleshooting"
+weight: 200
 ---
diff --git a/site/content/how-to/monitoring/dashboard.md b/site/content/how-to/monitoring/dashboard.md
@@ -1,12 +1,11 @@
 ---
-title: "NGINX Plus Dashboard"
-description: "Learn how to view the NGINX Plus dashboard to see real-time metrics."
+title: "NGINX Plus dashboard"
 weight: 300
 toc: true
 docs: "DOCS-1417"
 ---
 
-{{<custom-styles>}}
+Learn how to view the NGINX Plus dashboard to see real-time metrics.
 
 ## Overview
 

diff --git a/site/content/how-to/monitoring/prometheus.md b/site/content/how-to/monitoring/prometheus.md
@@ -1,16 +1,14 @@
 ---
-title: "Prometheus Metrics"
-description: "This document describes how to monitor NGINX Gateway Fabric using Prometheus and Grafana. It explains installation and configuration, as well as what metrics are available."
+title: "Prometheus metrics"
 weight: 100
 toc: true
 docs: "DOCS-1418"
 ---
 
-{{<custom-styles>}}
+This document describes how to monitor NGINX Gateway Fabric using Prometheus and Grafana. It explains installation and configuration, as well as what metrics are available.
 
 ## Overview
 
-
 NGINX Gateway Fabric metrics are displayed in [Prometheus](https://prometheus.io/) format. These metrics are served through a metrics server orchestrated by the controller-runtime package on HTTP port `9113`. When installed, Prometheus automatically scrapes this port and collects metrics. [Grafana](https://grafana.com/) can be used for rich visualization of these metrics.
 
 {{<call-out "important" "Security note for metrics">}}
@@ -98,7 +96,7 @@ Provided by the [controller-runtime](https://github.com/kubernetes-sigs/controll
 - Go runtime metrics such as the number of Go routines, garbage collection duration, and Go version.
 - Controller-specific metrics, including reconciliation errors per controller, length of the reconcile queue, and reconciliation latency.
 
-## How to change the default metrics configuration
+## Change the default metrics configuration
 
 You can configure monitoring metrics for NGINX Gateway Fabric using Helm or Manifests.
 

diff --git a/site/content/how-to/monitoring/tracing.md b/site/content/how-to/monitoring/tracing.md
@@ -17,7 +17,7 @@ This guide explains how to enable tracing on HTTPRoutes using NGINX Gateway Fabr
 Tracing cannot be enabled for [HTTPRoute matches](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRouteMatch) with `headers`, `params`, or `method` matchers defined. It will be added in a future release.
 {{< /important >}}
 
-## Install the Collectors
+## Install the collectors
 
 The first step is to install the collectors. NGINX Gateway Fabric will be configured to export to the OpenTelemetry Collector, which is configured to export to Jaeger. This model allows the visualization collector (Jaeger) to be swapped with something else, or to add more collectors without needing to reconfigure NGINX Gateway Fabric. It is also possible to configure NGINX Gateway Fabric to export directly to Jaeger.
 
@@ -333,7 +333,7 @@ Select a trace to view the attributes.
 
 The trace includes the attribute from the global NginxProxy resource as well as the attribute from the ObservabilityPolicy.
 
-## Further Reading
+## Further reading
 
 - [Custom policies]({{< relref "overview/custom-policies.md" >}}): learn about how NGINX Gateway Fabric custom policies work.
 - [API reference]({{< relref "reference/api.md" >}}): all configuration fields for the policies mentioned in this guide
diff --git a/site/content/how-to/monitoring/troubleshooting.md b/site/content/how-to/monitoring/troubleshooting.md
@@ -5,11 +5,8 @@ toc: true
 docs: "DOCS-1419"
 ---
 
-{{< custom-styles >}}
-
 This topic describes possible issues when using NGINX Gateway Fabric and general troubleshooting techniques. When possible, suggested workarounds are provided.
 
-
 ### General troubleshooting
 
 When investigating a problem or requesting help, there are important data points that can be collected to help understand what issues may exist.

diff --git a/site/content/how-to/traffic-management/_index.md b/site/content/how-to/traffic-management/_index.md
@@ -1,9 +1,4 @@
 ---
-title: "Traffic Management"
-description:
-weight: 300
-linkTitle: "Traffic Management"
-menu:
-  docs:
-    parent: How-To Guides
+title: "Traffic management"
+weight: 100
 ---
diff --git a/site/content/how-to/traffic-management/advanced-routing.md b/site/content/how-to/traffic-management/advanced-routing.md
@@ -1,20 +1,23 @@
 ---
-title: "Routing to Applications Using HTTP Matching Conditions"
-description: "Learn how to deploy multiple applications and HTTPRoutes with request conditions such as paths, methods, headers, and query parameters"
+title: "Application routes using HTTP matching conditions"
 weight: 200
 toc: true
 docs: "DOCS-1422"
 ---
 
+Learn how to deploy multiple applications and HTTPRoutes with request conditions such as paths, methods, headers, and query parameters
+
+## Overview
+
 In this guide we will configure advanced routing rules for multiple applications. These rules will showcase request matching by path, headers, query parameters, and method. For an introduction to exposing your application, we recommend that you follow the [basic guide]({{< relref "/how-to/traffic-management/routing-traffic-to-your-app.md" >}}) first.
 
 The following image shows the traffic flow that we will be creating with these rules.
 
-{{<img src="img/advanced-routing.png" alt="Traffic Flow Diagram">}}
+{{<img src="img/advanced-routing.png" alt="">}}
 
 The goal is to create a set of rules that will result in client requests being sent to specific backends based on the request attributes. In this diagram, we have two versions of the `coffee` service. Traffic for v1 needs to be directed to the old application, while traffic for v2 needs to be directed towards the new application. We also have two `tea` services, one that handles GET operations and one that handles POST operations. Both the `tea` and `coffee` applications share the same Gateway.
 
-## Prerequisites
+## Before you begin
 
 - [Install]({{< relref "/installation/" >}}) NGINX Gateway Fabric.
 - [Expose NGINX Gateway Fabric]({{< relref "installation/expose-nginx-gateway-fabric.md" >}}) and save the public IP
@@ -27,17 +30,17 @@ The goal is to create a set of rules that will result in client requests being s
 
 {{< note >}}In a production environment, you should have a DNS record for the external IP address that is exposed, and it should refer to the hostname that the gateway will forward for.{{< /note >}}
 
-## Coffee Applications
+## Coffee applications
 
-### Deploy the Coffee Applications
+### Deploy the Coffee applications
 
 Begin by deploying the `coffee-v1` and `coffee-v2` applications:
 
 ```shell
 kubectl apply -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/v1.3.0/examples/advanced-routing/coffee.yaml
 ```
 
-### Deploy the Gateway API Resources for the Coffee Applications
+### Deploy the Gateway API Resources for the Coffee applications
 
 The [gateway](https://gateway-api.sigs.k8s.io/api-types/gateway/) resource is typically deployed by the [cluster operator](https://gateway-api.sigs.k8s.io/concepts/roles-and-personas/#roles-and-personas_1). To deploy the gateway:
 
@@ -111,7 +114,7 @@ This HTTPRoute has a few important properties:
 
   If you want both conditions to be required, you can define headers and queryParams in the same match object.
 
-### Send Traffic to Coffee
+### Send traffic to Coffee
 
 Using the external IP address and port for NGINX Gateway Fabric, we can send traffic to our coffee applications.
 
@@ -147,17 +150,17 @@ Server address: 10.244.0.9:8080
 Server name: coffee-v2-68bd55f798-s9z5q
 ```
 
-## Tea Applications
+## Tea applications
 
 Let's deploy a different set of applications now called `tea` and `tea-post`. These applications will have their own set of rules, but will still attach to the same gateway listener as the `coffee` apps.
 
-### Deploy the Tea Applications
+### Deploy the Tea applications
 
 ```shell
 kubectl apply -f https://raw.githubusercontent.com/nginxinc/nginx-gateway-fabric/v1.3.0/examples/advanced-routing/tea.yaml
 ```
 
-### Deploy the HTTPRoute for the Tea Services
+### Deploy the HTTPRoute for the Tea services
 
 We are reusing the previous gateway for these applications, so all we need to create is the HTTPRoute.
 
@@ -199,7 +202,7 @@ The properties of this HTTPRoute include:
 - The first rule defines that a POST request to the `/tea` path is routed to the `tea-post` Service.
 - The second rule defines that a GET request to the `/tea` path is routed to the `tea` Service.
 
-### Send Traffic to Tea
+### Send traffic to Tea
 
 Using the external IP address and port for NGINX Gateway Fabric, we can send traffic to our tea applications.
 
@@ -332,7 +335,7 @@ If you have any issues while sending traffic, try the following to debug your co
 
   Check for any error messages in the conditions.
 
-## Further Reading
+## Further reading
 
 To learn more about the Gateway API and the resources we created in this guide, check out the following Kubernetes documentation resources:
 

diff --git a/site/content/how-to/traffic-management/client-settings.md b/site/content/how-to/traffic-management/client-settings.md
@@ -1,5 +1,5 @@
 ---
-title: "Client Settings Policy"
+title: "Client Settings Policy API"
 weight: 800
 toc: true
 docs: "DOCS-000"
@@ -148,7 +148,6 @@ Events:                      <none>
 
 Next, test that the policy is configured by sending a POST request to the coffee and tea applications exceeding the client's max body size of 50 bytes.
 
-
 ```shell
 curl --resolve cafe.example.com:$GW_PORT:$GW_IP http://cafe.example.com:$GW_PORT/coffee -X POST --data "this payload is greater than fifty bytes by four bytes"
 ```
@@ -279,7 +278,7 @@ spec:
 EOF
 ```
 
-## Further Reading
+## Further reading
 
 - [Custom policies]({{< relref "overview/custom-policies.md" >}}): learn about how NGINX Gateway Fabric custom policies work.
 - [API reference]({{< relref "reference/api.md" >}}): all configuration fields for the `ClientSettingsPolicy` API.
diff --git a/site/content/how-to/traffic-management/https-termination.md b/site/content/how-to/traffic-management/https-termination.md
@@ -1,14 +1,17 @@
 ---
-title: "HTTPS Termination"
-description: "Learn how to terminate HTTPS traffic using NGINX Gateway Fabric."
-weight: 500
+title: "HTTPS termination"
+weight: 600
 toc: true
 docs: "DOCS-1421"
 ---
 
+Learn how to terminate HTTPS traffic using NGINX Gateway Fabric.
+
+## Overview
+
 In this guide, we will show how to configure HTTPS termination for your application, using an [HTTPRoute](https://gateway-api.sigs.k8s.io/api-types/httproute/) redirect filter, secret, and [ReferenceGrant](https://gateway-api.sigs.k8s.io/api-types/referencegrant/).
 
-## Prerequisites
+## Before you begin
 
 - [Install]({{< relref "installation/" >}}) NGINX Gateway Fabric.
 - [Expose NGINX Gateway Fabric]({{< relref "installation/expose-nginx-gateway-fabric.md" >}}) and save the public IP address and port of NGINX Gateway Fabric into shell variables:
@@ -85,7 +88,7 @@ NAME                 TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)   AGE
 service/coffee       ClusterIP   10.96.189.37   <none>        80/TCP    40s
 ```
 
-## Configure HTTPS Termination and Routing
+## Configure HTTPS termination and routing
 
 For the HTTPS, we need a certificate and key that are stored in a secret. This secret will live in a separate namespace, so we will need a ReferenceGrant in order to access it.
 
@@ -238,7 +241,7 @@ Server address: 10.244.0.6:80
 Server name: coffee-6b8b6d6486-7fc78
 ```
 
-## Further Reading
+## Further reading
 
 To learn more about redirects using the Gateway API, see the following resource:
 

diff --git a/site/content/how-to/traffic-management/integrating-cert-manager.md b/site/content/how-to/traffic-management/integrating-cert-manager.md
@@ -1,11 +1,14 @@
 ---
-title: "Securing Traffic using Let's Encrypt and Cert-Manager"
-description: "Learn how to issue and mange certificates using Let's Encrypt and cert-manager."
+title: "Secure traffic using Let's Encrypt and cert-manager"
 weight: 300
 toc: true
 docs: "DOCS-1425"
 ---
 
+Learn how to issue and mange certificates using Let's Encrypt and cert-manager.
+
+## Overview
+
 Securing client server communication is a crucial part of modern application architectures. One of the most important steps in this process is implementing HTTPS (HTTP over TLS/SSL) for all communications. This encrypts the data transmitted between the client and server, preventing eavesdropping and tampering. To do this, you need an SSL/TLS certificate from a trusted Certificate Authority (CA). However, issuing and managing certificates can be a complicated manual process. Luckily, there are many services and tools available to simplify and automate certificate issuance and management.
 
 Follow the steps in this guide to:
@@ -14,14 +17,14 @@ Follow the steps in this guide to:
 - Use [Let’s Encrypt](https://letsencrypt.org) as the Certificate Authority (CA) issuing the TLS certificate.
 - Use [cert-manager](https://cert-manager.io) to automate the provisioning and management of the certificate.
 
-## Prerequisities
+## Before you begin
 
 - Administrator access to a Kubernetes cluster.
 - [Helm](https://helm.sh) and [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) must be installed locally.
 - [NGINX Gateway Fabric deployed]({{< relref "/installation/" >}}) in the Kubernetes cluster.
 - A DNS-resolvable domain name is required. It must resolve to the public endpoint of the NGINX Gateway Fabric deployment, and this public endpoint must be an external IP address or alias accessible over the internet. The process here will depend on your DNS provider. This DNS name will need to be resolvable from the Let’s Encrypt servers, which may require that you wait for the record to propagate before it will work.
 
-## Overview
+## Secure traffic using Let's Encrypt and cert-manage
 
 {{<img src="img/cert-manager-gateway-workflow.png" alt="cert-manager ACME challenge and certificate management with Gateway API">}}
 
@@ -37,7 +40,7 @@ At a high level, the process looks like this:
 1. When the client connects to `https://cafe.example.com/coffee`, the request is routed to the coffee-app application and the communication is secured using the signed keypair contained in the cafe-secret secret.
 1. The certificate will be automatically renewed when it is close to expiry, the secret will be updated using the new certificate, and NGINX Gateway Fabric will dynamically update the keypair on the filesystem used by NGINX for HTTPS termination once the secret is updated.
 
-## Securing Traffic
+## Securing traffic
 
 ### Deploy cert-manager