From 4b28f04aae86c63532c9f05bf13446e20a27df1b Mon Sep 17 00:00:00 2001
From: Saswata Mukherjee <saswataminsta@yahoo.com>
Date: Tue, 17 Aug 2021 17:37:45 +0530
Subject: [PATCH] Add mdox link checking and formatting

Signed-off-by: Saswata Mukherjee <saswataminsta@yahoo.com>
---
 ADOPTERS.md                                   |  8 +-
 CHANGELOG.md                                  | 17 ++--
 CONTRIBUTING.md                               | 22 ++---
 Documentation/additional-scrape-config.md     |  9 +-
 Documentation/custom-configuration.md         |  4 +-
 Documentation/design.md                       | 30 +++---
 Documentation/exposing-metrics.md             |  2 +-
 Documentation/high-availability.md            | 20 ++--
 Documentation/network-policies.md             |  2 +
 Documentation/rbac-crd.md                     | 24 ++---
 Documentation/rbac.md                         | 20 ++--
 Documentation/thanos.md                       | 31 +++---
 Documentation/troubleshooting.md              | 32 ++++---
 Documentation/user-guides/alerting.md         | 16 +---
 .../exposing-prometheus-and-alertmanager.md   | 15 +--
 Documentation/user-guides/getting-started.md  | 28 ++----
 .../monitoring-kubernetes-ingress.md          | 94 ++++++++++---------
 Documentation/user-guides/storage.md          | 14 +--
 MAINTAINERS.md                                | 33 ++++---
 Makefile                                      |  6 +-
 README.md                                     | 26 ++---
 RELEASE.md                                    | 36 +++----
 SECURITY.md                                   |  1 -
 code-of-conduct.md                            |  2 +-
 governance.md                                 | 62 ++++++------
 scripts/go.mod                                |  2 +-
 scripts/go.sum                                |  8 +-
 27 files changed, 263 insertions(+), 301 deletions(-)

diff --git a/ADOPTERS.md b/ADOPTERS.md
index 4a04d51bd..94c5bcbb3 100644
--- a/ADOPTERS.md
+++ b/ADOPTERS.md
@@ -1,7 +1,7 @@
 ---
-title: "Adopters"
-date: 2021-03-08T23:50:39+01:00
+title: Adopters
 draft: false
+date: "2021-03-08T23:50:39+01:00"
 ---
 
 <!--
@@ -27,7 +27,7 @@ This document tracks people and use cases for the Prometheus Operator in product
 
 Go ahead and [add your organization](https://github.com/prometheus-operator/prometheus-operator/edit/master/ADOPTERS.md) to the list.
 
-## Clyso 
+## Clyso
 
 [clyso.com](https://www.clyso.com/en)
 
@@ -83,7 +83,7 @@ Details:
 - 20000 samples/s
 - 1M active series
 
-## Innovaccer ##
+## Innovaccer
 
 https://innovaccer.com/
 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a927dedb9..19021fa03 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,7 +2,7 @@
 
 No change since v0.51.0.
 
-_The CI automation failed to build the v0.51.0 images so we had to create a new patch release._
+*The CI automation failed to build the v0.51.0 images so we had to create a new patch release.*
 
 ## 0.51.0 / 2021-09-24
 
@@ -181,11 +181,12 @@ future.
 
 ## 0.42.1 / 2020-09-21
 
-* [BUGFIX] Bump client-go to fix watch bug 
+* [BUGFIX] Bump client-go to fix watch bug
 
 ## 0.42.0 / 2020-09-09
 
-The Prometheus Operator now lives in its own independent GitHub organization.  
+The Prometheus Operator now lives in its own independent GitHub organization.
+
 We have also added a governance (#3398).
 
 * [FEATURE] Move API types out into their own module (#3395)
@@ -230,12 +231,12 @@ We have also added a governance (#3398).
 
 * [CHANGE] Update dependencies to prometheus 2.18 (#3231)
 * [CHANGE] Add support for new prometheus versions (v2.18 & v2.19) (#3284)
-* [CHANGE] bump Alertmanager default version to v0.21.0 (#3286) 
+* [CHANGE] bump Alertmanager default version to v0.21.0 (#3286)
 * [FEATURE] Automatically disable high availability mode for 1 replica alertmanager (#3233)
 * [FEATURE] thanos-sidecar: Add minTime arg (#3253)
-* [FEATURE] Add scrapeTimeout as global configurable parameter (#3250) 
-* [FEATURE] Add EnforcedSampleLimit which enforces a global sample limit (#3276) 
-* [FEATURE] add ability to exclude rules from namespace label enforcement (#3207) 
+* [FEATURE] Add scrapeTimeout as global configurable parameter (#3250)
+* [FEATURE] Add EnforcedSampleLimit which enforces a global sample limit (#3276)
+* [FEATURE] add ability to exclude rules from namespace label enforcement (#3207)
 * [BUGFIX] thanos sidecar: log flags double definition (#3242)
 * [BUGFIX] Mutate rule labels, annotations to strings (#3230)
 
@@ -513,7 +514,7 @@ and accepts and comma-separated list of namespaces as a string.
 ## 0.22.0 / 2018-07-09
 
 * [FEATURE] Allow setting volume name via volumetemplateclaimtemplate in prom and alertmanager (#1538)
-* [FEATURE] Allow setting custom tags of container images (#1584) 
+* [FEATURE] Allow setting custom tags of container images (#1584)
 * [ENHANCEMENT] Update default Thanos to v0.1.0-rc.2 (#1585)
 * [ENHANCEMENT] Split rule config map mounted into Prometheus if it exceeds Kubernetes config map limit (#1562)
 * [BUGFIX] Mount Prometheus data volume into Thanos sidecar & pass correct path to Thanos sidecar (#1583)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0478933d5..617d46cb6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,20 +1,20 @@
 ---
-title: "Contributing"
-description: "How can I contribute to the Prometheus Operator and kube-prometheus?"
-lead: ""
-date: 2021-03-08T08:48:57+00:00
-lastmod: 2021-03-08T08:48:57+00:00
-draft: false
-images: []
-menu:
-  docs:
-    parent: "prologue"
 weight: 200
 toc: true
+title: Contributing
+menu:
+    docs:
+        parent: prologue
+lead: ""
+lastmod: "2021-03-08T08:48:57+00:00"
+images: []
+draft: false
+description: How can I contribute to the Prometheus Operator and kube-prometheus?
+date: "2021-03-08T08:48:57+00:00"
 ---
 
 This project is licensed under the [Apache 2.0 license](LICENSE) and accept
-contributions via GitHub pull requests.  This document outlines some of the
+contributions via GitHub pull requests. This document outlines some of the
 conventions on development workflow, commit message formatting, contact points
 and other resources to make it easier to get your contribution accepted.
 
diff --git a/Documentation/additional-scrape-config.md b/Documentation/additional-scrape-config.md
index 287d44cfe..52f6c92a3 100644
--- a/Documentation/additional-scrape-config.md
+++ b/Documentation/additional-scrape-config.md
@@ -5,8 +5,7 @@ additional Prometheus scrape configurations. Scrape configurations specified
 are appended to the configurations generated by the Prometheus Operator.
 
 Job configurations specified must have the form as specified in the official
-[Prometheus documentation](
-https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config).
+[Prometheus documentation](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config).
 As scrape configs are appended, the user is responsible to make sure it is
 valid. *Note* that using this feature may expose the possibility to break
 upgrades of Prometheus.
@@ -17,7 +16,7 @@ scrape configs are going to break Prometheus after the upgrade.
 ## Creating an additional configuration
 
 First, you will need to create the additional configuration.
-Below we are making a simple "prometheus" config.  Name this
+Below we are making a simple "prometheus" config. Name this
 `prometheus-additional.yaml` or something similar.
 
 ```yaml
@@ -62,5 +61,5 @@ NOTE: Use only one secret for ALL additional scrape configurations.
 
 ## Additional References
 
- * [Prometheus Spec](api.md#prometheusspec)
- * [Additional Scrape Configs](../example/additional-scrape-configs)
+* [Prometheus Spec](api.md#prometheusspec)
+* [Additional Scrape Configs](../example/additional-scrape-configs)
diff --git a/Documentation/custom-configuration.md b/Documentation/custom-configuration.md
index 491f20041..ac99b4560 100644
--- a/Documentation/custom-configuration.md
+++ b/Documentation/custom-configuration.md
@@ -3,9 +3,7 @@
     <i class="fa fa-exclamation-triangle"></i><b> Note:</b> Starting with v0.39.0, Prometheus Operator requires use of Kubernetes v1.16.x and up.
 </div>
 
-
-**Deprecation Warning:** The _custom configuration_ option of the Prometheus Operator will be deprecated in favor of the [_additional scrape config_](additional-scrape-config.md) option.
-
+**Deprecation Warning:** The *custom configuration* option of the Prometheus Operator will be deprecated in favor of the [*additional scrape config*](additional-scrape-config.md) option.
 
 # Custom Configuration
 
diff --git a/Documentation/design.md b/Documentation/design.md
index 6b6a1834b..e8130bd5d 100644
--- a/Documentation/design.md
+++ b/Documentation/design.md
@@ -1,15 +1,15 @@
 ---
-title: "Design"
-description: "This document describes the design and interaction between the custom resource definitions that the Prometheus Operator introduces."
-lead: ""
-date: 2021-03-08T08:49:31+00:00
-draft: false
-images: []
-menu:
-  docs:
-    parent: "operator"
 weight: 100
 toc: true
+title: Design
+menu:
+    docs:
+        parent: operator
+lead: ""
+images: []
+draft: false
+description: This document describes the design and interaction between the custom resource definitions that the Prometheus Operator introduces.
+date: "2021-03-08T08:49:31+00:00"
 ---
 
 This document describes the design and interaction between the custom resource definitions that the Prometheus Operator introduces.
@@ -35,7 +35,6 @@ The CRD specifies which `ServiceMonitor`s should be covered by the deployed Prom
 
 If no selection of `ServiceMonitor`s is provided, the Operator leaves management of the `Secret` to the user, which allows to provide custom configurations while still benefiting from the Operator's capabilities of managing Prometheus setups.
 
-
 ## Alertmanager
 
 The `Alertmanager` custom resource definition (CRD) declaratively defines a desired Alertmanager setup to run in a Kubernetes cluster. It provides options to configure replication and persistent storage.
@@ -44,15 +43,13 @@ For each `Alertmanager` resource, the Operator deploys a properly configured `St
 
 When there are two or more configured replicas the operator runs the Alertmanager instances in high availability mode.
 
-
 ## ThanosRuler
 
 The `ThanosRuler` custom resource definition (CRD) declaratively defines a desired [Thanos Ruler](https://github.com/thanos-io/thanos/blob/master/docs/components/rule.md) setup to run in a Kubernetes cluster. With Thanos Ruler recording and alerting rules can be processed across multiple Prometheus instances.
 
-A `ThanosRuler` instance requires at least one `queryEndpoint` which points to the location of Thanos Queriers or Prometheus instances.  The `queryEndpoints` are used to configure the `--query` arguments(s) of the Thanos runtime.
+A `ThanosRuler` instance requires at least one `queryEndpoint` which points to the location of Thanos Queriers or Prometheus instances. The `queryEndpoints` are used to configure the `--query` arguments(s) of the Thanos runtime.
 Further information can also be found in the [Thanos doc](thanos.md).
 
-
 ## ServiceMonitor
 
 The `ServiceMonitor` custom resource definition (CRD) allows to declaratively define how a dynamic set of services should be monitored. Which services are selected to be monitored with the desired configuration is defined using label selections. This allows an organization to introduce conventions around how metrics are exposed, and then following these conventions new services are automatically discovered, without the need to reconfigure the system.
@@ -69,13 +66,13 @@ The `endpoints` section of the `ServiceMonitorSpec`, is used to configure which
 
 Both `ServiceMonitors` as well as discovered targets may come from any namespace. This is important to allow cross-namespace monitoring use cases, e.g. for meta-monitoring. Using the `ServiceMonitorNamespaceSelector` of the `PrometheusSpec`, one can restrict the namespaces `ServiceMonitor`s are selected from by the respective Prometheus server. Using the `namespaceSelector` of the `ServiceMonitorSpec`, one can restrict the namespaces the `Endpoints` objects are allowed to be discovered from.
 To discover targets in all namespaces the `namespaceSelector` has to be empty:
+
 ```yaml
 spec:
   namespaceSelector:
     any: true
 ```
 
-
 ## PodMonitor
 
 The `PodMonitor` custom resource definition (CRD) allows to declaratively define how a dynamic set of pods should be monitored.
@@ -91,26 +88,23 @@ The `PodMetricsEndpoints` section of the `PodMonitorSpec`, is used to configure
 Both `PodMonitors` as well as discovered targets may come from any namespace. This is important to allow cross-namespace monitoring use cases, e.g. for meta-monitoring.
 Using the `namespaceSelector` of the `PodMonitorSpec`, one can restrict the namespaces the `Pods` are allowed to be discovered from.
 To discover targets in all namespaces the `namespaceSelector` has to be empty:
+
 ```yaml
 spec:
   namespaceSelector:
     any: true
 ```
 
-
 ## Probe
 
 The `Probe` custom resource definition (CRD) allows to declarative define how groups of ingresses and static targets should be monitored. Besides the target, the `Probe` object requires a `prober` which is the service that monitors the target and provides metrics for Prometheus to scrape. This could be for example achieved using the [blackbox exporter](https://github.com/prometheus/blackbox_exporter/).
 
-
 ## PrometheusRule
 
 The `PrometheusRule` custom resource definition (CRD) declaratively defines a desired Prometheus rule to be consumed by one or more Prometheus instances.
 
 Alerts and recording rules can be saved and applied as YAML files, and dynamically loaded without requiring any restart.
 
-
 ## AlertmanagerConfig
 
 The `AlertmanagerConfig` custom resource definition (CRD) declaratively specifies subsections of the Alertmanager configuration, allowing routing of alerts to custom receivers, and setting inhibit rules. The `AlertmanagerConfig` can be defined on a namespace level providing an aggregated config to Alertmanager. An example on how to use it is provided [here](../example/user-guides/alerting/alertmanager-config-example.yaml). Please be aware that this CRD is not stable yet.
-
diff --git a/Documentation/exposing-metrics.md b/Documentation/exposing-metrics.md
index 99c2945dd..3e9fb3dbf 100644
--- a/Documentation/exposing-metrics.md
+++ b/Documentation/exposing-metrics.md
@@ -13,7 +13,7 @@ Not all software is natively instrumented with Prometheus metrics, but still rec
 
 Exporters can generally be divided into two categories:
 
-* Instance exporters: These expose metrics about a single instance of an application. For example the HTTP requests that a single HTTP server has exporters served. These exporters are deployed as a [side-car](http://blog.kubernetes.io/2015/06/the-distributed-system-toolkit-patterns.html) container in the same pod as the actual instance of the respective application.  A real life example is the [`dnsmasq` metrics sidecar](https://github.com/kubernetes/dns/blob/master/docs/sidecar/README.md), which converts the proprietary metrics format communicated over the DNS protocol by `dnsmasq` to the Prometheus exposition format and exposes it on an HTTP server.
+* Instance exporters: These expose metrics about a single instance of an application. For example the HTTP requests that a single HTTP server has exporters served. These exporters are deployed as a [side-car](http://blog.kubernetes.io/2015/06/the-distributed-system-toolkit-patterns.html) container in the same pod as the actual instance of the respective application. A real life example is the [`dnsmasq` metrics sidecar](https://github.com/kubernetes/dns/blob/master/docs/sidecar/README.md), which converts the proprietary metrics format communicated over the DNS protocol by `dnsmasq` to the Prometheus exposition format and exposes it on an HTTP server.
 
 * Cluster-state exporters: These expose metrics about an entire system. For example these could be the number of 3D objects in a game, or metrics about a Kubernetes deployment. These exporters are typically deployed as a normal Kubernetes deployment, but can vary depending on the nature of the particular exporter. A real life example of this is the [`kube-state-metrics`](https://github.com/kubernetes/kube-state-metrics) exporter, which exposes metrics about the cluster state of a Kubernetes cluster.
 
diff --git a/Documentation/high-availability.md b/Documentation/high-availability.md
index 32741bf36..ffdf35694 100644
--- a/Documentation/high-availability.md
+++ b/Documentation/high-availability.md
@@ -1,15 +1,15 @@
 ---
-title: "High Availability"
-description: "High Availability is a must for the monitoring infrastructure."
-lead: ""
-date: 2021-03-08T08:49:31+00:00
-draft: false
-images: []
-menu:
-  docs:
-    parent: "operator"
 weight: 300
 toc: true
+title: High Availability
+menu:
+    docs:
+        parent: operator
+lead: ""
+images: []
+draft: false
+description: High Availability is a must for the monitoring infrastructure.
+date: "2021-03-08T08:49:31+00:00"
 ---
 
 High availability is not only important for customer facing software, but if the monitoring infrastructure is not highly available, then there is a risk that operations people are not notified for alerts of the customer facing software. Therefore high availability must be just as thought through for the monitoring stack, as for anything else.
@@ -26,7 +26,7 @@ One of the goals with the Prometheus Operator is that we want to completely auto
 
 The final step of the high availability scheme between Prometheus and Alertmanager is that Prometheus, when an alert triggers, actually fires alerts against *all* instances of an Alertmanager cluster. Prometheus can discover all Alertmanagers through the Kubernetes API.
 
-The Alertmanager, starting with the `v0.5.0` release, ships with a high availability mode. It implements a gossip protocol to synchronize instances of an Alertmanager cluster regarding notifications that have been sent out, to prevent duplicate notifications. It is an AP (available and partition tolerant) system. Being an AP system, means that notifications are guaranteed to be sent at least once. 
+The Alertmanager, starting with the `v0.5.0` release, ships with a high availability mode. It implements a gossip protocol to synchronize instances of an Alertmanager cluster regarding notifications that have been sent out, to prevent duplicate notifications. It is an AP (available and partition tolerant) system. Being an AP system, means that notifications are guaranteed to be sent at least once.
 
 The Prometheus Operator ensures that Alertmanager clusters are properly configured to run highly available on Kubernetes, and allows easy configuration of Alertmanagers discovery for Prometheus.
 
diff --git a/Documentation/network-policies.md b/Documentation/network-policies.md
index c2511c943..aa985b734 100644
--- a/Documentation/network-policies.md
+++ b/Documentation/network-policies.md
@@ -16,6 +16,7 @@ This example will close all inbound communication on the namespace monitoring, a
 First, follow the instructions to [add Calico to an existing Kubernetes cluster](http://docs.projectcalico.org/v1.5/getting-started/kubernetes/installation/).
 
 Next, use the following configuration to deny all the ingress (inbound) traffic.
+
 ```yaml
  apiVersion: networking.k8s.io/v1
  kind: NetworkPolicy
@@ -26,6 +27,7 @@ Next, use the following configuration to deny all the ingress (inbound) traffic.
    podSelector:
      matchLabels:
 ```
+
 Save the config file as default-deny-all.yaml and apply the configuration to the cluster using
 
 ```sh
diff --git a/Documentation/rbac-crd.md b/Documentation/rbac-crd.md
index 00c33f66c..fe4a29c63 100644
--- a/Documentation/rbac-crd.md
+++ b/Documentation/rbac-crd.md
@@ -1,15 +1,15 @@
 ---
-title: "RBAC for CRDs"
-description: "Aggregate permissions on the Prometheus Operator CustomResourceDefinitions."
-lead: ""
-date: 2021-03-08T08:49:31+00:00
-draft: false
-images: []
-menu:
-  docs:
-    parent: "operator"
-weight: 420 # nice
+weight: 420
 toc: true
+title: RBAC for CRDs
+menu:
+    docs:
+        parent: operator
+lead: ""
+images: []
+draft: false
+description: Aggregate permissions on the Prometheus Operator CustomResourceDefinitions.
+date: "2021-03-08T08:49:31+00:00"
 ---
 
 ## Aggregated ClusterRoles
@@ -18,11 +18,11 @@ It can be useful to aggregate permissions on the Prometheus Operator CustomResou
 
 This can be achieved using ClusterRole aggregation. This lets admins include rules for custom resources, such as those served by CustomResourceDefinitions or Aggregated API servers, on the default roles.
 
-> Note: ClusterRole aggregation is available starting Kubernetes 1.9. 
+> Note: ClusterRole aggregation is available starting Kubernetes 1.9.
 
 ## Example
 
-In order to aggregate _read_ (resp. _edit_) permissions for the Prometheus Operator CustomResourceDefinitions to the `view` (resp. `edit` / `admin`) role(s), a cluster admin can create the `ClusterRole`s below.
+In order to aggregate *read* (resp. *edit*) permissions for the Prometheus Operator CustomResourceDefinitions to the `view` (resp. `edit` / `admin`) role(s), a cluster admin can create the `ClusterRole`s below.
 
 This grants:
 - Users with `view` role permissions to view the Prometheus Operator CRDs within their namespaces,
diff --git a/Documentation/rbac.md b/Documentation/rbac.md
index 2554a3b0d..1443c249e 100644
--- a/Documentation/rbac.md
+++ b/Documentation/rbac.md
@@ -1,15 +1,15 @@
 ---
-title: "RBAC"
-description: "High Availability is a must for the monitoring infrastructure."
-lead: ""
-date: 2021-03-08T08:49:31+00:00
-draft: false
-images: []
-menu:
-  docs:
-    parent: "operator"
 weight: 400
 toc: true
+title: RBAC
+menu:
+    docs:
+        parent: operator
+lead: ""
+images: []
+draft: false
+description: High Availability is a must for the monitoring infrastructure.
+date: "2021-03-08T08:49:31+00:00"
 ---
 
 [Role-based access control](https://en.wikipedia.org/wiki/Role-based_access_control) (RBAC) for the Prometheus Operator involves two parts, RBAC rules for the Operator itself and RBAC rules for the Prometheus Pods themselves created by the Operator as Prometheus requires access to the Kubernetes API for target and Alertmanager discovery.
@@ -159,7 +159,7 @@ rules:
   verbs: ["get"]
 ```
 
-> Note: A cluster admin is required to create this `ClusterRole` and create a `ClusterRoleBinding` or `RoleBinding` to the `ServiceAccount` used by the Prometheus `Pod`s.  The `ServiceAccount` used by the Prometheus `Pod`s can be specified in the `Prometheus` object.
+> Note: A cluster admin is required to create this `ClusterRole` and create a `ClusterRoleBinding` or `RoleBinding` to the `ServiceAccount` used by the Prometheus `Pod`s. The `ServiceAccount` used by the Prometheus `Pod`s can be specified in the `Prometheus` object.
 
 ## Example
 
diff --git a/Documentation/thanos.md b/Documentation/thanos.md
index 0a06fa9fa..e35b8d3c0 100644
--- a/Documentation/thanos.md
+++ b/Documentation/thanos.md
@@ -1,18 +1,18 @@
 ---
-title: "Thanos"
-description: "Thanos and the Prometheus Operator."
-lead: "Thanos and the Prometheus Operator."
-date: 2021-03-08T08:49:31+00:00
-draft: false
-images: []
-menu:
-  docs:
-    parent: "operator"
 weight: 500
 toc: true
+title: Thanos
+menu:
+    docs:
+        parent: operator
+lead: Thanos and the Prometheus Operator.
+images: []
+draft: false
+description: Thanos and the Prometheus Operator.
+date: "2021-03-08T08:49:31+00:00"
 ---
 
-_Note: This guide is valid for Prometheus Operator v0.28+ and Thanos v0.2+ and above._
+*Note: This guide is valid for Prometheus Operator v0.28+ and Thanos v0.2+ and above.*
 
 [Thanos](https://github.com/thanos-io/thanos/) is a set of components that can be composed into a highly available,
 multi Prometheus metric system with potentially unlimited storage capacity, if your Object Storage allows for it.
@@ -23,8 +23,8 @@ Before continuing with Prometheus Operator Thanos integration, it is recommended
 
 Prometheus Operator operates `Prometheus` and optionally `ThanosRuler` components.
 Other Thanos components, such as the querier and store gateway, must be configured
-separately.  The Thanos system integrates with Prometheus by adding a Thanos
-sidecar to each Prometheus instance.  The Thanos sidecar can be configured directly in the `Prometheus` CRD. This Sidecar can hook into the Thanos querying system as well as **optionally** back up your data in object storage.
+separately. The Thanos system integrates with Prometheus by adding a Thanos
+sidecar to each Prometheus instance. The Thanos sidecar can be configured directly in the `Prometheus` CRD. This Sidecar can hook into the Thanos querying system as well as **optionally** back up your data in object storage.
 
 Each component other than the sidecar and `ThanosRuler` is deployed independently of the Prometheus Operator and its Thanos configuration. The
 [kube-thanos](https://github.com/thanos-io/kube-thanos/) project has some starting points for other Thanos components deployments.
@@ -92,7 +92,7 @@ spec:
 ...
 ```
 
-This will attach Thanos sidecar that will backup all _new blocks_ that Prometheus produces every 2 hours to the object storage.
+This will attach Thanos sidecar that will backup all *new blocks* that Prometheus produces every 2 hours to the object storage.
 
 NOTE: This option will also disable local Prometheus compaction. This means that Thanos compactor is the main singleton component
 responsible for compactions on a global, object storage level.
@@ -100,7 +100,7 @@ responsible for compactions on a global, object storage level.
 ## Thanos Ruler
 
 The [Thanos Ruler](https://github.com/thanos-io/thanos/blob/master/docs/components/rule.md) component allows recording and alerting rules to be processed across
-multiple Prometheus instances.  A `ThanosRuler` instance requires at least one `queryEndpoint` which points to the location of Thanos Queriers or Prometheus instances.  The `queryEndpoints` are used to configure the `--query` arguments(s) of the Thanos runtime.
+multiple Prometheus instances. A `ThanosRuler` instance requires at least one `queryEndpoint` which points to the location of Thanos Queriers or Prometheus instances. The `queryEndpoints` are used to configure the `--query` arguments(s) of the Thanos runtime.
 
 ```yaml
 ...
@@ -120,8 +120,7 @@ spec:
     - dnssrv+_http._tcp.my-thanos-querier.monitoring.svc.cluster.local
 ```
 
-The recording and alerting rules used by a `ThanosRuler` component, are configured using the same `PrometheusRule` objects which are used by Prometheus.  In the given example, the rules contained in any `PrometheusRule` object which match the label `role=my-thanos-rules` will be added to the Thanos Ruler POD.
-
+The recording and alerting rules used by a `ThanosRuler` component, are configured using the same `PrometheusRule` objects which are used by Prometheus. In the given example, the rules contained in any `PrometheusRule` object which match the label `role=my-thanos-rules` will be added to the Thanos Ruler POD.
 
 ## Other Thanos Components
 
diff --git a/Documentation/troubleshooting.md b/Documentation/troubleshooting.md
index 0d9a919a9..5bcdbb08f 100644
--- a/Documentation/troubleshooting.md
+++ b/Documentation/troubleshooting.md
@@ -1,15 +1,15 @@
 ---
-title: "Troubleshooting"
-description: "Guide on troubleshooting the Prometheus Operator."
-lead: ""
-date: 2021-03-08T08:49:31+00:00
-draft: false
-images: []
-menu:
-  docs:
-    parent: "operator"
 weight: 600
 toc: true
+title: Troubleshooting
+menu:
+    docs:
+        parent: operator
+lead: ""
+images: []
+draft: false
+description: Guide on troubleshooting the Prometheus Operator.
+date: "2021-03-08T08:49:31+00:00"
 ---
 
 ### RBAC on Google Container Engine (GKE)
@@ -22,7 +22,7 @@ Error from server (Forbidden): error when creating
 "manifests/prometheus-operator/prometheus-operator-cluster-role.yaml":
 clusterroles.rbac.authorization.k8s.io "prometheus-operator" is forbidden: attempt to grant extra privileges:
 <....>
-````
+```
 
 This is due to the way Container Engine checks permissions. From [Google Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/how-to/role-based-access-control):
 
@@ -50,11 +50,10 @@ When creating/deleting/modifying `ServiceMonitor` objects it is sometimes not as
 
 A common problem related to `ServiceMonitor` identification by Prometheus is related to an incorrect tagging, that does not match the `Prometheus` custom resource definition scope, or lack of permission for the Prometheus `ServiceAccount` to *get, list, watch* `Services` and `Endpoints` from the target application being monitored. As a general guideline consider the diagram below, giving an example of a `Deployment` and `Service` called `my-app`, being monitored by Prometheus based on a `ServiceMonitor` named `my-service-monitor`:
 
-![flow diagram](./custom-metrics-elements.png)
+![flow diagram](custom-metrics-elements.png)
 
 Note: The `ServiceMonitor` references a `Service` (not a `Deployment`, or a `Pod`), by labels *and* by the port name in the `Service`. This *port name* is optional in Kubernetes, but must be specified for the `ServiceMonitor` to work. It is not the same as the port name on the `Pod` or container, although it can be.
 
-
 #### Has my `ServiceMonitor` been picked up by Prometheus?
 
 `ServiceMonitor` objects and the namespace where they belong are selected by the `serviceMonitorSelector` and `serviceMonitorNamespaceSelector`of a Prometheus object. The name of a `ServiceMonitor` is encoded in the Prometheus configuration, so you can simply grep whether it is present there. The configuration generated by the Prometheus Operator is stored in a Kubernetes `Secret`, named after the Prometheus object name prefixed with `prometheus-` and is located in the same namespace as the Prometheus object. For example for a Prometheus object called `k8s` one can find out if the `ServiceMonitor` named `my-service-monitor` has been picked up with:
@@ -69,9 +68,10 @@ Prometheus is installed, all looks good, however the `Targets` are all showing a
 
 #### Did you check the webhooks?
 
-Issue has been resolved by amending the webhooks to use `0.0.0.0` instead of `127.0.0.1`. Follow the below commands and it will update the webhooks which allows connections to all `clusterIP's`  in all `namespaces` and not just `127.0.0.1`.
+Issue has been resolved by amending the webhooks to use `0.0.0.0` instead of `127.0.0.1`. Follow the below commands and it will update the webhooks which allows connections to all `clusterIP's` in all `namespaces` and not just `127.0.0.1`.
 
 **Update the kubelet service to include webhook and restart:**
+
 ```sh
 KUBEADM_SYSTEMD_CONF=/etc/systemd/system/kubelet.service.d/10-kubeadm.conf
 sed -e "/cadvisor-port=0/d" -i "$KUBEADM_SYSTEMD_CONF"
@@ -83,6 +83,7 @@ systemctl restart kubelet
 ```
 
 **Modify the kube controller and kube scheduler to allow for reading data:**
+
 ```sh
 sed -e "s/- --address=127.0.0.1/- --address=0.0.0.0/" -i /etc/kubernetes/manifests/kube-controller-manager.yaml
 sed -e "s/- --address=127.0.0.1/- --address=0.0.0.0/" -i /etc/kubernetes/manifests/kube-scheduler.yaml
@@ -111,6 +112,7 @@ metadata:
 We would then define the service monitor using `metrics` as the port not `"8080"`. E.g.
 
 **CORRECT**
+
 ```yaml
 kind: ServiceMonitor
 metadata:
@@ -122,6 +124,7 @@ spec:
 ```
 
 **INCORRECT**
+
 ```yaml
 kind: ServiceMonitor
 metadata:
@@ -132,5 +135,4 @@ spec:
     - port: "8080"
 ```
 
-The incorrect example will give an error along these lines `spec.endpoints.port in body must be of type string:
-"integer"`
+The incorrect example will give an error along these lines `spec.endpoints.port in body must be of type string: "integer"`
diff --git a/Documentation/user-guides/alerting.md b/Documentation/user-guides/alerting.md
index 24f1168e9..5d0d85a7b 100644
--- a/Documentation/user-guides/alerting.md
+++ b/Documentation/user-guides/alerting.md
@@ -5,7 +5,7 @@
 
 # Alerting
 
-This guide assumes you have a basic understanding of the `Prometheus` resource and have read the [getting started guide][getting-started].
+This guide assumes you have a basic understanding of the `Prometheus` resource and have read the [getting started guide](getting-started.md).
 
 The Prometheus Operator introduces an Alertmanager resource, which allows users to declaratively describe an Alertmanager cluster. To successfully deploy an Alertmanager cluster, it is important to understand the contract between Prometheus and Alertmanager.
 
@@ -15,7 +15,7 @@ The Alertmanager may be used to:
 * Silence alerts
 * Route and send grouped notifications via providers (PagerDuty, OpsGenie, ...)
 
-Prometheus' configuration also includes "rule files", which contain the [alerting rules][alerting-rules]. When an alerting rule triggers it fires that alert against *all* Alertmanager instances, on *every* rule evaluation interval. The Alertmanager instances communicate to each other which notifications have already been sent out. For more information on this system design, see the [High Availability scheme description][ha-scheme].
+Prometheus' configuration also includes "rule files", which contain the [alerting rules](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/). When an alerting rule triggers it fires that alert against *all* Alertmanager instances, on *every* rule evaluation interval. The Alertmanager instances communicate to each other which notifications have already been sent out. For more information on this system design, see the [High Availability scheme description](../high-availability.md).
 
 The Prometheus Operator also introduces an AlertmanagerConfig resource, which allows users to declaratively describe Alertmanager configurations. The AlertmanagerConfig resource is currently v1alpha1, testing and feedback are welcome.
 
@@ -32,7 +32,7 @@ spec:
 
 The Alertmanager instances will not be able to start up, unless a valid configuration is given. An config file Secret will be composed by taking an optional base config file Secret specified through the `configSecret` field in the Alertmanager resource Spec, and merging that with any AlertmanagerConfig resources that get matched by using the `alertmanagerConfigSelector` and `alertmanagerConfigNamespaceSelector` selectors from the `Alertmanager` resource.
 
-For more information on configuring Alertmanager, see the Prometheus [Alerting Configuration document][alerting-config].
+For more information on configuring Alertmanager, see the Prometheus [Alerting Configuration document](https://prometheus.io/docs/alerting/configuration/).
 
 ## AlertmanagerConfig Resource
 
@@ -167,7 +167,7 @@ Once created it allows the web UI to be accessible via a Node's IP and the port
 
 ## Fire Alerts
 
-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.
+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.
 
 ```yaml mdox-exec="cat example/user-guides/alerting/prometheus-example.yaml"
 apiVersion: monitoring.coreos.com/v1
@@ -235,10 +235,4 @@ Looking at the status page for "Runtime & Build Information" on the Prometheus w
 
 These show three discovered Alertmanagers.
 
-Heading to the Alertmanager web UI now shows one active alert, although all Prometheus instances are firing it. [Configuring the Alertmanager][alerting-config] further allows custom alert routing, grouping and notification mechanisms.
-
-
-[alerting-config]: https://prometheus.io/docs/alerting/configuration/
-[alerting-rules]: https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/
-[ha-scheme]: ../high-availability.md
-[getting-started]: getting-started.md
+Heading to the Alertmanager web UI now shows one active alert, although all Prometheus instances are firing it. [Configuring the Alertmanager](https://prometheus.io/docs/alerting/configuration/) further allows custom alert routing, grouping and notification mechanisms.
diff --git a/Documentation/user-guides/exposing-prometheus-and-alertmanager.md b/Documentation/user-guides/exposing-prometheus-and-alertmanager.md
index 38b7a2b30..27569e8c5 100644
--- a/Documentation/user-guides/exposing-prometheus-and-alertmanager.md
+++ b/Documentation/user-guides/exposing-prometheus-and-alertmanager.md
@@ -165,13 +165,13 @@ Then it will be available under http://127.0.0.1:8001/api/v1/proxy/namespaces/de
 
 ## Ingress
 
-Exposing the Prometheus or Alertmanager web UI through an Ingress object requires a running Ingress controller. For more information, see the Kubernetes documentation on [Ingress][ingress-doc].
+Exposing the Prometheus or Alertmanager web UI through an Ingress object requires a running Ingress controller. For more information, see the Kubernetes documentation on [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/).
 
-This example was tested with the [NGINX Ingress Controller][nginx-ingress]. For a quick-start for running the NGINX Ingress Controller follow the instructions in the [NGINX Ingress installation guide][nginx-ingress-installation-guide]. 
+This example was tested with the [NGINX Ingress Controller](https://github.com/kubernetes/ingress-nginx). For a quick-start for running the NGINX Ingress Controller follow the instructions in the [NGINX Ingress installation guide](https://github.com/kubernetes/ingress-nginx/blob/master/docs/deploy/index.md).
 
-> Be certain to evaluate available Ingress controllers for the specifics of your  production environment. The NGINX Ingress Controller may or may not be suitable. Consider other solutions, like HA Proxy, Traefik, GCE, or AWS.
+> Be certain to evaluate available Ingress controllers for the specifics of your production environment. The NGINX Ingress Controller may or may not be suitable. Consider other solutions, like HA Proxy, Traefik, GCE, or AWS.
 
-> WARNING: If your Ingress is exposed to the internet, everyone can have full access on your resources. It's strongly recommend to enable an [external authentication][external-auth] or [whitelisting IP address][whitelist-ip].
+> WARNING: If your Ingress is exposed to the internet, everyone can have full access on your resources. It's strongly recommend to enable an [external authentication](https://github.com/kubernetes/ingress-nginx/blob/351ce5394a5ec37153344135c8112f71539b5af4/docs/examples/auth/external-auth/README.md) or [whitelisting IP address](https://github.com/kubernetes/ingress-nginx/blob/351ce5394a5ec37153344135c8112f71539b5af4/docs/user-guide/nginx-configuration/annotations.md#whitelist-source-range).
 
 An Ingress object also requires a Service to be set up, as the requests are routed from the Ingress endpoint to the internal Service.
 
@@ -255,10 +255,3 @@ spec:
 ```
 
 > Note the path `/prometheus` at the end of the `externalUrl`, as specified in the `Ingress` object.
-
-
-[ingress-doc]: https://kubernetes.io/docs/concepts/services-networking/ingress/
-[nginx-ingress]: https://github.com/kubernetes/ingress-nginx
-[nginx-ingress-installation-guide]: https://github.com/kubernetes/ingress-nginx/blob/master/docs/deploy/index.md
-[external-auth]: https://github.com/kubernetes/ingress-nginx/blob/351ce5394a5ec37153344135c8112f71539b5af4/docs/examples/auth/external-auth/README.md
-[whitelist-ip]: https://github.com/kubernetes/ingress-nginx/blob/351ce5394a5ec37153344135c8112f71539b5af4/docs/user-guide/nginx-configuration/annotations.md#whitelist-source-range
diff --git a/Documentation/user-guides/getting-started.md b/Documentation/user-guides/getting-started.md
index 4c6c4d5eb..eca6a37b5 100644
--- a/Documentation/user-guides/getting-started.md
+++ b/Documentation/user-guides/getting-started.md
@@ -6,13 +6,13 @@ This documentation is for an alpha feature. For questions and feedback on the Pr
 
 # Prometheus Operator
 
-Operators were introduced by CoreOS as a class of software that operates other software, putting operational knowledge collected by humans into software. Read more in the original blog post, [Introducing Operators][introducing-operators].
+Operators were introduced by CoreOS as a class of software that operates other software, putting operational knowledge collected by humans into software. Read more in the original blog post, [Introducing Operators](https://web.archive.org/web/20210210032403/https://coreos.com/blog/introducing-operators.html).
 
 The Prometheus Operator serves to make running Prometheus on top of Kubernetes as easy as possible, while preserving Kubernetes-native configuration options.
 
 ## Example Prometheus Operator manifest
 
-To follow this getting started you will need a Kubernetes cluster you have access to. This [example][bundle] describes a Prometheus Operator Deployment, and its required ClusterRole, ClusterRoleBinding, Service Account and Custom Resource Definitions.
+To follow this getting started you will need a Kubernetes cluster you have access to. This [example](../../bundle.yaml) describes a Prometheus Operator Deployment, and its required ClusterRole, ClusterRoleBinding, Service Account and Custom Resource Definitions.
 
 ## Related resources
 
@@ -22,7 +22,7 @@ The Prometheus Operator introduces additional resources in Kubernetes to declare
 * `Alertmanager`
 * `ServiceMonitor`
 
-> See the [Alerting guide][alerting-guide] for more information about the `Alertmanager` resource, or the [Design document][design-doc] for an overview of all resources introduced by the Prometheus Operator.
+> See the [Alerting guide](alerting.md) for more information about the `Alertmanager` resource, or the [Design document](../design.md) for an overview of all resources introduced by the Prometheus Operator.
 
 The Prometheus resource declaratively describes the desired state of a Prometheus deployment, while a ServiceMonitor describes the set of targets to be monitored by Prometheus.
 
@@ -91,7 +91,7 @@ spec:
 
 ## Enable RBAC rules for Prometheus pods
 
-If [RBAC][rbac-auth] authorization is activated, you must create RBAC rules for both Prometheus *and* Prometheus Operator. A ClusterRole and a ClusterRoleBinding for the Prometheus Operator were created in the example Prometheus Operator manifest above. The same must be done for the Prometheus Pods.
+If [RBAC](https://kubernetes.io/docs/reference/access-authn-authz/authorization/) authorization is activated, you must create RBAC rules for both Prometheus *and* Prometheus Operator. A ClusterRole and a ClusterRoleBinding for the Prometheus Operator were created in the example Prometheus Operator manifest above. The same must be done for the Prometheus Pods.
 
 Create a ClusterRole and ClusterRoleBinding for the Prometheus Pods:
 
@@ -144,7 +144,7 @@ subjects:
   namespace: default
 ```
 
-For more information, see the [Prometheus Operator RBAC guide][prom-rbac].
+For more information, see the [Prometheus Operator RBAC guide](../rbac.md).
 
 ## Include ServiceMonitors
 
@@ -166,7 +166,7 @@ spec:
   enableAdminAPI: false
 ```
 
-> If you have RBAC authorization activated, use the RBAC aware [Prometheus manifest][prometheus-manifest] instead.
+> If you have RBAC authorization activated, use the RBAC aware [Prometheus manifest](../../example/rbac/prometheus/prometheus.yaml) instead.
 
 This enables the frontend team to create new ServiceMonitors and Services which allow Prometheus to be dynamically reconfigured.
 
@@ -190,7 +190,7 @@ spec:
   enableAdminAPI: false
 ```
 
-> If you have RBAC authorization activated, use the RBAC aware [Prometheus manifest][prometheus-manifest] instead.
+> If you have RBAC authorization activated, use the RBAC aware [Prometheus manifest](../../example/rbac/prometheus/prometheus.yaml) instead.
 
 This enables the frontend team to create new PodMonitors which allow Prometheus to be dynamically reconfigured.
 
@@ -217,7 +217,7 @@ spec:
 
 Once this Service is created the Prometheus web UI is available under the node's IP address on port `30900`. The targets page in the web UI now shows that the instances of the example application have successfully been discovered.
 
-> Exposing the Prometheus web UI may not be an applicable solution. Read more about the possibilities of exposing it in the [exposing Prometheus and Alertmanager guide][exposing-prom].
+> Exposing the Prometheus web UI may not be an applicable solution. Read more about the possibilities of exposing it in the [exposing Prometheus and Alertmanager guide](exposing-prometheus-and-alertmanager.md).
 
 ## Expose the Prometheus Admin API
 
@@ -247,14 +247,4 @@ spec:
 
 Further reading:
 
-* [Alerting][alerting-guide] describes using the Prometheus Operator to manage Alertmanager clusters.
-
-
-[alerting-guide]: alerting.md
-[bundle]: ../../bundle.yaml
-[design-doc]: ../design.md
-[exposing-prom]: exposing-prometheus-and-alertmanager.md
-[introducing-operators]: https://web.archive.org/web/20210210032403/https://coreos.com/blog/introducing-operators.html
-[prom-rbac]: ../rbac.md
-[prometheus-manifest]: ../../example/rbac/prometheus/prometheus.yaml
-[rbac-auth]: https://kubernetes.io/docs/reference/access-authn-authz/authorization/
+* [Alerting](alerting.md) describes using the Prometheus Operator to manage Alertmanager clusters.
diff --git a/Documentation/user-guides/monitoring-kubernetes-ingress.md b/Documentation/user-guides/monitoring-kubernetes-ingress.md
index 51bc6ce33..00f3dd960 100644
--- a/Documentation/user-guides/monitoring-kubernetes-ingress.md
+++ b/Documentation/user-guides/monitoring-kubernetes-ingress.md
@@ -5,6 +5,7 @@ This documentation is for an alpha feature.
 </div>
 
 # Monitoring Kubernetes Ingress with Ambassador
+
 [Ambassador](https://getambassador.io/) is a popular open-source API gateway for Kubernetes. Built on [Envoy Proxy](https://envoyproxy.io), Ambassador natively exposes statistics that give you better insight to what is happening at the edge of your Kubernetes cluster. In this guide we will:
 
 * Create a simple Kubernetes application
@@ -17,6 +18,7 @@ This documentation is for an alpha feature.
 * The [Kubernetes command line tool](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
 
 ## Deploy and Expose an Application on Kubernetes
+
 First, we need an application running on Kubernetes for our users to access. You can deploy any application you would like but, for simplicity, we will use a [sample application](https://getambassador.io/user-guide/getting-started#3-creating-your-first-service) provided by the Ambassador team.
 
 We can quickly deploy this application using `kubectl`:
@@ -38,60 +40,64 @@ Now that we have an application running in Kubernetes, we need to expose it to t
 
 1. Deploy Ambassador to your cluster with `kubectl`:
 
-    ```sh
-    kubectl apply -f https://getambassador.io/yaml/ambassador/ambassador-rbac.yaml
-    ```
-    Ambassador is now running in your cluster and is ready to start routing traffic to your application.
+   ```sh
+   kubectl apply -f https://getambassador.io/yaml/ambassador/ambassador-rbac.yaml
+   ```
+
+   Ambassador is now running in your cluster and is ready to start routing traffic to your application.
 
 2. Expose Ambassador to the internet.
 
-    ```sh
-    kubectl apply -f https://getambassador.io/yaml/ambassador/ambassador-service.yaml
-    ```
-    This will create a `LoadBalancer` service in Kubernetes which will automatically create a cloud load balancer if you are running in cloud-managed Kubernetes.
+   ```sh
+   kubectl apply -f https://getambassador.io/yaml/ambassador/ambassador-service.yaml
+   ```
 
-    Kubernetes will automatically assign the load balancer's IP address as the `EXTERNAL_IP` of the service. You can view this with `kubectl`:
+   This will create a `LoadBalancer` service in Kubernetes which will automatically create a cloud load balancer if you are running in cloud-managed Kubernetes.
 
-    ```console
-    $ kubectl get svc ambassador
+   Kubernetes will automatically assign the load balancer's IP address as the `EXTERNAL_IP` of the service. You can view this with `kubectl`:
 
-    NAME         TYPE           CLUSTER-IP      EXTERNAL-IP      PORT(S)       AGE
-    ambassador   LoadBalancer   10.96.110.170   34.233.165.XXX   80:33241/TCP  87m
-    ```
-    **Note:** If you are running in a different Kubernetes environment that does not automatically create a load balancer (like minikube), you can still access Ambassador using the `NodePort` of the service (33241 in this example).
+   ```console
+   $ kubectl get svc ambassador
+
+   NAME         TYPE           CLUSTER-IP      EXTERNAL-IP      PORT(S)       AGE
+   ambassador   LoadBalancer   10.96.110.170   34.233.165.XXX   80:33241/TCP  87m
+   ```
+
+   **Note:** If you are running in a different Kubernetes environment that does not automatically create a load balancer (like minikube), you can still access Ambassador using the `NodePort` of the service (33241 in this example).
 
 3. Route traffic to your application
 
-    You configure Ambassador to expose your application using [annotations](https://getambassador.io/reference/configuration/) on the Kubernetes service of the application like the one below.
+   You configure Ambassador to expose your application using [annotations](https://getambassador.io/reference/configuration/) on the Kubernetes service of the application like the one below.
 
-    ```yaml
-    ---
-    apiVersion: v1
-    kind: Service
-    metadata:
-      name: tour
-      annotations:
-        getambassador.io/config: |
-          ---
-          apiVersion: ambassador/v1
-          kind: Mapping
-          name: tour-ui_mapping
-          prefix: /
-          service: tour:5000
-    spec:
-      ports:
-      - name: ui
-        port: 5000
-        targetPort: 5000
-      selector:
-        app: tour
-    ```
+   ```yaml
+   ---
+   apiVersion: v1
+   kind: Service
+   metadata:
+     name: tour
+     annotations:
+       getambassador.io/config: |
+         ---
+         apiVersion: ambassador/v1
+         kind: Mapping
+         name: tour-ui_mapping
+         prefix: /
+         service: tour:5000
+   spec:
+     ports:
+     - name: ui
+       port: 5000
+       targetPort: 5000
+     selector:
+       app: tour
+   ```
 
-    The example application above was deployed with a pre-configured annotation to expose it. You can can now access this application using the `EXTERNAL_IP` above and going to http://{AMBASSADOR_EXTERNAL_IP}/ from a web-browser.
+   The example application above was deployed with a pre-configured annotation to expose it. You can can now access this application using the `EXTERNAL_IP` above and going to http://{AMBASSADOR_EXTERNAL_IP}/ from a web-browser.
 
 You now have an application running in Kubernetes and exposed to the internet.
 
 ## Deploy Prometheus
+
 Now that we have an application running and exposed by Ambassador, we need to configure Prometheus to scrape the metrics from Ambassador. The Prometheus Operator gives us a way to deploy and manage Prometheus deployments using Kubernetes-style resources
 
 The Prometheus Operator creates Kubernetes Custom Resource Definitions (CRDs) so we can manage our Prometheus deployment using Kubernetes-style declarative YAML manifests. To deploy the Prometheus Operator, you can clone the [repository](https://github.com/prometheus-operator/prometheus-operator) and follow the instructions in the README. You can also just create it with `kubectl`:
@@ -150,6 +156,7 @@ spec:
 ```sh
 kubectl apply -f prometheus.yaml
 ```
+
 We now have Prometheus running in the cluster and exposed through Ambassador. View the Prometheus UI by going to http://{AMBASSADOR_EXTERNAL_IP}/prometheus/graph from a web browser.
 
 Finally, we need tell Prometheus where to scrape metrics from. The Prometheus Operator easily manages this using a `ServiceMonitor` CRD. To tell Prometheus to scrape metrics from Ambassador's `/metrics` endpoint, we will use the Ambassador admin service and port `ambassador-admin`(8877). Copy the following YAML to a file called `ambassador-monitor.yaml` and apply it with `kubectl`:
@@ -188,10 +195,9 @@ Envoy's metrics data model is remarkably similar to that of Prometheus and uses
 
 **Notable Metrics:**
 
-| Metric Category | Notable Metrics | Description |
-| --------------- | --------------- | ----------- |
-| 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. |
-
+| Metric Category           | Notable Metrics                                                                                                                         | Description                                                                                                                                                                                                                                                       |
+|---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| 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.
diff --git a/Documentation/user-guides/storage.md b/Documentation/user-guides/storage.md
index 181a8a793..0145be676 100644
--- a/Documentation/user-guides/storage.md
+++ b/Documentation/user-guides/storage.md
@@ -9,7 +9,7 @@ To maintain data across deployments and version upgrades, the data must be persi
 
 Kubernetes supports several kinds of storage volumes. The Prometheus Operator works with PersistentVolumeClaims, which support the underlying PersistentVolume to be provisioned when requested.
 
-This document assumes a basic understanding of PersistentVolumes, PersistentVolumeClaims, and their [provisioning][pv-provisioning].
+This document assumes a basic understanding of PersistentVolumes, PersistentVolumeClaims, and their [provisioning](https://kubernetes.io/docs/user-guide/persistent-volumes/#provisioning).
 
 ## Storage Provisioning on AWS
 
@@ -27,7 +27,7 @@ parameters:
 
 > Make sure that AWS as a cloud provider is properly configured with your cluster, or storage provisioning will not work.
 
-For best results, use volumes that have high I/O throughput. These examples use SSD EBS volumes. Read the Kubernetes [Persistent Volumes][persistent-volumes] documentation to adapt this `StorageClass` to your needs.
+For best results, use volumes that have high I/O throughput. These examples use SSD EBS volumes. Read the Kubernetes [Persistent Volumes](https://kubernetes.io/docs/user-guide/persistent-volumes/#aws) documentation to adapt this `StorageClass` to your needs.
 
 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).
 
@@ -46,7 +46,7 @@ spec:
             storage: 40Gi
 ```
 
-> The full documentation of the `storage` field can be found in the [API documentation][api-doc].
+> The full documentation of the `storage` field can be found in the [API documentation](../api.md#storagespec).
 
 When creating the Prometheus object, a PersistentVolumeClaim is used for each Pod in the StatefulSet, and the storage should automatically be provisioned, mounted and used.
 
@@ -101,7 +101,7 @@ To manually provision volumes (as of Kubernetes 1.6.0), you may need to disable
 
 The default StorageClass behavior will override manual storage provisioning, preventing PersistentVolumeClaims from automatically binding to manually created PersistentVolumes.
 
-To override this behavior, you must explicitly create the same resource, but set it to *not* be default. (See the [changelog][volumes-changelog] for more information.)
+To override this behavior, you must explicitly create the same resource, but set it to *not* be default. (See the [changelog](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG.md#volumes) for more information.)
 
 For example, to disable default StorageClasses on a Google Container Engine cluster, create the following StorageClass:
 
@@ -118,9 +118,3 @@ parameters:
   type: pd-ssd
   zone: us-east1-d
 ```
-
-
-[volumes-changelog]: https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.6.md#volumes
-[api-doc]: ../api.md#storagespec
-[pv-provisioning]: https://kubernetes.io/docs/user-guide/persistent-volumes/#provisioning
-[persistent-volumes]: https://kubernetes.io/docs/user-guide/persistent-volumes/#aws
diff --git a/MAINTAINERS.md b/MAINTAINERS.md
index 20db8da0e..b9542dd2d 100644
--- a/MAINTAINERS.md
+++ b/MAINTAINERS.md
@@ -1,17 +1,17 @@
 ## Maintainers of Prometheus Operator organization
 
-| Name                  | Email                       | Kubernetes Slack         | GitHub                                            | Company           |
-|-----------------------|-----------------------------|--------------------------|---------------------------------------------------|-------------------|
-| Frederic Branczyk     | fbranczyk@gmail.com         | `@brancz`                | [@brancz](https://github.com/brancz)              | Polar Signals     |
-| Lili Cosic            | cosiclili@gmail.com         | `@lili`                  | [@lilic](https://github.com/lilic)                | Red Hat           |
-| Matthias Loibl        | mail@matthiasloibl.com      | `@metalmatze`            | [@metalmatze](https://github.com/metalmatze)      | Polar Signals     |
-| Paweł Krupa           | paulfantom@gmail.com        | `@paulfantom`            | [@paulfantom](https://github.com/paulfantom)      | Timescale         |
-| Sergiusz Urbaniak     | sergiusz.urbaniak@gmail.com | `@sur`                   | [@s-urbaniak](https://github.com/s-urbaniak)      | Red Hat           |
-| Simon Pasquier        | pasquier.simon@gmail.com    | `@SimonPasquier`         | [@simonpasquier](https://github.com/simonpasquier)| Red Hat           |
-| Vasily Sliouniaev     |                             | `@vas`                   | [@vsliouniaev](https://github.com/vsliouniaev)    |                   |
-| Kemal Akkoyun         | kakkoyun@gmail.com          | `@kakkoyun`              | [@kakkoyun](https://github.com/kakkoyun)          | Polar Signals     |
-| Damien Grisonnet      | dgrisonn@redhat.com         | `@dgrisonnet`            | [@dgrisonnet](https://github.com/dgrisonnet)      | Red Hat           |
-| Arthur Silva Sens     | arthursens2005@gmail.com    | `@Arthur Silva Sens`     | [@ArthurSens](https://github.com/ArthurSens)      | Gitpod            |
+| Name              | Email                       | Kubernetes Slack     | GitHub                                             | Company       |
+|-------------------|-----------------------------|----------------------|----------------------------------------------------|---------------|
+| Frederic Branczyk | fbranczyk@gmail.com         | `@brancz`            | [@brancz](https://github.com/brancz)               | Polar Signals |
+| Lili Cosic        | cosiclili@gmail.com         | `@lili`              | [@lilic](https://github.com/lilic)                 | Red Hat       |
+| Matthias Loibl    | mail@matthiasloibl.com      | `@metalmatze`        | [@metalmatze](https://github.com/metalmatze)       | Polar Signals |
+| Paweł Krupa       | paulfantom@gmail.com        | `@paulfantom`        | [@paulfantom](https://github.com/paulfantom)       | Timescale     |
+| Sergiusz Urbaniak | sergiusz.urbaniak@gmail.com | `@sur`               | [@s-urbaniak](https://github.com/s-urbaniak)       | Red Hat       |
+| Simon Pasquier    | pasquier.simon@gmail.com    | `@SimonPasquier`     | [@simonpasquier](https://github.com/simonpasquier) | Red Hat       |
+| Vasily Sliouniaev |                             | `@vas`               | [@vsliouniaev](https://github.com/vsliouniaev)     |               |
+| Kemal Akkoyun     | kakkoyun@gmail.com          | `@kakkoyun`          | [@kakkoyun](https://github.com/kakkoyun)           | Polar Signals |
+| Damien Grisonnet  | dgrisonn@redhat.com         | `@dgrisonnet`        | [@dgrisonnet](https://github.com/dgrisonnet)       | Red Hat       |
+| Arthur Silva Sens | arthursens2005@gmail.com    | `@Arthur Silva Sens` | [@ArthurSens](https://github.com/ArthurSens)       | Gitpod        |
 
 Please reach any of the maintainer on slack (#prometheus-operator on https://slack.k8s.io/) or email if you want to help.
 
@@ -21,10 +21,9 @@ We also have some nice souls that help triaging issues and PRs. See [here](https
 
 Full list of triage people is displayed below:
 
-| Name                  | Slack                    | GitHub                                                     | Company         |
-|-----------------------|--------------------------|------------------------------------------------------------|-----------------|
-| Noah Kantrowitz       | `@coderanger`            | [@coderanger](https://github.com/coderanger)                | Geomagical/IKEA |
-
+| Name            | Slack         | GitHub                                       | Company         |
+|-----------------|---------------|----------------------------------------------|-----------------|
+| Noah Kantrowitz | `@coderanger` | [@coderanger](https://github.com/coderanger) | Geomagical/IKEA |
 
 ## How to be maintainer?
 
@@ -36,5 +35,5 @@ Reach us if you have any questions on how to join maintainer team.
 
 ## Notes
 
-This document is heavily inspired by Thanos MANTAINERS.md file. <3 
+This document is heavily inspired by Thanos MANTAINERS.md file. <3
 If you find anything not clear in this file feel free to open an issue or reach out to one of the maintainers.
diff --git a/Makefile b/Makefile
index eec325bc7..3b6e98e01 100644
--- a/Makefile
+++ b/Makefile
@@ -261,13 +261,13 @@ MD_FILES_TO_FORMAT=$(filter-out $(FULLY_GENERATED_DOCS), $(shell find Documentat
 
 .PHONY: docs
 docs: $(MDOX_BINARY)
-	@echo ">> formatting and local/remote links"
-	$(MDOX_BINARY) fmt -l --links.localize.address-regex="https://prometheus-operator.dev/.*" --links.validate.config-file=$(MDOX_VALIDATE_CONFIG) $(MD_FILES_TO_FORMAT)
+	@echo ">> formatting and local/remote link check"
+	$(MDOX_BINARY) fmt --soft-wraps -l --links.localize.address-regex="https://prometheus-operator.dev/.*" --links.validate.config-file=$(MDOX_VALIDATE_CONFIG) $(MD_FILES_TO_FORMAT)
 
 .PHONY: check-docs
 check-docs: $(MDOX_BINARY)
 	@echo ">> checking formatting and local/remote links"
-	$(MDOX_BINARY) fmt --check -l --links.localize.address-regex="https://prometheus-operator.dev/.*" --links.validate.config-file=$(MDOX_VALIDATE_CONFIG) $(MD_FILES_TO_FORMAT)
+	$(MDOX_BINARY) fmt --soft-wraps --check -l --links.localize.address-regex="https://prometheus-operator.dev/.*" --links.validate.config-file=$(MDOX_VALIDATE_CONFIG) $(MD_FILES_TO_FORMAT)
 
 ###########
 # Testing #
diff --git a/README.md b/README.md
index f2a809a12..c40e9d575 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,5 @@
 # Prometheus Operator
+
 [![Build Status](https://github.com/prometheus-operator/prometheus-operator/workflows/ci/badge.svg)](https://github.com/prometheus-operator/prometheus-operator/actions)
 [![Go Report Card](https://goreportcard.com/badge/prometheus-operator/prometheus-operator "Go Report Card")](https://goreportcard.com/report/prometheus-operator/prometheus-operator)
 [![Slack](https://img.shields.io/badge/join%20slack-%23prometheus--operator-brightgreen.svg)](http://slack.k8s.io/)
@@ -10,7 +11,7 @@ Note: Project was previously known as coreos/prometheus-operator.
 ## Overview
 
 The Prometheus Operator provides [Kubernetes](https://kubernetes.io/) native deployment and management of
-[Prometheus](https://prometheus.io/) and related monitoring components.  The purpose of this project is to
+[Prometheus](https://prometheus.io/) and related monitoring components. The purpose of this project is to
 simplify and automate the configuration of a Prometheus based monitoring stack for Kubernetes clusters.
 
 The Prometheus operator includes, but is not limited to, the following features:
@@ -29,15 +30,18 @@ For an introduction to the Prometheus Operator, see the [getting started](https:
 ## Prometheus Operator vs. kube-prometheus vs. community helm chart
 
 ### Prometheus Operator
+
 The Prometheus Operator uses Kubernetes [custom resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) to simplify the deployment and configuration of Prometheus, Alertmanager, and related monitoring components.
 
 ### kube-prometheus
+
 [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus) provides example configurations for a complete cluster monitoring
-stack based on Prometheus and the Prometheus Operator.  This includes deployment of multiple Prometheus and Alertmanager instances,
+stack based on Prometheus and the Prometheus Operator. This includes deployment of multiple Prometheus and Alertmanager instances,
 metrics exporters such as the node_exporter for gathering node metrics, scrape target configuration linking Prometheus to various
 metrics endpoints, and example alerting rules for notification of potential issues in the cluster.
 
 ### helm chart
+
 The [prometheus-community/kube-prometheus-stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack)
 helm chart provides a similar feature set to kube-prometheus. This chart is maintained by the Prometheus community.
 For more information, please see the [chart's readme](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack#kube-prometheus-stack)
@@ -98,10 +102,10 @@ For more information on this feature, see the [user guide](Documentation/user-gu
 ## Quickstart
 
 **Note:** this quickstart does not provision an entire monitoring stack; if that is what you are looking for,
-see the [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus) project.  If you want the whole stack,
+see the [kube-prometheus](https://github.com/prometheus-operator/kube-prometheus) project. If you want the whole stack,
 but have already applied the `bundle.yaml`, delete the bundle first (`kubectl delete -f bundle.yaml`).
 
-To quickly try out _just_ the Prometheus Operator inside a cluster, **choose a release** and run the following command:
+To quickly try out *just* the Prometheus Operator inside a cluster, **choose a release** and run the following command:
 
 ```sh
 kubectl apply -f bundle.yaml
@@ -172,15 +176,14 @@ kubectl delete --ignore-not-found customresourcedefinitions \
 
 1. `kind create cluster --image=kindest/node:<latest>`. e.g `v1.16.2` version.
 2. `kubectl cluster-info --context kind-kind`. kind version >= 0.6.x
-3. `make image` - build Prometheus Operator  docker image locally.
+3. `make image` - build Prometheus Operator docker image locally.
 4. `for n in "operator" "config-reloader"; do kind load docker-image "quay.io/prometheus-operator/prometheus-$n:$(git rev-parse --short HEAD)"; done` - publish
-built locally images to be accessible inside kind.
+   built locally images to be accessible inside kind.
 5. `make test-e2e`
 
 #### Running *end-to-end* tests on local minikube cluster:
 
-1. `minikube start --kubernetes-version=v1.10.0 --memory=4096
-   --extra-config=apiserver.authorization-mode=RBAC`
+1. `minikube start --kubernetes-version=v1.10.0 --memory=4096 --extra-config=apiserver.authorization-mode=RBAC`
 2. `eval $(minikube docker-env) && make image` - build Prometheus Operator
    docker image on minikube's docker
 3. `make test-e2e`
@@ -188,25 +191,22 @@ built locally images to be accessible inside kind.
 ## Contributing
 
 Many files (documentation, manifests, ...) in this repository are
-auto-generated. E.g. `bundle.yaml` originates from the _Jsonnet_ files in
+auto-generated. E.g. `bundle.yaml` originates from the *Jsonnet* files in
 `/jsonnet/prometheus-operator`. Before proposing a pull request:
 
 1. Commit your changes.
 2. Run `make generate`.
 3. Commit the generated changes.
 
-
 ## Security
 
 If you find a security vulnerability related to the Prometheus Operator, please
 do not report it by opening a GitHub issue, but instead please send an e-mail to
 the maintainers of the project found in the [MAINTAINERS.md](MAINTAINERS.md) file.
 
-[operator-vs-kube]: https://github.com/prometheus-operator/prometheus-operator/issues/2510#issuecomment-476692399
-
 ## Troubleshooting
 
-Check the [troubleshooting documentation](Documentation/troubleshooting.md) for 
+Check the [troubleshooting documentation](Documentation/troubleshooting.md) for
 common issues and frequently asked questions (FAQ).
 
 ## Acknowledgements
diff --git a/RELEASE.md b/RELEASE.md
index 1ea478b43..f1321aa18 100644
--- a/RELEASE.md
+++ b/RELEASE.md
@@ -4,23 +4,23 @@ Following [Prometheus](https://github.com/prometheus/prometheus/blob/master/RELE
 
 Release cadence of first pre-releases being cut is 6 weeks.
 
-| Release | Date of first pre-release (year-month-day) | Release shepherd                            |
-|---------|--------------------------------------------|---------------------------------------------|
-| v0.39   | 2020-05-06                                 | Pawel Krupa (GitHub: @paulfantom)           |
-| v0.40   | 2020-06-17                                 | Lili Cosic (GitHub: @lilic)                 |
-| v0.41   | 2020-07-29                                 | Sergiusz Urbaniak (GitHub: @s-urbaniak)     |
-| v0.42   | 2020-09-09                                 | Matthias Loibl (GitHub: @metalmatze)        |
-| v0.43   | 2020-10-21                                 | Simon Pasquier (GitHub: @simonpasquier)     |
-| v0.44   | 2020-12-02                                 | Pawel Krupa (GitHub: @paulfantom)           |
-| v0.45   | 2021-01-13                                 | Lili Cosic (GitHub: @lilic)                 |
-| v0.46   | 2021-02-24                                 | Sergiusz Urbaniak (GitHub: @s-urbaniak)     |
-| v0.47   | 2021-04-07                                 | Simon Pasquier (GitHub: @simonpasquier)     |
-| v0.48   | 2021-05-19                                 | Matthias Loibl (GitHub: @metalmatze)        |
-| v0.49   | 2021-06-30                                 | Pawel Krupa (GitHub: @paulfantom)           |
-| v0.50   | 2021-08-11                                 | Pawel Krupa (GitHub: @paulfantom)           |
-| v0.51   | 2021-09-22                                 | Simon Pasquier (GitHub: @simonpasquier)     |
-| v0.52   | 2021-11-03                                 | **searching for volunteer**                 |
-| v0.53   | 2021-12-15                                 | **searching for volunteer**                 |
+| Release | Date of first pre-release (year-month-day) | Release shepherd                        |
+|---------|--------------------------------------------|-----------------------------------------|
+| v0.39   | 2020-05-06                                 | Pawel Krupa (GitHub: @paulfantom)       |
+| v0.40   | 2020-06-17                                 | Lili Cosic (GitHub: @lilic)             |
+| v0.41   | 2020-07-29                                 | Sergiusz Urbaniak (GitHub: @s-urbaniak) |
+| v0.42   | 2020-09-09                                 | Matthias Loibl (GitHub: @metalmatze)    |
+| v0.43   | 2020-10-21                                 | Simon Pasquier (GitHub: @simonpasquier) |
+| v0.44   | 2020-12-02                                 | Pawel Krupa (GitHub: @paulfantom)       |
+| v0.45   | 2021-01-13                                 | Lili Cosic (GitHub: @lilic)             |
+| v0.46   | 2021-02-24                                 | Sergiusz Urbaniak (GitHub: @s-urbaniak) |
+| v0.47   | 2021-04-07                                 | Simon Pasquier (GitHub: @simonpasquier) |
+| v0.48   | 2021-05-19                                 | Matthias Loibl (GitHub: @metalmatze)    |
+| v0.49   | 2021-06-30                                 | Pawel Krupa (GitHub: @paulfantom)       |
+| v0.50   | 2021-08-11                                 | Pawel Krupa (GitHub: @paulfantom)       |
+| v0.51   | 2021-09-22                                 | Simon Pasquier (GitHub: @simonpasquier) |
+| v0.52   | 2021-11-03                                 | **searching for volunteer**             |
+| v0.53   | 2021-12-15                                 | **searching for volunteer**             |
 
 # How to cut a new release
 
@@ -101,7 +101,7 @@ Signed tag with a GPG key is appreciated, but in case you can't add a GPG key to
 
 Our CI pipeline will automatically push the container images to [quay.io](https://quay.io/organization/prometheus-operator).
 
-Go to  https://github.com/prometheus-operator/prometheus-operator/releases/new, associate the new release with the before pushed tag, paste in changes made to `CHANGELOG.md` and click "Publish release".
+Go to https://github.com/prometheus-operator/prometheus-operator/releases/new, associate the new release with the before pushed tag, paste in changes made to `CHANGELOG.md` and click "Publish release".
 
 For patch releases, submit a pull request to merge back the release branch into the `master` branch.
 
diff --git a/SECURITY.md b/SECURITY.md
index a3dfd6d81..af731ce61 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -3,4 +3,3 @@
 If you find a security vulnerability related to the Prometheus Operator, please
 do not report it by opening a GitHub issue, but instead please send an e-mail to
 the maintainers of the project found in the [MAINTAINERS.md](MAINTAINERS.md) file.
-
diff --git a/code-of-conduct.md b/code-of-conduct.md
index 6d9e19813..97b47b0ce 100644
--- a/code-of-conduct.md
+++ b/code-of-conduct.md
@@ -33,7 +33,7 @@ This code of conduct applies both within project spaces and in public spaces
 when an individual is representing the project or its community.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting a project maintainer listed in the MAINTAINERS.md file. 
+reported by contacting a project maintainer listed in the MAINTAINERS.md file.
 
 This Code of Conduct is adapted from the Contributor Covenant
 (http://contributor-covenant.org), version 1.2.0, available at
diff --git a/governance.md b/governance.md
index cdc950de4..2174c0afc 100644
--- a/governance.md
+++ b/governance.md
@@ -4,18 +4,18 @@ This document describes the rules and governance of the project. It is a slightl
 
 It is meant to be followed by all the developers of the Prometheus Operator project and the Prometheus Operator community. Common terminology used in this governance document are listed below:
 
-* **Maintainers Team**: A core Prometheus Operator team that have owner access to https://github.com/prometheus-operator organization and all projects within it. Current list is available [here][maintainers-doc].
+* **Maintainers Team**: A core Prometheus Operator team that have owner access to https://github.com/prometheus-operator organization and all projects within it. Current list is available [here](MAINTAINERS.md).
 
 * **Triage Team**: Contributors who does not belong to Maintainer's team, but has `Triage` GitHub role on [Prometheus Operator](https://github.com/prometheus-operator) repository allowing to change GitHub issues and PRs statuses and labels.
-They are listed [here](https://github.com/prometheus-operator/prometheus-operator/blob/master/MAINTAINERS.md#triage).
+  They are listed [here](https://github.com/prometheus-operator/prometheus-operator/blob/master/MAINTAINERS.md#triage).
 
-* **The Prometheus Operator project**: The sum of all activities performed under the [prometheus-operator organization on GitHub][gh], concerning one or more repositories or the community.
+* **The Prometheus Operator project**: The sum of all activities performed under the [prometheus-operator organization on GitHub](https://github.com/prometheus-operator), concerning one or more repositories or the community.
 
-Both Triage and Maintainers are part of [`prometheus-operator-team@googlegroups.com`][team] email list.
+Both Triage and Maintainers are part of [`prometheus-operator-team@googlegroups.com`](https://groups.google.com/forum/#!forum/prometheus-operator-team) email list.
 
 ## Values
 
-The Prometheus Operator developers and community are expected to follow the values defined in the [Code of Conduct][coc].
+The Prometheus Operator developers and community are expected to follow the values defined in the [Code of Conduct](code-of-conduct.md).
 
 Furthermore, the Prometheus Operator community strives for kindness, giving feedback effectively, and building a welcoming environment. The Prometheus Operator developers generally decide by consensus and only resort to conflict resolution by a majority vote if consensus cannot be reached.
 
@@ -26,22 +26,22 @@ Furthermore, the Prometheus Operator community strives for kindness, giving feed
 Team member status may be given to those who have made ongoing contributions to the Prometheus Operator project for at least 3 months.
 This is usually in the form of code improvements, pull-request reviews, issue triaging or notable work on documentation, but organizing events or user support could also be taken into account.
 
-New members may be proposed by any existing Maintainer by email to [prometheus-operator-team][team]. It is highly desirable to reach consensus about acceptance of a new member.
+New members may be proposed by any existing Maintainer by email to [prometheus-operator-team](https://groups.google.com/forum/#!forum/prometheus-operator-team). It is highly desirable to reach consensus about acceptance of a new member.
 However, the proposal is ultimately voted on by a formal [supermajority vote](#supermajority-vote) of Team Maintainers.
 
 If the new member proposal is accepted, the proposed team member should be contacted privately via email to confirm or deny their acceptance of team membership.
-This email will also be CC'd to [prometheus-operator-team][team] for record-keeping purposes.
+This email will also be CC'd to [prometheus-operator-team](https://groups.google.com/forum/#!forum/prometheus-operator-team) for record-keeping purposes.
 
 If they choose to accept, the following steps are taken:
 
-* Maintainer is added to the [GitHub organization][gh] as _Owner_.
-* Maintainer is added to the [prometheus-operator-team][team].
-* Maintainer is added to the list of team members [here][maintainers-doc]
-* New maintainer is announced on the [Prometheus Operator Twitter][twitter] by an existing team member.
+* Maintainer is added to the [GitHub organization](https://github.com/prometheus-operator) as *Owner*.
+* Maintainer is added to the [prometheus-operator-team](https://groups.google.com/forum/#!forum/prometheus-operator-team).
+* Maintainer is added to the list of team members [here](MAINTAINERS.md)
+* New maintainer is announced on the [Prometheus Operator Twitter](https://twitter.com/PromOperator) by an existing team member.
 
-Team members may retire at any time by emailing [prometheus-operator-team@googlegroups.com][team].
+Team members may retire at any time by emailing [prometheus-operator-team@googlegroups.com](https://groups.google.com/forum/#!forum/prometheus-operator-team).
 
-Team members can be removed by [supermajority vote](#supermajority-vote) on [prometheus-operator-team@googlegroups.com][team]. For this vote, the member in question is not eligible to vote and does not count towards the quorum.
+Team members can be removed by [supermajority vote](#supermajority-vote) on [prometheus-operator-team@googlegroups.com](https://groups.google.com/forum/#!forum/prometheus-operator-team). For this vote, the member in question is not eligible to vote and does not count towards the quorum.
 
 Upon death of a member, their team membership ends automatically.
 
@@ -49,29 +49,29 @@ Upon death of a member, their team membership ends automatically.
 
 Triage team has similar rules, however the contributions made to the projects does not need to be as significant as expected by potential maintainer.
 
-New members as well may be proposed by any existing Maintainer or Triage person by email to [prometheus-operator-team@googlegroups.com][team]. It is highly desirable to reach consensus about acceptance of a new member.
+New members as well may be proposed by any existing Maintainer or Triage person by email to [prometheus-operator-team@googlegroups.com](https://groups.google.com/forum/#!forum/prometheus-operator-team). It is highly desirable to reach consensus about acceptance of a new member.
 However, the proposal is ultimately voted on by a formal [majority vote](#majority-vote) (in comparison to Maintainer's vote which requires supermajority).
 
 If the new member proposal is accepted, the proposed team member should be contacted privately via email to confirm or deny their acceptance of team membership.
-This email will also be CC'd to [prometheus-operator-team@googlegroups.com][team] for record-keeping purposes.
+This email will also be CC'd to [prometheus-operator-team@googlegroups.com](https://groups.google.com/forum/#!forum/prometheus-operator-team) for record-keeping purposes.
 
 If they choose to accept, the following steps are taken:
 
 * Triage member is added to the [Prometheus Operator project](http://github.com/prometheus-operator/prometheus-operator) with `Triage` access.
-* Triage member is added to the [prometheus-operator-team][team].
-* Triage member is added to the list of Triage members [here][maintainers-doc].
-* New team Triage member are announced on the [Prometheus Operator Twitter][twitter] by an existing team member.
+* Triage member is added to the [prometheus-operator-team](https://groups.google.com/forum/#!forum/prometheus-operator-team).
+* Triage member is added to the list of Triage members [here](MAINTAINERS.md).
+* New team Triage member are announced on the [Prometheus Operator Twitter](https://twitter.com/PromOperator) by an existing team member.
 
-Triage member may retire at any time by emailing [prometheus-operator-team@googlegroups.com][team].
+Triage member may retire at any time by emailing [prometheus-operator-team@googlegroups.com](https://groups.google.com/forum/#!forum/prometheus-operator-team).
 
-Triage member can be removed by [majority vote](#majority-vote) on [prometheus-operator-team@googlegroups.com][team]. Only Maintainers team has right to vote.
+Triage member can be removed by [majority vote](#majority-vote) on [prometheus-operator-team@googlegroups.com](https://groups.google.com/forum/#!forum/prometheus-operator-team). Only Maintainers team has right to vote.
 
 Upon death of a member, their Triage team membership ends automatically.
 
 ### Technical decisions
 
 Smaller technical decisions are made informally and [lazy consensus](#consensus) is assumed. Technical decisions that span multiple parts of the Prometheus Operator project
-should be discussed and made on the [GitHub issues][issues] and in most cases followed by proposal as described [here](https://github.com/prometheus-operator/prometheus-operator/blob/master/CONTRIBUTING.md).
+should be discussed and made on the [GitHub issues](https://github.com/prometheus-operator/prometheus-operator/issues) and in most cases followed by proposal as described [here](https://github.com/prometheus-operator/prometheus-operator/blob/master/CONTRIBUTING.md).
 
 Decisions are usually made by [lazy consensus](#consensus). If no consensus can be reached, the matter may be resolved by [majority vote](#majority-vote).
 
@@ -83,7 +83,7 @@ Any change requires a [supermajority](#supermajority-vote) in favor. Editorial c
 ### Other matters
 
 Any matter that needs a decision, including but not limited to financial matters, may be called to a vote by any Maintainer if they deem it necessary.
-For financial, private, or personnel matters, discussion and voting takes place on the [prometheus-operator-team@googlegroups.com][team]; Otherwise discussion and votes are held in public on the GitHub issues or #prometheus-operator-dev Kubernetes slack channel.
+For financial, private, or personnel matters, discussion and voting takes place on the [prometheus-operator-team@googlegroups.com](https://groups.google.com/forum/#!forum/prometheus-operator-team); Otherwise discussion and votes are held in public on the GitHub issues or #prometheus-operator-dev Kubernetes slack channel.
 
 ## Voting
 
@@ -96,7 +96,7 @@ A vote may be called and closed early if enough votes have come in one way so th
 
 In all cases, all and only [Maintainers](#maintainers-team) are eligible to vote, with the sole exception of the forced removal of a team member, in which said member is not eligible to vote.
 
-Discussion and votes on personnel matters (including but not limited to team membership and maintainership) are held in private on the [prometheus-operator-team@googlegroups.com][team]. All other discussion and votes are held in public on the GitHub issues or #prometheus-operator-dev CNCF slack channel.
+Discussion and votes on personnel matters (including but not limited to team membership and maintainership) are held in private on the [prometheus-operator-team@googlegroups.com](https://groups.google.com/forum/#!forum/prometheus-operator-team). All other discussion and votes are held in public on the GitHub issues or #prometheus-operator-dev CNCF slack channel.
 
 For public discussions, anyone interested is encouraged to participate. Formal power to object or vote is limited to [Maintainers Team](#maintainers-team).
 
@@ -110,7 +110,7 @@ We also encourage any other company interested in helping maintaining Prometheus
 
 ### Consensus
 
-The default decision making mechanism for the Prometheus Operator project is [lazy consensus][lazy]. This means that any decision on technical issues is considered supported by the [team][team] as long as nobody objects.
+The default decision making mechanism for the Prometheus Operator project is [lazy consensus](https://couchdb.apache.org/bylaws.html#lazy). This means that any decision on technical issues is considered supported by the [team](https://groups.google.com/forum/#!forum/prometheus-operator-team) as long as nobody objects.
 
 Silence on any consensus decision is implicit agreement and equivalent to explicit agreement. Explicit agreement may be stated at will.
 
@@ -170,15 +170,15 @@ To become an official member of Maintainers Team, you should make ongoing contri
 At that point, a team member (typically a maintainer of the project) may propose you for membership.
 The discussion about this will be held in private, and you will be informed privately when a decision has been made. A possible, but not required, graduation path is to become a maintainer first.
 
-Should the decision be in favor, your new membership will also be announced on the [Prometheus Operator Twitter][twitter]
+Should the decision be in favor, your new membership will also be announced on the [Prometheus Operator Twitter](https://twitter.com/PromOperator)
 
 ### How do I add a project?
 
-As a team member, propose the new project on the [Prometheus Operator GitHub Issue][issues]. However, currently to maintain project in our organization you have to become Prometheus Operator Maintainers.
+As a team member, propose the new project on the [Prometheus Operator GitHub Issue](https://github.com/prometheus-operator/prometheus-operator/issues). However, currently to maintain project in our organization you have to become Prometheus Operator Maintainers.
 
 ### How do I remove a Maintainer or Triage member?
 
-All members may resign by notifying the [prometheus-operator-team@googlegroups.com][team]. If you think a team member should be removed against their will, propose this to the [prometheus-operator-team@googlegroups.com][team].
+All members may resign by notifying the [prometheus-operator-team@googlegroups.com](https://groups.google.com/forum/#!forum/prometheus-operator-team). If you think a team member should be removed against their will, propose this to the [prometheus-operator-team@googlegroups.com](https://groups.google.com/forum/#!forum/prometheus-operator-team).
 Discussions will be held there in private.
 
 ### Can majority/supermajority vote be done on GitHub PR by just approving PR?
@@ -190,11 +190,3 @@ No,`[VOTE]` email has to be created.
 For majority voting this means that member that did not send a response agree with the proposal.
 
 For supermajority voting team has to wait for all answers.
-
-[twitter]: https://twitter.com/PromOperator
-[issues]: https://github.com/prometheus-operator/prometheus-operator/issues
-[maintainers-doc]: MAINTAINERS.md
-[team]: https://groups.google.com/forum/#!forum/prometheus-operator-team
-[gh]: https://github.com/prometheus-operator
-[coc]: code-of-conduct.md
-[lazy]: https://couchdb.apache.org/bylaws.html#lazy
diff --git a/scripts/go.mod b/scripts/go.mod
index 2bb877353..e8ae9344c 100644
--- a/scripts/go.mod
+++ b/scripts/go.mod
@@ -4,7 +4,7 @@ go 1.15
 
 require (
 	github.com/brancz/gojsontoyaml v0.0.0-20191212081931-bf2969bbd742
-	github.com/bwplotka/mdox v0.2.2-0.20210731105602-946757ef5f98
+	github.com/bwplotka/mdox v0.2.2-0.20210817102948-ffcf1df22cbc
 	github.com/golangci/golangci-lint v1.40.1
 	github.com/google/go-jsonnet v0.17.0
 	github.com/jsonnet-bundler/jsonnet-bundler v0.3.1
diff --git a/scripts/go.sum b/scripts/go.sum
index 789df25da..36660696c 100644
--- a/scripts/go.sum
+++ b/scripts/go.sum
@@ -73,8 +73,8 @@ github.com/GeertJohan/go.incremental v1.0.0/go.mod h1:6fAjUhbVuX1KcMD3c8TEgVUqmo
 github.com/GeertJohan/go.rice v1.0.0/go.mod h1:eH6gbSOAUv07dQuZVnBmoDP8mgsM1rtixis4Tib9if0=
 github.com/GoogleCloudPlatform/cloudsql-proxy v0.0.0-20190418212003-6ac0b49e7197/go.mod h1:aJ4qN3TfrelA6NZ6AXsXRfmEVaYin3EDbSPJrKS8OXo=
 github.com/Knetic/govaluate v3.0.1-0.20171022003610-9aa49832a739+incompatible/go.mod h1:r7JcOSlj0wfOMncg0iLm8Leh48TZaKVeNIfJntJ2wa0=
-github.com/Kunde21/markdownfmt/v2 v2.1.1-0.20210622145915-e6bf3dcd02de h1:VpixUG1dDCCTtgTdSPoxuyzwDqLLt1dXZ5v4Ur0c9PY=
-github.com/Kunde21/markdownfmt/v2 v2.1.1-0.20210622145915-e6bf3dcd02de/go.mod h1:LFJueuHZej/Z7Xhqh/XgClfkDjZiiEBOLVTt1Duq1r0=
+github.com/Kunde21/markdownfmt/v2 v2.1.1-0.20210810103848-727f02f4c51c h1:rnouiLtDKeaWKnxRViK454oCI8jkhWv5fItCvZ9nJOU=
+github.com/Kunde21/markdownfmt/v2 v2.1.1-0.20210810103848-727f02f4c51c/go.mod h1:LFJueuHZej/Z7Xhqh/XgClfkDjZiiEBOLVTt1Duq1r0=
 github.com/Masterminds/goutils v1.1.0/go.mod h1:8cTjp+g8YejhMuvIA5y2vz3BpJxksy863GQaJW2MFNU=
 github.com/Masterminds/semver v1.4.2/go.mod h1:MB6lktGJrhw8PrUyiEoblNEGEQ+RzHPF078ddwwvV3Y=
 github.com/Masterminds/semver v1.5.0 h1:H65muMkzWKEuNDnfl9d70GUjFniHKHRbFPGBuZ3QEww=
@@ -182,8 +182,8 @@ github.com/bombsimon/wsl/v3 v3.3.0 h1:Mka/+kRLoQJq7g2rggtgQsjuI/K5Efd87WX96EWFxj
 github.com/bombsimon/wsl/v3 v3.3.0/go.mod h1:st10JtZYLE4D5sC7b8xV4zTKZwAQjCH/Hy2Pm1FNZIc=
 github.com/brancz/gojsontoyaml v0.0.0-20191212081931-bf2969bbd742 h1:PdvQdwUXiFnSmWsOJcBXLpyH3mJfP2FMPTT3J0i7+8o=
 github.com/brancz/gojsontoyaml v0.0.0-20191212081931-bf2969bbd742/go.mod h1:IyUJYN1gvWjtLF5ZuygmxbnsAyP3aJS6cHzIuZY50B0=
-github.com/bwplotka/mdox v0.2.2-0.20210731105602-946757ef5f98 h1:ngs7TmL/tpcMHye7SfXVQQQQrpb9wysgFguZspqxzRM=
-github.com/bwplotka/mdox v0.2.2-0.20210731105602-946757ef5f98/go.mod h1:OamjXQNkD6dtDz7f0QmcTT3O7W6bpe1SXOb12h2TwUQ=
+github.com/bwplotka/mdox v0.2.2-0.20210817102948-ffcf1df22cbc h1:BkVHkrp8xP2ImhwNkHZHWRF+hzjNI/HlpUC0595PiiU=
+github.com/bwplotka/mdox v0.2.2-0.20210817102948-ffcf1df22cbc/go.mod h1:LQ56NADXiE02c1gvLtmTTFNYCvJFQpZgCU/1+hAYC5U=
 github.com/campoy/embedmd v1.0.0/go.mod h1:oxyr9RCiSXg0M3VJ3ks0UGfp98BpSSGr0kpiX3MzVl8=
 github.com/casbin/casbin/v2 v2.1.2/go.mod h1:YcPU1XXisHhLzuxH9coDNf2FbKpjGlbCg3n9yuLkIJQ=
 github.com/cenkalti/backoff v2.2.1+incompatible/go.mod h1:90ReRw6GdpyfrHakVjL/QHaoyV4aDUVVkXQJJJ3NXXM=