Setup mdox

Signed-off-by: Saswata Mukherjee <saswataminsta@yahoo.com>

.github/workflows/checks.yaml

@@ -25,16 +25,15 @@ jobs:
       with:
         go-version: ${{ env.golang-version }}
     - run: make --always-make format generate && git diff --exit-code
-  check-links:
+  check-docs:
     runs-on: ubuntu-latest
-    name: Check markdown links
+    name: Check Documentation formatting and links
     steps:
     - uses: actions/checkout@v2
-    - uses: gaurav-nelson/github-action-markdown-link-check@v1
+    - uses: actions/setup-go@v2
       with:
-        use-quiet-mode: 'yes'
-        config-file: '.github/workflows/.mlc_config.json'
-      continue-on-error: true
+        go-version: ${{ env.golang-version }}
+    - run: make check-docs
   check-golang:
     runs-on: ubuntu-latest
     name: Golang linter

.mdox.validate.yaml

@@ -0,0 +1,15 @@
+version: 1
+
+validators:
+  # Cloudflare protection, so returns 503 if not in browser. Cannot curl as well.
+  - regex: 'wise\.com'
+    type: "ignore"
+  # Adopters example link.
+  - regex: "our-link"
+    type: "ignore"
+  # 301 errors even when curl-ed.
+  - regex: "envoyproxy"
+    type: "ignore"
+  # Ignore release links.
+  - regex: 'https:\/\/github\.com\/prometheus-operator\/prometheus-operator\/releases'
+    type: "ignore"

Documentation/network-policies.md

@@ -51,8 +51,7 @@ networkpolicy "prometheus" configured
 * Allow inbound tcp dst port 9093 from any source to alertmanager
 * Allow inbound tcp & udp dst port 9094 from only alertmanager to alertmanager
 
-[embedmd]:# (../example/networkpolicies/alertmanager.yaml)
-```yaml
+```yaml mdox-exec="cat example/networkpolicies/alertmanager.yaml"
 apiVersion: networking.k8s.io/v1
 kind: NetworkPolicy
 metadata:
@@ -101,8 +100,7 @@ spec:
 
 * Allow inbound tcp dst port 3000 from any source to grafana
 
-[embedmd]:# (../example/networkpolicies/grafana.yaml)
-```yaml
+```yaml mdox-exec="cat example/networkpolicies/grafana.yaml"
 apiVersion: networking.k8s.io/v1
 kind: NetworkPolicy
 metadata:
@@ -121,8 +119,7 @@ spec:
 
 * Allow inbound tcp dst port 9090 from any source to prometheus
 
-[embedmd]:# (../example/networkpolicies/prometheus.yaml)
-```yaml
+```yaml mdox-exec="cat example/networkpolicies/prometheus.yaml"
 apiVersion: networking.k8s.io/v1
 kind: NetworkPolicy
 metadata:
@@ -142,8 +139,7 @@ spec:
 
 * Allow inbound tcp dst port 9100 from only prometheus to node-exporter
 
-[embedmd]:# (../example/networkpolicies/node-exporter.yaml)
-```yaml
+```yaml mdox-exec="cat example/networkpolicies/node-exporter.yaml"
 apiVersion: networking.k8s.io/v1
 kind: NetworkPolicy
 metadata:
@@ -173,8 +169,7 @@ spec:
 
 * Allow inbound tcp dst port 8080 from only prometheus to kube-state-metrics
 
-[embedmd]:# (../example/networkpolicies/kube-state-metrics.yaml)
-```yaml
+```yaml mdox-exec="cat example/networkpolicies/kube-state-metrics.yaml"
 apiVersion: networking.k8s.io/v1
 kind: NetworkPolicy
 metadata:

Documentation/rbac-crd.md

@@ -28,8 +28,7 @@ This grants:
 - Users with `view` role permissions to view the Prometheus Operator CRDs within their namespaces,
 - Users with `edit` and `admin` roles permissions to create, edit and delete Prometheus Operator CRDs within their namespaces.
 
-[embedmd]:# (../example/rbac/prometheus-operator-crd/prometheus-operator-crd-cluster-roles.yaml)
-```yaml
+```yaml mdox-exec="cat example/rbac/prometheus-operator-crd/prometheus-operator-crd-cluster-roles.yaml"
 kind: ClusterRole
 apiVersion: rbac.authorization.k8s.io/v1
 metadata:

Documentation/rbac.md

@@ -20,8 +20,7 @@ In order for the Prometheus Operator to work in an RBAC based authorization envi
 
 Here is a ready to use manifest of a `ClusterRole` that can be used to start the Prometheus Operator:
 
-[embedmd]:# (../example/rbac/prometheus-operator/prometheus-operator-cluster-role.yaml)
-```yaml
+```yaml mdox-exec="cat example/rbac/prometheus-operator/prometheus-operator-cluster-role.yaml"
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
 metadata:
@@ -133,8 +132,7 @@ As Prometheus does not modify any Objects in the Kubernetes API, but just reads
 
 In addition to the resources Prometheus itself needs to access, the Prometheus side-car needs to be able to `get` configmaps to be able to pull in rule files from configmap objects.
 
-[embedmd]:# (../example/rbac/prometheus/prometheus-cluster-role.yaml)
-```yaml
+```yaml mdox-exec="cat example/rbac/prometheus/prometheus-cluster-role.yaml"
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
 metadata:
@@ -169,8 +167,7 @@ To demonstrate how to use a `ClusterRole` with a `ClusterRoleBinding` and a `Ser
 
 Say the Prometheus Operator shall be deployed in the `default` namespace. First a `ServiceAccount` needs to be setup.
 
-[embedmd]:# (../example/rbac/prometheus-operator/prometheus-operator-service-account.yaml)
-```yaml
+```yaml mdox-exec="cat example/rbac/prometheus-operator/prometheus-operator-service-account.yaml"
 apiVersion: v1
 kind: ServiceAccount
 metadata:
@@ -186,8 +183,7 @@ Note that the `ServiceAccountName` also has to actually be used in the `PodTempl
 
 And then a `ClusterRoleBinding`:
 
-[embedmd]:# (../example/rbac/prometheus-operator/prometheus-operator-cluster-role-binding.yaml)
-```yaml
+```yaml mdox-exec="cat example/rbac/prometheus-operator/prometheus-operator-cluster-role-binding.yaml"
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRoleBinding
 metadata:
@@ -210,8 +206,7 @@ Because the `Pod` that the Prometheus Operator is running in uses the `ServiceAc
 
 When creating `Prometheus` objects the procedure is similar. It starts with a `ServiceAccount`.
 
-[embedmd]:# (../example/rbac/prometheus/prometheus-service-account.yaml)
-```yaml
+```yaml mdox-exec="cat example/rbac/prometheus/prometheus-service-account.yaml"
 apiVersion: v1
 kind: ServiceAccount
 metadata:
@@ -220,8 +215,7 @@ metadata:
 
 And then because the `ClusterRole` named `prometheus`, as described above, is likely to be used multiple times, a `ClusterRoleBinding` instead of a `RoleBinding` is used.
 
-[embedmd]:# (../example/rbac/prometheus/prometheus-cluster-role-binding.yaml)
-```yaml
+```yaml mdox-exec="cat example/rbac/prometheus/prometheus-cluster-role-binding.yaml"
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRoleBinding
 metadata:

Documentation/user-guides/alerting.md

@@ -21,8 +21,7 @@ The Prometheus Operator also introduces an AlertmanagerConfig resource, which al
 
 First, create an example Alertmanager cluster, with three instances.
 
-[embedmd]:# (../../example/user-guides/alerting/alertmanager-example.yaml)
-```yaml
+```yaml mdox-exec="cat example/user-guides/alerting/alertmanager-example.yaml"
 apiVersion: monitoring.coreos.com/v1
 kind: Alertmanager
 metadata:
@@ -39,8 +38,7 @@ For more information on configuring Alertmanager, see the Prometheus [Alerting C
 
 The following example configuration creates an AlertmanagerConfig resource that sends notifications to a non-existent `wechat` receiver:
 
-[embedmd]:# (../../example/user-guides/alerting/alertmanager-config-example.yaml)
-```yaml
+```yaml mdox-exec="cat example/user-guides/alerting/alertmanager-config-example.yaml"
 apiVersion: monitoring.coreos.com/v1alpha1
 kind: AlertmanagerConfig
 metadata:
@@ -81,8 +79,7 @@ $ kubectl create -f alertmanager-config.yaml
 
 The `alertmanagerConfigSelector` field in the Alertmanager resource Spec needs to be specified so that the operator can select such AlertmanagerConfig resources. In the previous example, the label `alertmanagerConfig: example` is added, so the Alertmanager instance should be updated, adding the `alertmanagerConfigSelector`:
 
-[embedmd]:# (../../example/user-guides/alerting/alertmanager-selector-example.yaml)
-```yaml
+```yaml mdox-exec="cat example/user-guides/alerting/alertmanager-selector-example.yaml"
 apiVersion: monitoring.coreos.com/v1
 kind: Alertmanager
 metadata:
@@ -98,8 +95,7 @@ spec:
 
 The following example configuration sends notifications against to a `webhook`:
 
-[embedmd]:# (../../example/user-guides/alerting/alertmanager.yaml)
-```yaml
+```yaml mdox-exec="cat example/user-guides/alerting/alertmanager.yaml"
 global:
   resolve_timeout: 5m
 route:
@@ -150,8 +146,7 @@ Once the operator merges the optional manually specified Secret with any selecte
 
 To be able to view the web UI, expose it through a Service. A simple way to do this is to use a Service of type `NodePort`.
 
-[embedmd]:# (../../example/user-guides/alerting/alertmanager-example-service.yaml)
-```yaml
+```yaml mdox-exec="cat example/user-guides/alerting/alertmanager-example-service.yaml"
 apiVersion: v1
 kind: Service
 metadata:
@@ -174,8 +169,7 @@ Once created it allows the web UI to be accessible via a Node's IP and the port
 
 This Alertmanager cluster is now fully functional and highly available, but no alerts are fired against it. Create  Prometheus instances to fire alerts to the Alertmanagers.
 
-[embedmd]:# (../../example/user-guides/alerting/prometheus-example.yaml)
-```yaml
+```yaml mdox-exec="cat example/user-guides/alerting/prometheus-example.yaml"
 apiVersion: monitoring.coreos.com/v1
 kind: Prometheus
 metadata:
@@ -202,8 +196,7 @@ Prometheus rule files are held in `PrometheusRule` custom resources. Use the lab
 
 The best practice is to label the `PrometheusRule`s containing rule files with `role: alert-rules` as well as the name of the Prometheus object, `prometheus: example` in this case.
 
-[embedmd]:# (../../example/user-guides/alerting/prometheus-example-rules.yaml)
-```yaml
+```yaml mdox-exec="cat example/user-guides/alerting/prometheus-example-rules.yaml"
 apiVersion: monitoring.coreos.com/v1
 kind: PrometheusRule
 metadata:

Documentation/user-guides/getting-started.md

@@ -32,8 +32,7 @@ The Prometheus resource includes a field called `serviceMonitorSelector`, which
 
 First, deploy three instances of a simple example application, which listens and exposes metrics on port `8080`.
 
-[embedmd]:# (../../example/user-guides/getting-started/example-app-deployment.yaml)
-```yaml
+```yaml mdox-exec="cat example/user-guides/getting-started/example-app-deployment.yaml"
 apiVersion: apps/v1
 kind: Deployment
 metadata:
@@ -58,8 +57,7 @@ spec:
 
 The ServiceMonitor has a label selector to select Services and their underlying Endpoint objects. The Service object for the example application selects the Pods by the `app` label having the `example-app` value. The Service object also specifies the port on which the metrics are exposed.
 
-[embedmd]:# (../../example/user-guides/getting-started/example-app-service.yaml)
-```yaml
+```yaml mdox-exec="cat example/user-guides/getting-started/example-app-service.yaml"
 kind: Service
 apiVersion: v1
 metadata:
@@ -76,8 +74,7 @@ spec:
 
 This Service object is discovered by a ServiceMonitor, which selects in the same way. The `app` label must have the value `example-app`.
 
-[embedmd]:# (../../example/user-guides/getting-started/example-app-service-monitor.yaml)
-```yaml
+```yaml mdox-exec="cat example/user-guides/getting-started/example-app-service-monitor.yaml"
 apiVersion: monitoring.coreos.com/v1
 kind: ServiceMonitor
 metadata:
@@ -98,16 +95,14 @@ If [RBAC][rbac-auth] authorization is activated, you must create RBAC rules for
 
 Create a ClusterRole and ClusterRoleBinding for the Prometheus Pods:
 
-[embedmd]:# (../../example/rbac/prometheus/prometheus-service-account.yaml)
-```yaml
+```yaml mdox-exec="cat example/rbac/prometheus/prometheus-service-account.yaml"
 apiVersion: v1
 kind: ServiceAccount
 metadata:
   name: prometheus
 ```
 
-[embedmd]:# (../../example/rbac/prometheus/prometheus-cluster-role.yaml)
-```yaml
+```yaml mdox-exec="cat example/rbac/prometheus/prometheus-cluster-role.yaml"
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
 metadata:
@@ -134,8 +129,7 @@ rules:
   verbs: ["get"]
 ```
 
-[embedmd]:# (../../example/rbac/prometheus/prometheus-cluster-role-binding.yaml)
-```yaml
+```yaml mdox-exec="cat example/rbac/prometheus/prometheus-cluster-role-binding.yaml"
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRoleBinding
 metadata:
@@ -156,8 +150,7 @@ For more information, see the [Prometheus Operator RBAC guide][prom-rbac].
 
 A Prometheus object defines the `serviceMonitorSelector` to specify which ServiceMonitors should be included. Above the label `team: frontend` was specified, so that's what the Prometheus object selects by.
 
-[embedmd]:# (../../example/user-guides/getting-started/prometheus-service-monitor.yaml)
-```yaml
+```yaml mdox-exec="cat example/user-guides/getting-started/prometheus-service-monitor.yaml"
 apiVersion: monitoring.coreos.com/v1
 kind: Prometheus
 metadata:
@@ -181,8 +174,7 @@ This enables the frontend team to create new ServiceMonitors and Services which
 
 Finally, a Prometheus object defines the `podMonitorSelector` to specify which PodMonitors should be included. Above the label `team: frontend` was specified, so that's what the Prometheus object selects by.
 
-[embedmd]:# (../../example/user-guides/getting-started/prometheus-pod-monitor.yaml)
-```yaml
+```yaml mdox-exec="cat example/user-guides/getting-started/prometheus-pod-monitor.yaml"
 apiVersion: monitoring.coreos.com/v1
 kind: Prometheus
 metadata:
@@ -206,8 +198,7 @@ This enables the frontend team to create new PodMonitors which allow Prometheus
 
 To access the Prometheus instance it must be exposed to the outside. This example exposes the instance using a Service of type `NodePort`.
 
-[embedmd]:# (../../example/user-guides/getting-started/prometheus-service.yaml)
-```yaml
+```yaml mdox-exec="cat example/user-guides/getting-started/prometheus-service.yaml"
 apiVersion: v1
 kind: Service
 metadata:
@@ -238,8 +229,7 @@ This API access is disabled by default and can be toggled using this boolean fla
 > user is advised to add additional authentication authorization via a proxy to
 > ensure only clients authorized to perform these actions can do so.
 
-[embedmd]:# (../../example/user-guides/getting-started/prometheus-admin-api.yaml)
-```yaml
+```yaml mdox-exec="cat example/user-guides/getting-started/prometheus-admin-api.yaml"
 apiVersion: monitoring.coreos.com/v1
 kind: Prometheus
 metadata:

Documentation/user-guides/monitoring-kubernetes-ingress.md

@@ -190,8 +190,8 @@ Envoy's metrics data model is remarkably similar to that of Prometheus and uses
 
 | Metric Category | Notable Metrics | Description |
 | --------------- | --------------- | ----------- |
-| envoy_http_downstream_rq | envoy_http_downstream_rq_http1_total <br></br> envoy_http_downstream_rq_http1_total <br></br> envoy_http_downstream_rq_total <br></br> envoy_http_downstream_rq_xx | Statistics regarding traffic from the internet, to each Ambassador instance. Tracking this will give you insight into how each pod is performing for various requests. |
-| envoy_cluster_upstream_rq | envoy_cluster_upstream_rq <br></br> envoy_cluster_upstream_rq_xx <br></br> envoy_cluster_upstream_rq_total <br></br> envoy_cluster_upstream_rq_retry | Statistics regarding traffic from Envoy to each upstream service. Tracking this will give you insight to how the request is performing after reaching Ambassador. It will help you pinpoint whether failures are happening in Ambassador or the upstream service. |
+| envoy_http_downstream_rq | envoy_http_downstream_rq_http1_total, envoy_http_downstream_rq_http1_total, envoy_http_downstream_rq_total, envoy_http_downstream_rq_xx | Statistics regarding traffic from the internet, to each Ambassador instance. Tracking this will give you insight into how each pod is performing for various requests. |
+| envoy_cluster_upstream_rq | envoy_cluster_upstream_rq, envoy_cluster_upstream_rq_xx, envoy_cluster_upstream_rq_total, envoy_cluster_upstream_rq_retry | Statistics regarding traffic from Envoy to each upstream service. Tracking this will give you insight to how the request is performing after reaching Ambassador. It will help you pinpoint whether failures are happening in Ambassador or the upstream service. |
 
 
 Envoy collects many more statistics including some regarding rate limiting, circuit breaking, and distributed tracing. See the [Envoy's documentation](https://envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/stats) for more information on the metrics envoy collects.

Documentation/user-guides/storage.md

@@ -15,8 +15,7 @@ This document assumes a basic understanding of PersistentVolumes, PersistentVolu
 
 Automatic provisioning of storage requires a `StorageClass`.
 
-[embedmd]:# (../../example/storage/storageclass.yaml)
-```yaml
+```yaml mdox-exec="cat example/storage/storageclass.yaml"
 apiVersion: storage.k8s.io/v1
 kind: StorageClass
 metadata:
@@ -32,8 +31,7 @@ For best results, use volumes that have high I/O throughput. These examples use
 
 The `StorageClass` that was created can be specified in the `storage` section in the `Prometheus` resource (note that if you're using [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus), then instead of making the following change to your `Prometheus` resource, see the [prometheus-pvc.jsonnet](https://github.com/prometheus-operator/kube-prometheus/blob/master/examples/prometheus-pvc.jsonnet) example).
 
-[embedmd]:# (../../example/storage/persisted-prometheus.yaml)
-```yaml
+```yaml mdox-exec="cat example/storage/persisted-prometheus.yaml"
 apiVersion: monitoring.coreos.com/v1
 kind: Prometheus
 metadata: