CI: run markdown linter on all pages + fixes (#3032)

.github/workflows/check-links.yml

@@ -1,4 +1,4 @@
-name: Check links and refcache # cSpell:ignore refcache
+name: Check links and refcache
 
 on:
   pull_request:

.github/workflows/check-text.yml

@@ -1,11 +1,11 @@
-name: Check text linter rules # cSpell:ignore refcache startswith
+name: Check linter rules
 
 on:
   pull_request:
 
 jobs:
-  check-formatting:
-    name: Check text linter rules
+  text-linter:
+    name: TEXT linter
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -14,3 +14,21 @@ jobs:
           jq 'del(.dependencies) | .devDependencies |= with_entries( select(.key | startswith("textlint")))' package.json > package2.json && mv package2.json package.json
       - run: npm install --ignore-scripts
       - run: npm run check:text
+
+  markdown-linter:
+    name: MARKDOWN linter
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Create and use reduced-dependencies package.json
+        run: |
+          mkdir -p tmp
+          jq '.devDependencies |= with_entries(
+                  select(.key | test("gulp|markdown|through|require|yargs"))
+                )
+                | del(.dependencies)' \
+            package.json > tmp/package-min.json
+          cp tmp/package-min.json package.json
+      - run: npm install --ignore-scripts
+      - run: npm run check:markdown

.markdownlint.json

@@ -0,0 +1,29 @@
+{
+  "no-inline-html": false,
+  "no-emphasis-as-header": false,
+  "no-trailing-punctuation": false,
+  "fenced-code-language": false,
+  "comment": "Disables rules that may conflict with Prettier",
+  "blanks-around-fences": false,
+  "blanks-around-headings": false,
+  "blanks-around-lists": false,
+  "code-fence-style": false,
+  "emphasis-style": false,
+  "heading-start-left": false,
+  "hr-style": false,
+  "line-length": false,
+  "list-indent": false,
+  "list-marker-space": false,
+  "no-blanks-blockquote": false,
+  "no-hard-tabs": false,
+  "no-missing-space-atx": false,
+  "no-missing-space-closed-atx": false,
+  "no-multiple-blanks": false,
+  "no-multiple-space-atx": false,
+  "no-multiple-space-blockquote": false,
+  "no-multiple-space-closed-atx": false,
+  "no-trailing-spaces": false,
+  "ol-prefix": false,
+  "strong-style": false,
+  "ul-indent": false
+}

CONTRIBUTING.md

@@ -74,8 +74,8 @@ npm run serve
 
 The site will be served at [localhost:1313][].
 
-If you need to test Netlify redirects, use the following command, and visit the
-site at [localhost:8888][]:
+If you need to test [Netlify] redirects, use the following command, and visit
+the site at [localhost:8888][]:
 
 ```sh
 npm run serve:netlify

README.md

@@ -13,7 +13,7 @@ missing [let us know][]!
 
 Read on to learn about other ways on how you can help.
 
-## Adding a project to the OpenTelemetry Registry
+## Adding a project to the OpenTelemetry [Registry]
 
 For details, see [Adding to the registry][].
 

content/en/blog/2022/instrument-nginx/index.md

@@ -167,14 +167,14 @@ startup.
 
 Get everything up and running[^1]:
 
-```console
-$ docker compose up
+```sh
+docker compose up
 ```
 
 In another shell, create some traffic:
 
-```console
-$ curl localhost:8080
+```sh
+curl localhost:8080
 ```
 
 In your browser open [localhost:16686][] and search for traces from
@@ -331,8 +331,8 @@ You should now have the following files in your top level directory:
 
 With everything in place, you can now start the demo environment[^1]:
 
-```console
-$ docker compose up
+```sh
+docker compose up
 ```
 
 Within a few moments you should have five docker containers up and running:

content/en/blog/2022/k8s-otel-expose/index.md

@@ -3,9 +3,9 @@ title: Exposing a Collector for cross cluster communication
 linkTitle: Exposing a Collector
 date: 2022-09-08
 author: '[Benedikt Bongartz](https://github.com/frzifus)'
-spelling: cSpell:ignore k8sattributes k8sattributesprocessor K8sattributes 
+spelling: cSpell:ignore k8sattributes k8sattributesprocessor K8sattributes
 spelling: cSpell:ignore K8sprocessor Benedikt Bongartz Keycloak k8sprocessor
-spelling: cSpell:ignore dXNlci0xOjEyMzQK basicauth htpasswd llczt 
+spelling: cSpell:ignore dXNlci0xOjEyMzQK basicauth htpasswd llczt
 spelling: cSpell:ignore oidc rolebinding letsencrypt frzifus
 ---
 
@@ -103,17 +103,16 @@ transmitted traces are stored in a
 Interfaces and behavior may change in the future. Therefore, the versions used
 in this setup are mentioned in brackets.
 
-- A Kubernetes[v1.23.3] cluster with a public address with
-  [ingress-nginx-controller](https://docs.nginx.com/nginx-ingress-controller/)[v1.2.1]
-  installed.
-- A Kubernetes[v1.23.3] edge cluster to create a test cluster. Using
+- A Kubernetes [v1.23.3] cluster with a public address with
+  [ingress-nginx-controller](https://docs.nginx.com/nginx-ingress-controller/)
+  [v1.2.1] installed.
+- A Kubernetes [v1.23.3] edge cluster to create a test cluster. Using
   [Kind](https://kind.sigs.k8s.io/) is recommended.
-- Installed [OpenTelemetry Operator](/docs/collector/getting-started)[v0.58.0]
+- Installed [OpenTelemetry Operator](/docs/collector/getting-started) [v0.58.0]
   on both ends.
-- Installed
-  [Jaeger Operator](https://www.jaegertracing.io/docs/1.37/operator/)[v1.37.0]
-  on your public cluster.
-- Installed [cert-manager](https://cert-manager.io/)[v1.9.1] on your public
+- Installed [Jaeger Operator](https://www.jaegertracing.io/docs/1.37/operator/)
+  [v1.37.0] on your public cluster.
+- Installed [cert-manager](https://cert-manager.io/) [v1.9.1] on your public
   cluster.
 
 ## Remote cluster configuration

content/en/blog/2023/end-user-discussions-02.md

@@ -169,7 +169,7 @@ landing on a particular page which can be tracked with a counter.
 
 The community also discussed these important points:
 
-#### Auto-discovery of sources to collect telemetry data
+### Auto-discovery of sources to collect telemetry data
 
 **Q:** Can OTel Collector automatically discover known sources and collect
 telemetry from them?
@@ -189,7 +189,7 @@ Using
 users should be able to detect and report Kubernetes pod, port, and node
 endpoints via the Kubernetes API.
 
-#### Hosting pattern suggestion of the OTel Collector within Azure
+### Hosting pattern suggestion of the OTel Collector within Azure
 
 **Q:** Are there any suggestions for hosting pattern of the Collector within
 Azure to collect telemetry from Azure App Services and Azure functions?

content/en/blog/2023/end-user-discussions-04.md

@@ -65,7 +65,7 @@ that you incur less cost.
 
 ## Other Important discussion points
 
-#### Maturity model for OpenTelemetry
+### Maturity model for OpenTelemetry
 
 **Q:** Is there some literature available around understanding steps to reach a
 certain maturity level in adopting OTel in your organization? For example, I

content/en/blog/2023/otel-in-focus-02.md

@@ -20,6 +20,8 @@ channel.
 
 Here are the latest updates from our core repositories.
 
+<!-- markdownlint-disable heading-increment -->
+
 ##### [Specification](/docs/specs/otel/)
 
 [v1.18](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.18.0)

content/en/blog/2023/otel-in-focus-03.md

@@ -3,7 +3,7 @@ title: OpenTelemetry in Focus, March 2023
 linkTitle: OTel in Focus 2023/03
 date: 2023-03-31
 author: '[Austin Parker](https://github.com/austinlparker)'
-spelling: cSpell:ignore spanmetricsconnector spanmetricsprocessor 
+spelling: cSpell:ignore spanmetricsconnector spanmetricsprocessor
 spelling: cSpell:ignore Jodd Ktor Webflux
 ---
 
@@ -22,6 +22,8 @@ channel.
 
 Here are the latest updates from our core repositories.
 
+<!-- markdownlint-disable heading-increment -->
+
 ##### [Specification](/docs/specs/otel/)
 
 [Version 1.19](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.19.0)

content/en/blog/2023/otel-in-focus-04.md

@@ -21,6 +21,8 @@ channel.
 
 Here are the latest updates from some of our core repositories.
 
+<!-- markdownlint-disable heading-increment -->
+
 ##### [Specification](/docs/specs/otel/)
 
 [Version 1.20](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.20.0)

content/en/blog/2023/otel-in-focus-05.md

@@ -19,6 +19,8 @@ channel.
 
 Here are the latest updates from some of our core repositories.
 
+<!-- markdownlint-disable heading-increment -->
+
 ##### [Specification](/docs/specs/otel/)
 
 [Version 1.21](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.21.0)

content/en/blog/2023/otel-in-focus-06.md

@@ -3,7 +3,7 @@ title: OpenTelemetry in Focus, June 2023
 linkTitle: OTel in Focus 2023/06
 date: 2023-07-01
 author: '[Austin Parker](https://github.com/austinlparker)'
-spelling: cSpell:ignore scraperhelper Skywalking autoconfigure Logback Quarkus 
+spelling: cSpell:ignore scraperhelper Skywalking autoconfigure Logback Quarkus
 spelling: cSpell:ignore Ktor Farfetch Dyrmishi Inet
 ---
 
@@ -20,6 +20,8 @@ channel.
 
 Here are the latest updates from some of our core repositories.
 
+<!-- markdownlint-disable heading-increment -->
+
 ##### [Specification](/docs/specs/otel/)
 
 [Version 1.22](https://github.com/open-telemetry/opentelemetry-specification/releases/tag/v1.22.0)

content/en/community/marketing-guidelines.md

@@ -86,7 +86,7 @@ concerns.
 Here is how we handle such circumstances:
 
 1. Whomever notices the relevant public (marketing) content should write an
-   email to cncf-opentelemetry-governance@lists.cncf.io and include an
+   email to <cncf-opentelemetry-governance@lists.cncf.io> and include an
    explanation of why the content is problematic, ideally referencing the
    [relevant guidelines above](#goals-and-guidelines).
 1. The OTel Governance Committee (GC) will discuss the case during its next