chore: tidy up docs (#1802)

## Description

This PR makes minor changes to debugging docs and applies some
IDE-suggested `.md` fixes.

End to End Test:  <!-- if applicable -->  
(See [Pepr Excellent
Examples](https://github.com/defenseunicorns/pepr-excellent-examples))

## Related Issue

Fixes #1776

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [x] Other (security config, docs update, etc)

## Checklist before merging
- [x] Unit,
[Journey](https://github.com/defenseunicorns/pepr/tree/main/journey),
[E2E Tests](https://github.com/defenseunicorns/pepr-excellent-examples),
[docs](https://github.com/defenseunicorns/pepr/tree/main/docs),
[adr](https://github.com/defenseunicorns/pepr/tree/main/adr) added or
updated as needed
- [x] [Contributor Guide
Steps](https://docs.pepr.dev/main/contribute/#submitting-a-pull-request)
followed

README.md

@@ -9,9 +9,10 @@
 [![codecov](https://codecov.io/github/defenseunicorns/pepr/graph/badge.svg?token=7679Y9K1HB)](https://codecov.io/github/defenseunicorns/pepr)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](code_of_conduct.md)
 
-#### **_Type safe Kubernetes middleware for humans_**
+## **_Type safe Kubernetes middleware for humans_**
 
-<img align="right" width="40%" src="_images/pepr.png" />
+<!-- markdownlint-disable MD033 - Image-styling is unsupported on GitHub-flavored markdown -->
+<img alt="The Pepr Logo" align="right" width="40%" src="_images/pepr.png" />
 
 Pepr is on a mission to save Kubernetes from the tyranny of YAML, intimidating glue code, bash scripts, and other makeshift solutions. As a Kubernetes controller, Pepr empowers you to define Kubernetes transformations using TypeScript, without software development expertise thanks to plain-english configurations. Pepr transforms a patchwork of forks, scripts, overlays, and other chaos into a cohesive, well-structured, and maintainable system. With Pepr, you can seamlessly transition IT ops organizational knowledge into code, simplifying documentation, testing, validation, and coordination of changes for a more predictable outcome.
 
@@ -89,7 +90,7 @@ When(a.ConfigMap)
   - [Visual Studio Code](https://code.visualstudio.com/) for inline debugging and [Pepr Capabilities](#capability) creation.
   - A Kubernetes cluster for `npx pepr dev`. Pepr modules include `npm run k3d-setup` if you want to test locally with [K3d](https://k3d.io/) and [Docker](https://www.docker.com/).
 
-## Wow, too many words! tl;dr;
+## Wow, too many words! tl;dr
 
 ```bash
 # Create a new Pepr Module
@@ -112,7 +113,7 @@ kubectl apply -f capabilities/hello-pepr.samples.yaml
 > local k8s distro documentation how to reach your localhost, which is where
 > `pepr dev` is serving the code from.
 
-https://user-images.githubusercontent.com/882485/230895880-c5623077-f811-4870-bb9f-9bb8e5edc118.mp4
+<https://user-images.githubusercontent.com/882485/230895880-c5623077-f811-4870-bb9f-9bb8e5edc118.mp4>
 
 ## Concepts
 
@@ -151,8 +152,7 @@ See [actions](./docs/030_user-guide/030_actions/README.md) for more details.
 
 To join our channel go to [Kubernetes Slack](https://communityinviter.com/apps/kubernetes/community) and join the `#pepr` channel.
 
-<a href="https://github.com/defenseunicorns/pepr/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=defenseunicorns/pepr" />
-</a>
+[contributors]: https://contrib.rocks/image?repo=defenseunicorns/pepr
+[![Contributor Chart][contributors]](https://github.com/defenseunicorns/pepr/graphs/contributors)
 
 Made with [contrib.rocks](https://contrib.rocks).

docs/030_user-guide/010_pepr-cli.md

@@ -30,6 +30,7 @@ Update the current Pepr Module to the latest SDK version. This command is not re
 Connect a local cluster to a local version of the Pepr Controller to do real-time debugging of your module. Note the `npx pepr dev` assumes a K3d cluster is running by default. If you are working with Kind or another docker-based K8s distro, you will need to pass the `--host host.docker.internal` option to `npx pepr dev`. If working with a remote cluster you will have to give Pepr a host path to your machine that is reachable from the K8s cluster.
 
 NOTE: This command, by necessity, installs resources into the cluster you run it against.  Generally, these resources are removed once the `pepr dev` session ends but there are two notable exceptions:
+
 - the `pepr-system` namespace, and
 - the `PeprStore` CRD.
 
@@ -100,7 +101,7 @@ Create a [zarf.yaml](https://zarf.dev) and K8s manifest for the current module.
 - `-i, --custom-image [custom-image]` - Specify a custom image (including version) for Admission and Watch Deployments. Example: 'docker.io/username/custom-pepr-controller:v1.0.0'
 - `--registry [GitHub, Iron Bank]` - Container registry: Choose container registry for deployment manifests.
 - `-v, --version <version>. Example: '0.27.3'` - DEPRECATED: The version of the Pepr image to use in the deployment manifests.
--  `--withPullSecret <imagePullSecret>` - Image Pull Secret: Use image pull secret for controller Deployment.
+- `--withPullSecret <imagePullSecret>` - Image Pull Secret: Use image pull secret for controller Deployment.
 - `-z, --zarf [manifest|chart]` - The Zarf package type to generate: manifest or chart (default: manifest).
 
 ## `npx pepr kfc`

docs/030_user-guide/015_sdk.md

@@ -50,7 +50,7 @@ let result = containers(peprValidationRequest, "ephemeralContainers")
 Returns the owner reference for a Kubernetes resource as an array. Accepts the following parameters:
 
 - **@param kubernetesResource: GenericKind** The Kubernetes resource to get the owner reference for
-- **@param blockOwnerDeletion: boolean** If true, AND if the owner has the "foregroundDeletion" finalizer, then the owner cannot be deleted from the key-value store until this reference is removed. 
+- **@param blockOwnerDeletion: boolean** If true, AND if the owner has the "foregroundDeletion" finalizer, then the owner cannot be deleted from the key-value store until this reference is removed.
 - **@param controller: boolean** If true, this reference points to the managing controller.
 
 **Usage:**
@@ -69,10 +69,10 @@ Write a K8s event for a CRD. Accepts the following parameters:
 - **@param kubernetesResource: GenericKind** The Kubernetes resource to write the event for
 - **@param event** The event to write, should contain a human-readable message for the event
 - **@param options** Configuration options for the event.
-	-	eventType: string – The type of event to write, for example "Warning"
-	-	eventReason: string – The reason for the event, for example "ReconciliationFailed"
-	-	reportingComponent: string – The component that is reporting the event, for example "uds.dev/operator"
-	-	reportingInstance: string – The instance of the component that is reporting the event, for example process.env.HOSTNAME
+  - eventType: string – The type of event to write, for example "Warning"
+  - eventReason: string – The reason for the event, for example "ReconciliationFailed"
+  - reportingComponent: string – The component that is reporting the event, for example "uds.dev/operator"
+  - reportingInstance: string – The instance of the component that is reporting the event, for example process.env.HOSTNAME
 
 **Usage:**
 

docs/030_user-guide/080_onschedule.md

@@ -2,7 +2,6 @@
 
 The `OnSchedule` feature allows you to schedule and automate the execution of specific code at predefined intervals or schedules. This feature is designed to simplify recurring tasks and can serve as an alternative to traditional CronJobs. This code is designed to be run at the top level on a Capability, not within a function like `When`.
 
-
 ## Best Practices
 
 `OnSchedule` is designed for targeting intervals equal to or larger than 30 seconds due to the storage mechanism used to archive schedule info.

docs/030_user-guide/100_metrics.md

@@ -17,7 +17,6 @@ The `MetricsCollector` exposes the following metrics:
 
 | `PEPR_MAX_CACHE_MISS_WINDOWS` | Maximum number windows to emit `pepr_cache_miss` metrics for  | default: `Undefined`  |
 
-
 ## API Details
 
 **Method:** GET

docs/030_user-guide/130_filters.md

@@ -20,16 +20,16 @@ When(a.ConfigMap)
   });
 ```
 
-
 ## `Filters`
 
 - `.WithName("name")`: Filters resources by name.
 - `.WithNameRegex(/^pepr/)`: Filters resources by name using a regex.
 - `.InNamespace("namespace")`: Filters resources by namespace.
 - `.InNamespaceRegex(/(.*)-system/)`: Filters resources by namespace using a regex.
 - `.WithLabel("key", "value")`: Filters resources by label. (Can be multiple)
-- `.WithDeletionTimestamp()`: Filters resources that have a deletion timestamp. 
+- `.WithDeletionTimestamp()`: Filters resources that have a deletion timestamp.
+
+Notes:
 
-Notes: 
-- `WithDeletionTimestamp()` is does not work on Delete through the `Mutate` or `Validate` methods because the Kubernetes Admission Process does not fire the DELETE event with a deletion timestamp on the resource. 
+- `WithDeletionTimestamp()` is does not work on Delete through the `Mutate` or `Validate` methods because the Kubernetes Admission Process does not fire the DELETE event with a deletion timestamp on the resource.
 - `WithDeletionTimestamp()` _will_ match on an Update event during Admission (`Mutate` or `Validate`) when pending-deletion permitted changes (like removing a finalizer) occur.

docs/040_pepr-tutorials/020_create-pepr-dashboard.md

@@ -33,7 +33,6 @@ kubectl apply -f capabilities/hello-pepr.samples.yaml
 npx pepr deploy
 ```
 
-
 ### Step 2: Create and Apply Our Pepr Dashboard to the Cluster
 
 Create a new file called grafana-dashboard.yaml and add the following content:
@@ -842,7 +841,7 @@ The targets should look something like this:
 
 You should be able to test the Prometheus connection in the Grafana UI by visiting the following URL:
 
-http://localhost:3000/connections/datasources
+<http://localhost:3000/connections/datasources>
 
 The login information for Grafana was set in the values.yaml file:
 
@@ -853,7 +852,7 @@ By clicking on the Prometheus data source, you should be able to test the connec
 
 NOTE: The Prometheus server URL should be something like:
 
-http://monitoring-kube-prometh-prometheus.default:9090/
+<http://monitoring-kube-prometh-prometheus.default:9090/>
 
 You should now be able to select the Pepr Dashboard from the Grafana UI in the "Dashboards" section.
 

docs/040_pepr-tutorials/030_create-pepr-operator.md

@@ -6,21 +6,20 @@ This tutorial will walk you through the process of building a Kubernetes Operato
 
 ## Background
 
-
 The WebApp Operator deploys the WebApp `CustomResourceDefinition`, then watches and reconciles against instances of WebApps to ensure the desired state meets the actual cluster state.
 
 The WebApp instance represents a `Deployment` object with configurable replicas, a `Service`, and a `ConfigMap` that has a `index.html` file that can be configured to a specific language, and theme. The resources the Operator deploys contain `ownerReferences`, causing a cascading delete effect when the WebApp instance is deleted.
 
-If any object deployed by the Operator is deleted for any reason, the Operator will abruptly redeploy the object. 
+If any object deployed by the Operator is deleted for any reason, the Operator will abruptly redeploy the object.
 
 ## Steps
 
 - [Create a new Pepr Module](#create-a-new-pepr-module)
 - [Create CRD](#create-crd)
 - [Create Helpers](#create-helpers)
-- [Create Reconciler](#create-reconciler) 
-- [Build and Deploy](#build-and-deploy)
- 
+- [Create Reconciler](#create-reconciler)
+- [Build and Deploy](#demo)
+
 ## Create a new Pepr Module
 
 ```bash
@@ -745,7 +744,7 @@ When(a.CustomResourceDefinition)
     RegisterCRD();
   });
 
-// // Don't let them be deleted
+// Don't let them be deleted
 When(a.Deployment)
   .IsDeleted()
   .WithLabel("pepr.dev/operator")
@@ -775,6 +774,7 @@ When(a.ConfigMap)
   });
 
 ```
+
 - When a WebApp is created or updated, validate it, store the name of the instance and enqueue it for processing.
 - If an "owned" resource (ConfigMap, Service, or Deployment) is deleted, redeploy it.
 - Always redeploy the WebApp CRD if it was deleted as the controller depends on it
@@ -783,7 +783,7 @@ In this section we created a `reconciler.ts` file that contains the function tha
 
 ## Demo
 
-_Create an ephemeral cluster. (Kind or k3d will work)_
+Create an ephemeral cluster (Kind or k3d will work).
 
 Clone the Operator
 
@@ -804,7 +804,7 @@ Build the Pepr manifests (Already built with appropriate RBAC)
 npx pepr build
 ```
 
-Deploy the Operator 
+Deploy the Operator
 
 ```bash
 kubectl apply -f dist/pepr-module-774fab07-77fa-517c-b5f8-c682c96c20c0.yaml
@@ -919,6 +919,7 @@ Port-forward and look at the WebApp in the browser
 ```bash
 kubectl port-forward svc/webapp-light-en -n webapps 3000:80
 ```
+
 [WebApp](http://localhost:3000)
 ![WebApp](light.png)
 
@@ -960,6 +961,7 @@ Port-forward and look at the WebApp in the browser
 ```bash
 kubectl port-forward svc/webapp-light-en -n webapps 3000:80
 ```
+
 [WebApp](http://localhost:3000)
 
 ![WebApp](dark.png)
@@ -977,7 +979,6 @@ configmap/kube-root-ca.crt   1      40s
 
 When the WebApp is deleted, all of the resources that it created are also deleted.
 
-
 ## Conclusion
 
 In this tutorial we created a Kubernetes Operator using Pepr. We created a CRD, created helper functions to help with the reconciliation process, and created a queue and reconciler to reconcile the state of the instance with the cluster. We also built and deployed the Operator and created an instance of the WebApp resource and watched the Operator reconcile the state of the instance with the cluster. Finally, we updated and deleted the instance and watched the Operator reconcile the manifests based in the updated instance and delete the resources when the instance was deleted.