Fix docs to make copying commands easier (#859)

Problem: Commands and their output were saved in the same block, making it difficult for users to simply copy the commands.

Solution: Separate commands and their output into separate blocks in the documentation.

Author: sjberman

README.md

@@ -67,8 +67,8 @@ The SBOMs for the binaries are available in the releases page. The SBOMs are gen
 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:
-```
-$ docker buildx imagetools inspect ghcr.io/nginxinc/nginx-kubernetes-gateway:edge --format '{{ json (index .SBOM "linux/amd64").SPDX }}' | grype
+```shell
+docker buildx imagetools inspect ghcr.io/nginxinc/nginx-kubernetes-gateway:edge --format '{{ json (index .SBOM "linux/amd64").SPDX }}' | grype
 ```
 
 ## Contacts

conformance/README.md

@@ -11,9 +11,11 @@
 
 List available commands:
 
-```bash
-$ make
+```shell
+make
+```
 
+```
 build-nkg-image                Build NKG container and load it and NGINX container on configured kind cluster
 build-test-runner-image        Build conformance test runner image
 cleanup-conformance-tests      Clean up conformance tests fixtures
@@ -50,18 +52,18 @@ update-nkg-manifest            Update the NKG deployment manifest image name and
 
 ### Step 1 - Create a kind Cluster
 
-```bash
-$ make create-kind-cluster
+```makefile
+make create-kind-cluster
 ```
 ### Step 2 - Install Nginx Kubernetes Gateway to configured kind cluster
 
 #### *Option 1* Build and install Nginx Kubernetes Gateway from local to configured kind cluster
-```bash
-$ make install-nkg-local-build
+```makefile
+make install-nkg-local-build
 ```
 #### *Option 2* Install Nginx Kubernetes Gateway from local already built image to configured kind cluster
-```bash
-$ make install-nkg-local-no-build
+```makefile
+make install-nkg-local-no-build
 ```
 **Note:** You can optionally skip the actual *build* step. However, if choosing 
 this option, the following step *must* be completed manually *before* the build step:
@@ -80,34 +82,36 @@ this option, the following step *must* be completed manually *before* the build
 #### *Option 3* Install Nginx Kubernetes Gateway from edge to configured kind cluster
 You can also skip the build NKG image step and prepare the environment to instead use the `edge` image
 
-```bash
-$ make install-nkg-edge
+```makefile
+make install-nkg-edge
 ```
 
 ### Step 3 - Build conformance test runner image
-```bash
-$ make build-test-runner-image
+```makefile
+make build-test-runner-image
 ```
 
 ### Step 4 - Run Gateway conformance tests
-```bash
-$ make run-conformance-tests
+```makefile
+make run-conformance-tests
 ```
 
 ### Step 5 - Cleanup the conformance test fixtures and uninstall Nginx Kubernetes Gateway
-```bash
-$ make cleanup-conformance-tests
-$ make uninstall-nkg
+```makefile
+make cleanup-conformance-tests
+```
+```makefile
+make uninstall-nkg
 ```
 
 ### Step 6 - Revert changes to the NKG deployment manifest
 **Optional** Not required if using `edge` image
 **Warning**: `make undo-image-update` will hard reset changes to the deploy/manifests/deployment.yaml file!
-```bash
-$ make undo-image-update
+```makefile
+make undo-image-update
 ```
 
 ### Step 7 - Delete kind cluster
-```bash
-$ make delete-kind-cluster
+```makefile
+make delete-kind-cluster
 ```

conformance/provisioner/provisioner.md renamed to conformance/provisioner/README.md

@@ -28,12 +28,14 @@ How to deploy:
 1. Follow the [installation](/docs/installation.md) instructions up until the Deploy the NGINX Kubernetes Gateway Step
    to deploy prerequisites for both the static mode Deployments and the provisioner.
 1. Deploy provisioner:
-   ```
+   ```shell
    kubectl apply -f conformance/provisioner/provisioner.yaml
    ```
 1. Confirm the provisioner is running in nginx-gateway namespace:
-   ```
+   ```shell
    kubectl get pods -n nginx-gateway 
+   ```
+   ```console
    NAME                                         READY   STATUS    RESTARTS   AGE
    nginx-gateway-provisioner-6c9d9fdcb8-b2pf8   1/1     Running   0          11m
    ```

design/control-data-plane-separation/design.md

@@ -748,7 +748,7 @@ configurations, we can work with them to add bigger config files to the test sui
 
 Config Push Benchmarks:
 
-```bash
+```shell
 cpu: Intel(R) Xeon(R) Platinum 8370C CPU @ 2.80GHz
 BenchmarkNginxConfig/../testdata/configs/bigger/1k.conf-2         	1000000000	         0.005241 ns/op	       0 B/op	       0 allocs/op
 BenchmarkNginxConfig/../testdata/configs/bigger/2k.conf-2         	1000000000	         0.01087 ns/op	       0 B/op	       0 allocs/op
@@ -762,7 +762,7 @@ BenchmarkGetConfigFiles/GetConfigFiles#03-2                       	1000000000
 
 Config Zip and Unzip Benchmarks:
 
-```bash
+```shell
 BenchmarkZipConfig/Zip_config../testdata/configs/bigger/1k.conf-2            	1000000000	         0.0001852 ns/op	       0 B/op	       0 allocs/op
 BenchmarkZipConfig/Zip_config../testdata/configs/bigger/2k.conf-2            	1000000000	         0.0000663 ns/op	       0 B/op	       0 allocs/op
 BenchmarkZipConfig/Zip_config../testdata/configs/bigger/3k.conf-2            	1000000000	         0.0000674 ns/op	       0 B/op	       0 allocs/op

docs/building-the-image.md

@@ -11,22 +11,22 @@ Before you can build the NGINX Kubernetes Gateway, make sure you have the follow
 
 1. Clone the repo and change into the `nginx-kubernetes-gateway` directory:
 
-   ```
+   ```shell
    git clone https://github.com/nginxinc/nginx-kubernetes-gateway.git
    cd nginx-kubernetes-gateway
    ```
 
 1. Build the image:
 
-   ```
+   ```makefile
    make PREFIX=myregistry.example.com/nginx-kubernetes-gateway container
    ```
 
    Set the `PREFIX` variable to the name of the registry you'd like to push the image to. By default, the image will be named `nginx-kubernetes-gateway:edge`.
 
 1. Push the image to your container registry:
 
-   ```
+   ```shell
    docker push myregistry.example.com/nginx-kubernetes-gateway:edge
    ```
 

docs/developer/quickstart.md

@@ -27,6 +27,8 @@ Follow these steps to set up your development environment.
    ```shell
    git clone https://github.com/<YOUR-USERNAME>/nginx-kubernetes-gateway.git
    cd nginx-kubernetes-gateway
+   ```
+   ```makefile
    make deps
    ```
 
@@ -36,7 +38,7 @@ Follow these steps to set up your development environment.
 
 To build the binary, run the make build command from the project's root directory:
 
-```shell
+```makefile
 make build
 ```
 
@@ -46,7 +48,7 @@ This command will build the binary and output it to the `/build/.out` directory.
 
 To build an NGINX Kubernetes Gateway container image from source run the following make command:
 
-```shell
+```makefile
 make TAG=$(whoami) container
 ```
 
@@ -56,7 +58,7 @@ This will build the docker image `nginx-kubernetes-gateway:<your-user>`.
 
 1. Create a `kind` cluster:
 
-   ```shell
+   ```makefile
    make create-kind-cluster
    ```
 
@@ -87,7 +89,7 @@ To make sure NKG is running properly, try out the [examples](/examples).
 
 To run all the unit tests, run the make unit-test command from the project's root directory:
 
-```shell
+```makefile
 make unit-test
 ```
 
@@ -101,7 +103,7 @@ To run Gateway API conformance tests, please follow the instructions on [this](/
 
 To lint the code, run the following make command from the project's root directory:
 
-```shell
+```makefile
 make lint
 ```
 

docs/developer/testing.md

@@ -44,7 +44,7 @@ promoting efficient refactoring and continuous development.
 
 To run the unit tests, run the make unit-test command from the project's root directory:
 
-```shell
+```makefile
 make unit-test
 ```
 

docs/installation.md

@@ -12,57 +12,61 @@ This guide walks you through how to install NGINX Kubernetes Gateway on a generi
 
 1. Clone the repo and change into the `nginx-kubernetes-gateway` directory:
 
-   ```
+   ```shell
    git clone https://github.com/nginxinc/nginx-kubernetes-gateway.git
+   ```
+   ```shell
    cd nginx-kubernetes-gateway
    ```
 
 1. Install the Gateway API resources from the standard channel (the CRDs and the validating webhook):
 
-   ```
+   ```shell
    kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v0.7.1/standard-install.yaml
    ```
 
 1. Create the nginx-gateway Namespace:
 
-    ```
+    ```shell
     kubectl apply -f deploy/manifests/namespace.yaml
     ```
 
 1. Create the njs-modules ConfigMap:
 
-    ```
+    ```shell
     kubectl create configmap njs-modules --from-file=internal/mode/static/nginx/modules/src/httpmatches.js -n nginx-gateway
     ```
 
 1. Create the ConfigMap with the main NGINX configuration file:
 
-    ```
+    ```shell
     kubectl apply -f deploy/manifests/nginx-conf.yaml
     ```
 
 1. Configure RBAC:
 
-    ```
+    ```shell
     kubectl apply -f deploy/manifests/rbac.yaml
     ```
 
 1. Create the GatewayClass resource:
 
-    ```
+    ```shell
     kubectl apply -f deploy/manifests/gatewayclass.yaml
     ```
 
 1. Deploy the NGINX Kubernetes Gateway:
 
-   ```
+   ```shell
    kubectl apply -f deploy/manifests/deployment.yaml
    ```
 
 1. Confirm the NGINX Kubernetes Gateway is running in `nginx-gateway` namespace:
 
-   ```
+   ```shell
    kubectl get pods -n nginx-gateway
+   ```
+   ```console
    NAME                             READY   STATUS    RESTARTS   AGE
    nginx-gateway-5d4f4c7db7-xk2kq   2/2     Running   0          112s
    ```
@@ -80,7 +84,7 @@ You can gain access to NGINX Kubernetes Gateway by creating a `NodePort` Service
 
 Create a Service with type `NodePort`:
 
-```
+```shell
 kubectl apply -f deploy/manifests/service/nodeport.yaml
 ```
 
@@ -92,33 +96,33 @@ Create a Service with type `LoadBalancer` using the appropriate manifest for you
 
 - For GCP or Azure:
 
-   ```
+   ```shell
    kubectl apply -f deploy/manifests/service/loadbalancer.yaml
    ```
 
    Lookup the public IP of the load balancer, which is reported in the `EXTERNAL-IP` column in the output of the following command:
 
-   ```
+   ```shell
    kubectl get svc nginx-gateway -n nginx-gateway
    ```
 
    Use the public IP of the load balancer to access NGINX Kubernetes Gateway.
 
 - For AWS:
 
-   ```
+   ```shell
    kubectl apply -f deploy/manifests/service/loadbalancer-aws-nlb.yaml
    ```
 
    In AWS, the NLB DNS name will be reported by Kubernetes in lieu of a public IP in the `EXTERNAL-IP` column. To get the DNS name run:
 
-   ```
+   ```shell
    kubectl get svc nginx-gateway -n nginx-gateway
    ```
 
    In general, you should rely on the NLB DNS name, however for testing purposes you can resolve the DNS name to get the IP address of the load balancer:
 
-   ```
+   ```shell
    nslookup <dns-name>
    ```
 

docs/resource-validation.md

@@ -52,8 +52,10 @@ The Kubernetes API server validates Gateway API resources against the OpenAPI sc
 For example, if you create an HTTPRoute with an invalid hostname `cafe.!@#$%example.com`, the API server will reject it
 with the following error:
 
-```
+```shell
 kubectl apply -f coffee-route.yaml 
+```
+```
 The HTTPRoute "coffee" is invalid: spec.hostnames[0]: Invalid value: "cafe.!@#$%example.com": spec.hostnames[0] in body should match '^(\*\.)?[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$'
 ```
 
@@ -67,8 +69,10 @@ It validates Gateway API resources using advanced rules unavailable in the OpenA
 you create a Gateway resource with a TCP listener that configures a hostname, the webhook will reject it with the
 following error:
 
-```
+```shell
 kubectl apply -f prod-gateway.yaml 
+```
+```
 Error from server: error when creating "prod-gateway.yaml": admission webhook "validate.gateway.networking.k8s.io" denied the request: spec.listeners[1].hostname: Forbidden: should be empty for protocol TCP
 ```
 
@@ -84,8 +88,10 @@ performs the validation *after* the Kubernetes API server accepts the resource.
 Below is an example of how NKG rejects an invalid resource (a Gateway resource with a TCP listener that configures a
 hostname) with a Kubernetes event:
 
-```
+```shell
 kubectl describe gateway prod-gateway
+```
+```
 . . .
 Events:
   Type     Reason    Age   From                            Message
@@ -114,8 +120,10 @@ This step catches the following cases of invalid values:
 
 Below is an example of how NGK rejects an invalid resource. The validation error is reported via the status:
 
-```
+```shell
 kubectl describe httproutes.gateway.networking.k8s.io coffee
+```
+```
 . . .
 Status:
   Parents: