nginx · kate-osborn · Jul 20, 2023 · Jul 18, 2023 · Jul 20, 2023 · Jul 20, 2023
@@ -76,3 +76,15 @@ jobs:
       - uses: reviewdog/action-actionlint@7485c2136bd093d2317a854c72910eebaee35238 # v1.37.1
         with:
           actionlint_flags: -shellcheck ""
+
+  markdown-lint:
+    name: Markdown Lint
+    runs-on: ubuntu-22.04
+    steps:
+    - name: Checkout Repository
+      uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 # v3.5.3
+
+    - uses: DavidAnson/markdownlint-cli2-action@8f3516061301755c97ff833a8e933f09282cc5b5 # v11.0.0
+      with:
+        config: ${{ github.workspace }}/.markdownlint-cli2.yaml
+        globs: '**/*.md'
@@ -0,0 +1,23 @@
+# Rule configuration.
+# For rule descriptions and how to fix: https://github.com/DavidAnson/markdownlint/tree/main#rules--aliases
+config:
+  ul-style:
+    style: dash
+  no-hard-tabs: false
+  no-multiple-blanks: false
+  line-length:
+    line_length: 120
+    code_blocks: false
+    tables: false
+  blanks-around-headers: false
+  no-duplicate-heading:
+    siblings_only: true
+  no-inline-html: false
+  no-bare-urls: false
+  no-emphasis-as-heading: false
+  first-line-h1: false
+  code-block-style: false
+
+# Define glob expressions to ignore
+ignores:
+  - ".github/"
@@ -48,5 +48,12 @@ repos:
       - id: golangci-lint
         args: [--new-from-patch=/tmp/diff.patch]
 
+    # Rules are in .markdownlint-cli2.yaml file
+    # See https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md for rule descriptions
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.8.1
+    hooks:
+    - id: markdownlint-cli2-fix
+
 ci:
-  skip: [golang-diff, golangci-lint, prettier]
+  skip: [golang-diff, golangci-lint, prettier, markdownlint-cli2-fix]
@@ -16,21 +16,21 @@ appearance, race, religion, or sexual identity and orientation.
 Examples of behavior that contributes to creating a positive environment
 include:
 
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
 
 Examples of unacceptable behavior by participants include:
 
-* The use of sexualized language or imagery and unwelcome sexual attention or
+- The use of sexualized language or imagery and unwelcome sexual attention or
   advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
   address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+- Other conduct which could reasonably be considered inappropriate in a
   professional setting
 
 ## Our Responsibilities

@@ -3,16 +3,16 @@
 The following is a set of guidelines for contributing to NGINX Kubernetes Gateway. We really appreciate that you are
 considering contributing!
 
-#### Table Of Contents
+## Table Of Contents
 
 [Ask a Question](#ask-a-question)
 
 [Getting Started](#getting-started)
 
 [Contributing](#contributing)
 
-* [Issues and Discussions](#issues-and-discussions)
-* [Development Guide](#development-guide)
+- [Issues and Discussions](#issues-and-discussions)
+- [Development Guide](#development-guide)
 
 [Code of Conduct](CODE_OF_CONDUCT.md)
 
@@ -33,15 +33,15 @@ Follow our [Installation Instructions](/docs/installation.md) to get the NGINX K
 
 ### Project Structure
 
-* NGINX Kubernetes Gateway is written in Go and uses the open source NGINX software as the data plane.
-* The project follows a standard Go project layout
-    * The main code is found at `cmd/gateway/`
-    * The internal code is found at `internal/`
-    * Build files for Docker are found under `build/`
-    * Deployment yaml files are found at `deploy/`
-    * External APIs, clients, and SDKs can be found under `pkg/`
-* We use [Go Modules](https://github.com/golang/go/wiki/Modules) for managing dependencies.
-* We use [Ginkgo](https://onsi.github.io/ginkgo/) and [Gomega](https://onsi.github.io/gomega/) for our BDD style unit
+- NGINX Kubernetes Gateway is written in Go and uses the open source NGINX software as the data plane.
+- The project follows a standard Go project layout
+  - The main code is found at `cmd/gateway/`
+  - The internal code is found at `internal/`
+  - Build files for Docker are found under `build/`
+  - Deployment yaml files are found at `deploy/`
+  - External APIs, clients, and SDKs can be found under `pkg/`
+- We use [Go Modules](https://github.com/golang/go/wiki/Modules) for managing dependencies.
+- We use [Ginkgo](https://onsi.github.io/ginkgo/) and [Gomega](https://onsi.github.io/gomega/) for our BDD style unit
   tests.
 
 ## Contributing

@@ -7,25 +7,24 @@ lifecycle.)
 
 1. New issue created by community member.
 
-
 2. Assign issue owner: All new issues are assigned an owner on the NGINX engineering team. This owner shepherds the
    issue through the subsequent stages in the issue lifecycle.
 
-
 3. Determine issue type: This is done with automation where possible, and manually by the owner where necessary. The
    associated label is applied to the issue.
-   #### Possible Issue Types
-   `needs more info`: The owner should use the issue to request information from the creator. If we don't receive the
-   needed information within 7 days, automation closes the issue.
 
-   `bug`: The implementation of a feature is not correct.
+   Possible Issue Types:
 
-   `enhancement`:  An enhancement, tackling technical debt, documentation changes, or improving existing features.
+   - `needs more info`: The owner should use the issue to request information from the creator. If we don't receive the
+         needed information within 7 days, automation closes the issue.
 
-   `enhancement-proposal`: Enhancements that require an [Enhancement Proposal](/docs/proposals/README.md).
+   - `bug`: The implementation of a feature is not correct.
 
-   `question`: The owner converts the issue to a github discussion and engages the creator.
+   - `enhancement`:  An enhancement, tackling technical debt, documentation changes, or improving existing features.
 
+   - `enhancement-proposal`: Enhancements that require an [Enhancement Proposal](/docs/proposals/README.md).
+
+   - `question`: The owner converts the issue to a github discussion and engages the creator.
 
 4. Determine milestone: The owner, in collaboration with the wider team (product management & engineering), determines
    what milestone to attach to an issue. Generally, milestones correspond to product releases - however there are two
@@ -43,7 +42,6 @@ lifecycle.)
 
    `backlog` issues can be labeled by the owner as `help wanted` and/or `good first issue` as appropriate.
 
-
 5. Promotion of `backlog candidate` issue to `backlog` issue: If an issue labelled `backlog candidate` receives more
    than 30 upvotes within 60 days, we promote the issue by applying the `backlog` label. While issues promoted in this
    manner have not been committed to a particular release, we welcome PRs from the community on them.

@@ -1,73 +1,93 @@
-[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/nginxinc/nginx-kubernetes-gateway/badge)](https://api.securityscorecards.dev/projects/github.com/nginxinc/nginx-kubernetes-gateway) [![FOSSA Status](https://app.fossa.com/api/projects/custom%2B5618%2Fgithub.com%2Fnginxinc%2Fnginx-kubernetes-gateway.svg?type=shield)](https://app.fossa.com/projects/custom%2B5618%2Fgithub.com%2Fnginxinc%2Fnginx-kubernetes-gateway?ref=badge_shield)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/nginxinc/nginx-kubernetes-gateway/badge)](https://api.securityscorecards.dev/projects/github.com/nginxinc/nginx-kubernetes-gateway)
+[![FOSSA Status](https://app.fossa.com/api/projects/custom%2B5618%2Fgithub.com%2Fnginxinc%2Fnginx-kubernetes-gateway.svg?type=shield)](https://app.fossa.com/projects/custom%2B5618%2Fgithub.com%2Fnginxinc%2Fnginx-kubernetes-gateway?ref=badge_shield)
 
 # NGINX Kubernetes Gateway
 
-NGINX Kubernetes Gateway is an open-source project that provides an implementation of the [Gateway API](https://gateway-api.sigs.k8s.io/) using [NGINX](https://nginx.org/) as the data plane. The goal of this project is to implement the core Gateway APIs -- `Gateway`, `GatewayClass`, `HTTPRoute`, `TCPRoute`, `TLSRoute`, and `UDPRoute` -- to configure an HTTP or TCP/UDP load balancer, reverse-proxy, or API gateway for applications running on Kubernetes. NGINX Kubernetes Gateway is currently under development and supports a subset of the Gateway API.
+NGINX Kubernetes Gateway is an open-source project that provides an implementation of
+the [Gateway API](https://gateway-api.sigs.k8s.io/) using [NGINX](https://nginx.org/) as the data plane. The goal of
+this project is to implement the core Gateway APIs -- `Gateway`, `GatewayClass`, `HTTPRoute`, `TCPRoute`, `TLSRoute`,
+and `UDPRoute` -- to configure an HTTP or TCP/UDP load balancer, reverse-proxy, or API gateway for applications running
+on Kubernetes. NGINX Kubernetes Gateway is currently under development and supports a subset of the Gateway API.
 
-For a list of supported Gateway API resources and features, see the [Gateway API Compatibility](docs/gateway-api-compatibility.md) doc.
+For a list of supported Gateway API resources and features, see
+the [Gateway API Compatibility](docs/gateway-api-compatibility.md) doc.
 
-> Warning: This project is actively in development (beta feature state) and should not be deployed in a production environment.
-> All APIs, SDKs, designs, and packages are subject to change.
+> Warning: This project is actively in development (beta feature state) and should not be deployed in a
+> production environment. All APIs, SDKs, designs, and packages are subject to change.
 
 Learn about our [design principles](/docs/developer/design-principles.md) and [architecture](/docs/architecture.md).
 
 ## Getting Started
 
 1. [Quick Start on a kind cluster](docs/running-on-kind.md).
 2. [Install](docs/installation.md) NGINX Kubernetes Gateway.
-3. [Build](docs/building-the-image.md) an NGINX Kubernetes Gateway container image from source or use a pre-built image available on [GitHub Container Registry](https://github.com/nginxinc/nginx-kubernetes-gateway/pkgs/container/nginx-kubernetes-gateway).
+3. [Build](docs/building-the-image.md) an NGINX Kubernetes Gateway container image from source or use a pre-built image
+   available
+   on [GitHub Container Registry](https://github.com/nginxinc/nginx-kubernetes-gateway/pkgs/container/nginx-kubernetes-gateway).
 4. Deploy various [examples](examples).
 
 ## NGINX Kubernetes Gateway Releases
 
-We publish NGINX Kubernetes Gateway releases on GitHub. See our [releases page](https://github.com/nginxinc/nginx-kubernetes-gateway/releases).
+We publish NGINX Kubernetes Gateway releases on GitHub. See
+our [releases page](https://github.com/nginxinc/nginx-kubernetes-gateway/releases).
 
 The latest release is [0.5.0](https://github.com/nginxinc/nginx-kubernetes-gateway/releases/tag/v0.5.0).
 
-The edge version is useful for experimenting with new features that are not yet published in a release. To use, choose the *edge* version built from the [latest commit](https://github.com/nginxinc/nginx-kubernetes-gateway/commits/main) from the main branch.
+The edge version is useful for experimenting with new features that are not yet published in a release. To use, choose
+the *edge* version built from the [latest commit](https://github.com/nginxinc/nginx-kubernetes-gateway/commits/main)
+from the main branch.
 
 To use NGINX Kubernetes Gateway, you need to have access to:
-* An NGINX Kubernetes Gateway image.
-* Installation manifests.
-* Documentation and examples.
+
+- An NGINX Kubernetes Gateway image.
+- Installation manifests.
+- Documentation and examples.
 
 It is important that the versions of those things above match.
 
-The table below summarizes the options regarding the images, manifests, documentation and examples and gives your links to the correct versions:
+The table below summarizes the options regarding the images, manifests, documentation and examples and gives your links
+to the correct versions:
 
-| Version | Description | Image | Installation Manifests | Documentation and Examples |
-|-|-|-|-|-|
-| Latest release | For experimental use | Use the 0.5.0 image from [GitHub](https://github.com/nginxinc/nginx-kubernetes-gateway/pkgs/container/nginx-kubernetes-gateway) | [Manifests](https://github.com/nginxinc/nginx-kubernetes-gateway/tree/v0.5.0/deploy). | [Documentation](https://github.com/nginxinc/nginx-kubernetes-gateway/tree/v0.5.0/docs). [Examples](https://github.com/nginxinc/nginx-kubernetes-gateway/tree/v0.5.0/examples). |
-| Edge| For experimental use and latest features | Use the edge image from [GitHub](https://github.com/nginxinc/nginx-kubernetes-gateway/pkgs/container/nginx-kubernetes-gateway) | [Manifests](https://github.com/nginxinc/nginx-kubernetes-gateway/tree/main/deploy). | [Documentation](https://github.com/nginxinc/nginx-kubernetes-gateway/tree/main/docs). [Examples](https://github.com/nginxinc/nginx-kubernetes-gateway/tree/main/examples). |
+| Version        | Description                              | Image                                                                                                                                                                                                                                                                                  | Installation Manifests                                                                | Documentation and Examples                                                                                                                                                     |
+|----------------|------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Latest release | For experimental use                     | Use the 0.5.0 image from [GitHub](https://github.com/nginxinc/nginx-kubernetes-gateway/pkgs/container/nginx-kubernetes-gateway)                                                                                                                                                        | [Manifests](https://github.com/nginxinc/nginx-kubernetes-gateway/tree/v0.5.0/deploy). | [Documentation](https://github.com/nginxinc/nginx-kubernetes-gateway/tree/v0.5.0/docs). [Examples](https://github.com/nginxinc/nginx-kubernetes-gateway/tree/v0.5.0/examples). |
+| Edge           | For experimental use and latest features | Use the edge image                                                                                                                                                         from [GitHub](https://github.com/nginxinc/nginx-kubernetes-gateway/pkgs/container/nginx-kubernetes-gateway) | [Manifests](https://github.com/nginxinc/nginx-kubernetes-gateway/tree/main/deploy).   | [Documentation](https://github.com/nginxinc/nginx-kubernetes-gateway/tree/main/docs). [Examples](https://github.com/nginxinc/nginx-kubernetes-gateway/tree/main/examples).     |
 
 ## Technical Specifications
 
 The following table lists the software versions NGINX Kubernetes Gateway supports.
 
 | NGINX Kubernetes Gateway | Gateway API | Kubernetes | NGINX OSS |
-|-|-|-|-|
-| Edge | 0.7.1 | 1.21+ | 1.25.x *|
-| 0.5.0 | 0.7.1 | 1.21+ | 1.25.x *|
-| 0.4.0 | 0.7.1 | 1.21+ | 1.25.x *|
-| 0.3.0 | 0.6.2 | 1.21+ | 1.23.x *|
-| 0.2.0 | 0.5.1 | 1.21+ | 1.21.x *|
-| 0.1.0 | 0.5.0 | 1.19+ | 1.21.3 |
+|--------------------------|-------------|------------|-----------|
+| Edge                     | 0.7.1       | 1.21+      | 1.25.x *  |
+| 0.5.0                    | 0.7.1       | 1.21+      | 1.25.x *  |
+| 0.4.0                    | 0.7.1       | 1.21+      | 1.25.x *  |
+| 0.3.0                    | 0.6.2       | 1.21+      | 1.23.x *  |
+| 0.2.0                    | 0.5.1       | 1.21+      | 1.21.x *  |
+| 0.1.0                    | 0.5.0       | 1.19+      | 1.21.3    |
 
-\*the installation manifests use the minor version of NGINX container image (e.g. 1.25) and the patch version is not specified. This means that the latest available patch version is used.
+\*the installation manifests use the minor version of NGINX container image (e.g. 1.25) and the patch version is not
+specified. This means that the latest available patch version is used.
 
 ## SBOM (Software Bill of Materials)
 
 We generate SBOMs for the binaries and the Docker image.
 
 ### Binaries
 
-The SBOMs for the binaries are available in the releases page. The SBOMs are generated using [syft](https://github.com/anchore/syft) and are available in SPDX format.
+The SBOMs for the binaries are available in the releases page. The SBOMs are generated
+using [syft](https://github.com/anchore/syft) and are available in SPDX format.
 
 ### Docker Images
 
-The SBOM for the Docker image is available in the [GitHub Container](https://github.com/nginxinc/nginx-kubernetes-gateway/pkgs/container/nginx-kubernetes-gateway) repository. The SBOM is generated using [syft](https://github.com/anchore/syft) and stored as an attestation in the image manifest.
+The SBOM for the Docker image is available in
+the [GitHub Container](https://github.com/nginxinc/nginx-kubernetes-gateway/pkgs/container/nginx-kubernetes-gateway)
+repository. The SBOM is generated using [syft](https://github.com/anchore/syft) and stored as an attestation in the
+image manifest.
+
+For example to retrieve the SBOM for `linux/amd64` and analyze it using [grype](https://github.com/anchore/grype) you
+can run the following command:
 
-For example to retrieve the SBOM for `linux/amd64` and analyze it using [grype](https://github.com/anchore/grype) you can run the following command:
 ```shell
 docker buildx imagetools inspect ghcr.io/nginxinc/nginx-kubernetes-gateway:edge --format '{{ json (index .SBOM "linux/amd64").SPDX }}' | grype
 ```
@@ -76,11 +96,14 @@ docker buildx imagetools inspect ghcr.io/nginxinc/nginx-kubernetes-gateway:edge
 
 We’d like to hear your feedback! If you experience issues with our Gateway Controller, please [open a bug][bug] in
 GitHub. If you have any suggestions or enhancement requests, please [open an idea][idea] on GitHub discussions. You can
-contact us directly via [email protected] or on the [NGINX Community Slack][slack] in the `#nginx-kubernetes-gateway`
+contact us directly via [email protected] or on the [NGINX Community Slack][slack] in
+the `#nginx-kubernetes-gateway`
 channel.
 
 [bug]:https://github.com/nginxinc/nginx-kubernetes-gateway/issues/new?assignees=&labels=&projects=&template=bug_report.md&title=
+
 [idea]:https://github.com/nginxinc/nginx-kubernetes-gateway/discussions/categories/ideas
+
 [slack]: https://nginxcommunity.slack.com/channels/nginx-kubernetes-gateway
 
 ## Contributing