Update top level documentation pages for style consistency (nginxinc#…

…5754)

This commit changes the top level pages of documentation 
to adhere with newer style guide conventions.

* Horizontal rules at the end of sections
* Sentence case for page titles and headings
* Note formatting
* Link introduction phrasing

Co-authored-by: Venktesh Shivam Patel <ve.patel@f5.com>

docs/content/community.md

@@ -1,11 +1,11 @@
 ---
 docs: DOCS-1447
-title: Community and Contribution
+title: Community and contributing
 toc: true
 weight: 2200
 ---
 
-There are a few ways to get involved with the NGINX Ingress Controller community and contribute to the project.
+There are a few ways to get involved with the F5 NGINX Ingress Controller community and contribute to the project.
 
 # Community
 

docs/content/glossary.md

@@ -5,6 +5,10 @@ title: Glossary
 weight: 10000
 ---
 
+This is a glossary of terms related to F5 NGINX Ingress Controller and Kubernetes as a whole.
+
+---
+
 ## Ingress {#ingress}
 
 _Ingress_ refers to an _Ingress Resource_, a Kubernetes API object which allows access to [Services](https://kubernetes.io/docs/concepts/services-networking/service/) within a cluster. They are managed by an [Ingress Controller]({{< relref "glossary.md#ingress-controller">}}).
@@ -17,8 +21,10 @@ _Ingress_ resources enable the following functionality:
 
 For additional information, please read the official [Kubernetes Ingress Documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/).
 
+---
+
 ## Ingress Controller {#ingress-controller}
 
 *Ingress Controllers* are applications within a Kubernetes cluster that enable [Ingress]({{< relref "glossary.md#ingress">}}) resources to function. They are not automatically deployed with a Kubernetes cluster, and can vary in implementation based on intended use, such as load balancing algorithms for Ingress resources.
 
-[How NGINX Ingress Controller is Designed]({{< relref "overview/design">}}) explains the technical details of the F5 NGINX Ingress Controller.
+[The design of NGINX Ingress Controller]({{< relref "overview/design.md">}}) explains the technical details of NGINX Ingress Controller.

docs/content/overview/about.md

@@ -8,9 +8,10 @@ weight: 100
 
 This document describes the F5 NGINX Ingress Controller, an Ingress Controller implementation for NGINX and NGINX Plus.
 
+---
+
 NGINX Ingress Controller is an [Ingress Controller]({{< relref "glossary.md#ingress-controller">}}) implementation for NGINX and NGINX Plus that can load balance Websocket, gRPC, TCP and UDP applications. It supports standard [Ingress]({{< relref "glossary.md#ingress">}}) features such as content-based routing and TLS/SSL termination. Several NGINX and NGINX Plus features are available as extensions to Ingress resources through [Annotations]({{< relref "configuration/ingress-resources/advanced-configuration-with-annotations">}}) and the [ConfigMap]({{< relref "configuration/global-configuration/configmap-resource">}}) resource.
 
 NGINX Ingress Controller supports the [VirtualServer and VirtualServerRoute resources]({{< relref "configuration/virtualserver-and-virtualserverroute-resources">}}) as alternatives to Ingress, enabling traffic splitting and advanced content-based routing. It also supports TCP, UDP and TLS Passthrough load balancing using [TransportServer resources]({{< relref "configuration/transportserver-resource">}}).
 
-To learn more about NGINX Ingress Controller, please read the [How NGINX Ingress Controller is Designed
-]({{< relref "overview/design">}}) and [Extensibility with NGINX Plus]({{< relref "overview/nginx-plus">}}) pages.
+To learn more about NGINX Ingress Controller, please read the [The design of NGINX Ingress Controller]({{< relref "overview/design.nd">}}) and [Extensibility with NGINX Plus]({{< relref "overview/nginx-plus.md">}}) topics.

docs/content/overview/design.md

@@ -2,7 +2,7 @@
 docs: DOCS-609
 doctypes:
 - reference
-title: How NGINX Ingress Controller is Designed
+title: The design of NGINX Ingress Controller
 toc: true
 weight: 200
 ---
@@ -18,7 +18,9 @@ We assume that the reader is familiar with core Kubernetes concepts, such as Pod
 
 For conciseness in diagrams, NGINX Ingress Controller is often labelled "IC" on this page.
 
-## NGINX Ingress Controller at a High Level
+---
+
+## NGINX Ingress Controller at a high level
 
 This figure depicts an example of NGINX Ingress Controller exposing two web applications within a Kubernetes cluster to clients on the internet:
 
@@ -38,7 +40,9 @@ The figure shows:
 
 The yellow and purple arrows represent connections related to the client traffic, and the black arrows represent access to the Kubernetes API.
 
-## The NGINX Ingress Controller Pod
+---
+
+## The NGINX Ingress Controller pod
 
 The NGINX Ingress Controller pod consists of a single container, which includes the following:
 
@@ -52,7 +56,6 @@ The following is an architectural diagram depicting how those processes interact
 
 This table describes each connection, starting with its type:
 
-
 {{< bootstrap-table "table table-bordered table-striped table-responsive" >}}
 | # | Protocols | Description |
 | --- | --- | --- |
@@ -79,6 +82,8 @@ This table describes each connection, starting with its type:
 |21|HTTP| _Admin_ can connect to the [NGINX stub_status](http://nginx.org/en/docs/http/ngx_http_stub_status_module.html#stub_status) using port 8080 via an _NGINX worker_. By default, NGINX only allows connections from `localhost`.
 {{% /bootstrap-table %}}
 
+---
+
 ### Differences with NGINX Plus
 
 The previous diagram depicts NGINX Ingress Controller using NGINX. NGINX Ingress Controller with NGINX Plus has the following differences:
@@ -87,15 +92,19 @@ The previous diagram depicts NGINX Ingress Controller using NGINX. NGINX Ingress
 - Instead of the stub status metrics, the extended metrics available from the NGINX Plus API are used.
 - In addition to TLS certs and keys, NGINX Ingress Controllerf writes JWKs from the secrets of the type `nginx.org/jwk`, and NGINX workers read them.
 
-## The NGINX Ingress Controller Process
+---
+
+## The NGINX Ingress Controller process
 
 This section covers the architecture of the NGINX Ingress Controller process, including:
 
 - How NGINX Ingress Controller processes a new Ingress resource created by a user.
 - A summary of how NGINX Ingress Controller works in relation to others Kubernetes Controllers.
 - The different components of the IC process.
 
-### Processing a New Ingress Resource
+---
+
+### Processing a new Ingress resource
 
 The following diagram depicts how NGINX Ingress Controller processes a new Ingress resource. The the NGINX master and worker processes are represented as a single rectangle, _NGINX_ for simplicity. VirtualServer and VirtualServerRoute resources are indicated similarly.
 
@@ -114,7 +123,9 @@ Processing a new Ingress resource involves the following steps: each step corres
     1. _NGINX_ reads the _configuration files_.
 1. The _Control Loop_ emits an event for the Ingress resource and updates its status. If the reload fails, the event includes the error message.
 
-### NGINX Ingress Controller is a Kubernetes Controller
+---
+
+### NGINX Ingress Controller is a Kubernetes controller
 
 With the context from the previous sections, we can generalize how NGINX Ingress Controller works:
 
@@ -147,7 +158,9 @@ NGINX Ingress Controller can watch additional Custom Resources, which are less c
 - [NGINX App Protect resources]({{< relref "installation/integrations/app-protect-dos/configuration" >}}) (APPolicies, APLogConfs, APUserSigs)
 - IngressLink resource (only one resource)
 
-## NGINX Ingress Controller Process Components
+---
+
+## NGINX Ingress Controller process components
 
 In this section, we describe the components of the NGINX Ingress Controller process and how they interact, including:
 
@@ -158,7 +171,7 @@ In this section, we describe the components of the NGINX Ingress Controller proc
 
 NGINX Ingress Controller is written in [Go](https://golang.org/) and relies heavily on the [Go client for Kubernetes](https://github.com/kubernetes/client-go). Where relevant, we include links to the source code on GitHub.
 
-### Resource Caches
+### Resource caches
 
 In an earlier section, [Processing a New Ingress Resource](#processing-a-new-ingress-resource), we mentioned that NGINX Ingress Controller has a cache of the resources in the cluster that stays in sync with the Kubernetes API by watching them for changes.
 
@@ -172,7 +185,9 @@ We also mentioned that once the cache is updated, it notifies the control loop a
 - The _Workqueue_ always tries to drain itself: if there is an element at the front, the queue will remove the element and send it to the _Controller_ by calling a callback function (See the arrow _4. Send_).
 - The _Controller_ is the primary component of NGINX Ingress Controller, which represents the _Control Loop_, explained in [The Control Loop](#the-control-loop) section. To process a workqueue element, the _Controller_ component gets the latest version of the resource from the _Store_ (See the arrow _5. Get_), reconfigures _NGINX_ according to the resource (See the arrow _6. Reconfigure*_, updates the resource status, and emits an event via the _Kubernetes API_ (See the arrow  _7. Update status and emit event_).
 
-### The Control Loop
+---
+
+### The control loop
 
 This section discusses the main components of NGINX Ingress Controller, which comprise the control loop:
 
@@ -192,7 +207,9 @@ The following diagram shows how the three components interact:
 
 {{<img src="img/control-loop.png" alt="">}}
 
-#### The Controller Sync Method
+---
+
+#### The Controller sync method
 
 The Controller [sync](https://github.com/nginxinc/kubernetes-ingress/blob/v1.11.0/internal/k8s/controller.go#L663) method is called by the _Workqueue_ to process a change of a resource. The method determines the _kind_ of the resource and calls the appropriate _sync_ method (Such as _syncIngress_ for Ingress resources).
 
@@ -213,16 +230,20 @@ To explain how the sync methods work, we will examine the most important one: th
 1. The reload status is propagated from _Manager_ to _processChanges_, and is either a success or a failure with an error message.
 1. _processChanges_ calls _updateRegularIngressStatusAndEvent_ to update the status of the Ingress resource and emit an event with the status of the reload: both make an API call to the Kubernetes API.
 
-**Additional Notes**:
+**Additional notes**:
 
 - Many details are not included for conciseness: the source code provides the most granular detail.
 - The _syncVirtualServer_, _syncVirtualServerRoute_, and _syncTransportServer_ methods are similar to _syncIngress_, while other sync methods are different. However, those methods typically find the affected Ingress, VirtualServer, and TransportServer resources and regenerate the configuration for them.
 - The _Workqueue_ has only a single worker thread that calls the sync method synchronously, meaning the _Control Loop_ processes only one change at a time.
 
-#### Helper Components
+---
+
+#### Helper components
 
 There are two additional helper components crucial for processing changes: _Configuration_ and _LocalSecretStore_.
 
+---
+
 ##### Configuration
 
 [_Configuration_](https://github.com/nginxinc/kubernetes-ingress/blob/v1.11.0/internal/k8s/configuration.go#L320) holds the latest valid state of the NGINX Ingress Controller load balancing configuration resources: Ingresses, VirtualServers, VirtualServerRoutes, TransportServers, and GlobalConfiguration.
@@ -238,16 +259,22 @@ Additionally, the _Configuration_ ensures that only one Ingress/VirtualServer/Tr
 
 Ultimately, NGINX Ingress Controller ensures the NGINX config on the filesystem reflects the state of the objects in the _Configuration_ at any point in time.
 
+---
+
 ##### LocalSecretStore
 
 [_LocalSecretStore_](https://github.com/nginxinc/kubernetes-ingress/blob/v1.11.0/internal/k8s/secrets/store.go#L32) (of the _SecretStore_ interface) holds the valid Secret resources and keeps the corresponding files on the filesystem in sync with them. Secrets are used to hold TLS certificates and keys (type `kubernetes.io/tls`), CAs (`nginx.org/ca`), JWKs (`nginx.org/jwk`), and client secrets for an OIDC provider (`nginx.org/oidc`).
 
 When _Controller_ processes a change to a configuration resource like Ingress, it creates an extended version of a resource that includes the dependencies (Such as Secrets) necessary to generate the NGINX configuration. _LocalSecretStore_ allows _Controller_ to reference the filesystem for a secret using the secret key (namespace/name).
 
+---
+
 ## Reloading NGINX
 
 The following sections describe how NGINX reloads and how NGINX Ingress Controller specifically affects this process.
 
+---
+
 ### How NGINX reloads work
 
 Reloading NGINX is necessary to apply new configuration changes and occurs with these steps:
@@ -257,6 +284,9 @@ Reloading NGINX is necessary to apply new configuration changes and occurs with
 1. The administrator verifies the reload has successfully finished.
 
 The [NGINX documentation](https://nginx.org/en/docs/control.html#reconfiguration) has more details about reloading.
+
+---
+
 #### How to reload NGINX and confirm success
 
 The NGINX binary (`nginx`) supports the reload operation with the `-s reload` option. When you run this option:
@@ -273,6 +303,8 @@ Once the reload operation has been invoked with `nginx -s reload`, there is no w
 
 NGINX reloads take roughly 200ms. The factors affecting reload time are configuration size and details, the number of TLS certificates/keys, enabled modules, and available CPU resources.
 
+---
+
 #### Potential problems
 
 Most of the time, if `nginx -s reload` executes, the reload will also succeed. In the rare case a reload fails, the NGINX master process will print the an error message. This is an example:
@@ -285,6 +317,8 @@ The operation is graceful; reloading doesn't lead to any traffic loss by NGINX.
 
 Old NGINX workers will not shut down until all connections are terminated either by clients or backends, unless you configure [worker_shutdown_timeout](https://nginx.org/en/docs/ngx_core_module.html#worker_shutdown_timeout). Since both the old and new NGINX worker processes coexist during a reload, reloading can lead to two spikes in memory utilization. With a lack of available memory, the NGINX master process can fail to create new worker processes.
 
+---
+
 ### Reloading in NGINX Ingress Controller
 
 NGINX Ingress Controller reloads NGINX to apply configuration changes.
@@ -301,7 +335,9 @@ Reloads occur with this sequence of steps:
 
 The [NGINX Ingress Controller Control Loop](#the-control-loop) stops during a reload so that it cannot affect configuration files or reload NGINX until the current reload succeeds or fails.
 
-### When NGINX Ingress Controller Reloads NGINX
+---
+
+### When NGINX Ingress Controller reloads NGINX
 
 NGINX Ingress Controller reloads NGINX every time the Control Loop processes a change that affects the generated NGINX configuration. In general, every time a monitored resource is changed, NGINX Ingress Controller will regenerate the configuration and reload NGINX.
 

docs/content/overview/nginx-plus.md

@@ -6,10 +6,12 @@ title: Extensibility with NGINX Plus
 weight: 300
 ---
 
-This document explains how F5 NGINX Plus can extend the functionality of the F5 NGINX Ingress Controller.
+This document explains how F5 NGINX Plus can extend the functionality of F5 NGINX Ingress Controller.
 
 NGINX Ingress Controller works with [NGINX](https://nginx.org/) as well as [NGINX Plus](https://www.nginx.com/products/nginx/), a commercial closed source version of NGINX which has additional features and support from NGINX Inc. NGINX Ingress Controller can leverage functionality from NGINX Plus to extend its base capabilities.
 
+---
+
 ## Additional features
 
 - _Real-time metrics_: Metrics for NGINX Plus and application performance are available through the API or the [NGINX Status Page]({{< relref "logging-and-monitoring/status-page">}}). These metrics can also be exported to [Prometheus]({{< relref "logging-and-monitoring/prometheus">}}).
@@ -20,10 +22,12 @@ NGINX Ingress Controller works with [NGINX](https://nginx.org/) as well as [NGIN
 
 For a comprehensive guide of NGINX Plus features available with Ingress resources, see the [ConfigMap]({{< relref "configuration/global-configuration/configmap-resource">}}) and [Annotations]({{< relref "configuration/ingress-resources/advanced-configuration-with-annotations">}}) documentation.
 
-{{< note >}}NGINX Plus features are configured for Ingress resources using Annotations that start with `nginx.com`.{{< /note >}}
+{{< note >}} NGINX Plus features are configured for Ingress resources using Annotations that start with `nginx.com`. {{< /note >}}
 
 For a comprehensive guide of NGINX Plus features available with custom resources, see the [Policy]({{< relref "configuration/policy-resource" >}}), [VirtualServer]({{< relref "configuration/virtualserver-and-virtualserverroute-resources" >}}) and [TransportServer]({{< relref "configuration/transportserver-resource" >}}) documentation.
 
+---
+
 ## Dynamic reconfiguration
 
 NGINX Ingress Controller updates the configuration of the load balancer to reflect changes every time the number of pods exposed through an Ingress resource changes. When using NGINX, the configuration file must be changed then reloaded.

docs/content/overview/product-telemetry.md

@@ -1,23 +1,24 @@
 ---
-title: Product Telemetry
+title: Product telemetry
 toc: true
 weight: 500
 ---
 
-Learn why NGINX Ingress Controller collects telemetry, and understand how and what it gathers.
+Learn why, what and how F5 NGINX Ingress Controller collects telemetry.
+
+---
 
 ## Overview
 
-NGINX Ingress Controller collects product telemetry data to allow its developers to understand how it's deployed and configured by users.
-This data is used to triage development work, prioritizing features and functionality that will benefit the most people.
+NGINX Ingress Controller collects product telemetry data to allow its developers to understand how it's deployed and configured by users. This data is used to triage development work, prioritizing features and functionality that will benefit the most people.
 
 Product telemetry is enabled by default, collected once every 24 hours. It's then sent to a service managed by F5 over HTTPS.
 
-{{< note >}}
-If you would prefer to avoid sending any telemetry data, you can [opt-out](#opt-out) when installing NGINX Ingress Controller.
-{{< /note >}}
+{{< note >}} If you would prefer not to send any telemetry data, you can [opt-out](#opt-out) when installing NGINX Ingress Controller. {{< /note >}}
+
+---
 
-## Data Collected
+## Data collected
 
 These are the data points collected and reported by NGINX Ingress Controller:
 
@@ -56,20 +57,24 @@ These are the data points collected and reported by NGINX Ingress Controller:
 - **IsPlus** Represents whether NGINX is Plus or OSS
 - **InstallationFlags** List of command line arguments configured for NGINX Ingress Controller
 
+---
+
 ## Opt out
 
 Product telemetry can be disabled when installing NGINX Ingress Controller.
 
 ### Helm
 
+When installing or upgrading NGINX Ingress Controller with Helm, set the `controller.telemetry.enable` option to `false`.
 
-When installing or upgrading NGINX Ingress Controller with Helm, set the `controller.telemetry.enable` option to `false`
 This can be set directly in the `values.yaml` file, or using the `--set` option
 
 ```shell
 helm upgrade --install ... --set controller.telemetry.enable=false
 ```
 
+---
+
 ### Manifests
 
 When installing NGINX Ingress Controller with Manifests, set the `-enable-telemetry-reporting` flag to `false`