Add markdownlint workflow (#920)

Author: trask

.github/workflows/build.yml

@@ -72,14 +72,19 @@ jobs:
   link-check:
     uses: ./.github/workflows/reusable-link-check.yml
 
+  markdown-lint-check:
+    uses: ./.github/workflows/reusable-markdown-lint.yml
+
   required-status-check:
     needs:
       - build
       - test-declarative-configuration-run
+      - markdown-lint-check
     runs-on: ubuntu-latest
     if: always()
     steps:
       - if: >
           needs.build.result != 'success' ||
-          needs.test-declarative-configuration-run.result != 'success'
+          needs.test-declarative-configuration-run.result != 'success' ||
+          needs.markdown-lint-check.result != 'success'
         run: exit 1

.github/workflows/reusable-markdown-lint.yml

@@ -0,0 +1,23 @@
+name: Reusable - Markdown lint check
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  markdown-lint-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6.0.0
+
+      - uses: jdx/mise-action@9dc7d5dd454262207dea3ab5a06a3df6afc8ff26 # v3.4.1
+
+      - name: Run markdownlint
+        run: |
+          if ! mise run lint:markdown; then
+            echo "markdownlint failed. To auto-fix many issues locally, run:"
+            echo "  mise run lint:markdown --fix"
+            exit 1
+          fi

.markdownlint.yaml

@@ -0,0 +1,13 @@
+# See https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+# and https://github.com/DavidAnson/markdownlint-cli2
+
+ul-style: false
+line-length: false
+no-duplicate-heading:
+  siblings_only: true
+ol-prefix:
+  style: ordered
+no-inline-html: false
+fenced-code-language: false
+no-trailing-punctuation:
+  punctuation: ".,;:" # allowing exclamation points and question marks at end of sentences

.mise/tasks/lint/markdown.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+#MISE description="Lint markdown files"
+#MISE flag "--fix" help="Automatically fix issues"
+
+set -e
+
+if [ "${usage_fix}" = "true" ]; then
+  markdownlint-cli2 --fix "**/*.md"
+else
+  markdownlint-cli2 "**/*.md"
+fi

CONTRIBUTING.md

@@ -17,6 +17,22 @@ To build the project, run:
 ./gradlew assemble
 ```
 
+## Markdown linting
+
+This repository uses [markdownlint](https://github.com/DavidAnson/markdownlint) via `markdownlint-cli2` managed by [mise](https://github.com/jdx/mise).
+
+To check all Markdown files:
+
+```bash
+mise run lint:markdown
+```
+
+To automatically fix fixable issues:
+
+```bash
+mise run lint:markdown --fix
+```
+
 ## Style guide
 
 This repository follows the OpenTelemetry Java

README.md

@@ -22,75 +22,75 @@ To build the all of examples, run:
 ## Example Modules
 
 - [Using the SDK AutoConfiguration module](autoconfigure)
-    - This module contains a fully functional example of using the autoconfigure
+  - This module contains a fully functional example of using the autoconfigure
       SDK extension module to configure the SDK using only environment
       variables (or system properties).
-    - Note: the `opentelemetry-sdk-extension-autoconfigure` module is still
+  - Note: the `opentelemetry-sdk-extension-autoconfigure` module is still
       experimental at this time.
 - [Manual instrumentation of HTTP](http)
-    - This module provides an example of writing manual instrumentation for
+  - This module provides an example of writing manual instrumentation for
       HTTP, both client and server.
-    - Note: More production-ready instrumentation for HTTP is provided as part
+  - Note: More production-ready instrumentation for HTTP is provided as part
       of the [OpenTelemetry Java Instrumentation](https://github.com/open-telemetry/opentelemetry-java-instrumentation)
       project.
 - [Manual span creation and baggage propagation](manual-tracing)
-    - This module provides an example of manually creating spans using the
+  - This module provides an example of manually creating spans using the
       OpenTelemetry API with the ExtendedTracer.
-    - Additionally, it demonstrates how to use the OpenTelemetry API to
+  - Additionally, it demonstrates how to use the OpenTelemetry API to
       propagate baggage items.
 - [Configuring the Jaeger Exporter](jaeger)
-    - This module contains a fully functional example of configuring the
+  - This module contains a fully functional example of configuring the
       OpenTelemetry SDK to use a Jaeger exporter and send spans to it
       using the OpenTelemetry API.
-    - Note: This example requires Docker to be installed.
+  - Note: This example requires Docker to be installed.
 - [Using the OpenTelemetry Java Agent](javaagent)
-    - This module demonstrates using the OpenTelemetry Java Agent with a simple
+  - This module demonstrates using the OpenTelemetry Java Agent with a simple
       Spring Boot application. Traces, metrics, and logs are exported to a
       collector via OTLP.
 - [Spring native image telemetry with OpenTelemetry Spring Starter](spring-native)
-    - This module demonstrates using the OpenTelemetry Spring Boot starter with a
+  - This module demonstrates using the OpenTelemetry Spring Boot starter with a
       GraalVM native image. Traces and metrics are exported to a collector via OTLP.
 - [Configuring Log Appenders](log-appender)
-    - This module demonstrates how to configure the Log4j and Logback appenders to
+  - This module demonstrates how to configure the Log4j and Logback appenders to
       bridge logs into the OpenTelemetry Log SDK.
 - [Configuring the Logging Exporters](logging)
-    - This module contains a fully functional example of configuring the
+  - This module contains a fully functional example of configuring the
       OpenTelemetry SDK to use a logging exporter.
 - [Exporting application logs using JSON logging in Kubernetes](logging-k8s-stdout-otlp-json)
-    - This module demonstrates how to export application logs using JSON logging
+  - This module demonstrates how to export application logs using JSON logging
       in Kubernetes.
 - [Using the OpenTelemetry metrics API](metrics)
-    - This module contains examples of using the OpenTelemetry metrics APIs.
+  - This module contains examples of using the OpenTelemetry metrics APIs.
 - [Using OpenTelemetry Micrometer shim](micrometer-shim)
-    - This module contains an example of a typical Micrometer setup (Spring Boot
+  - This module contains an example of a typical Micrometer setup (Spring Boot
       with Spring Boot Actuator) configured to bridge metrics to OpenTelemetry
       with the Micrometer shim.
-    - Note: The Micrometer shim is still experimental at this time.
+  - Note: The Micrometer shim is still experimental at this time.
 - [Setting up OTLP exporters](otlp)
-    - OTLP is the OpenTelemetry Protocol. This module demonstrates how to
+  - OTLP is the OpenTelemetry Protocol. This module demonstrates how to
       configure the OTLP exporters and send data to the OpenTelemetry Collector
       using them.
-    - Note: This example requires Docker to be installed.
+  - Note: This example requires Docker to be installed.
 - [Setting up the Prometheus exporter](prometheus)
-    - This module shows how to configure the OpenTelemetry SDK to expose an
+  - This module shows how to configure the OpenTelemetry SDK to expose an
       endpoint that can be scraped by Prometheus.
-    - Note: The Prometheus metric reader is still experimental at this time.
+  - Note: The Prometheus metric reader is still experimental at this time.
 - [Manually Configuring the SDK](sdk-usage)
-    - This module shows some concrete examples of manually configuring the
+  - This module shows some concrete examples of manually configuring the
       OpenTelemetry SDK for tracing.
 - [Telemetry Testing](telemetry-testing)
-    - This module demonstrates how to test OpenTelemetry instrumentation with
+  - This module demonstrates how to test OpenTelemetry instrumentation with
       MockServer.
 - [Setting up the Zipkin exporter](zipkin)
-    - This module contains a fully functional example of configuring the
+  - This module contains a fully functional example of configuring the
       OpenTelemetry SDK to use a Zipkin exporter and send spans to a
       Zipkin backend using the OpenTelemetry API.
-    - Note: This example requires Docker to be installed.
+  - Note: This example requires Docker to be installed.
 - [Declarative Configuration with the OpenTelemetry Java Agent](javaagent-declarative-configuration)
-    - This module demonstrates how to use declarative configuration with the
+  - This module demonstrates how to use declarative configuration with the
       OpenTelemetry Java Agent to configure tracing behavior, including
       excluding specific endpoints from tracing.
-    - Note: This example requires Java 17 or higher.
+  - Note: This example requires Java 17 or higher.
 
 ## Contributing
 

declarative-configuration/README.md

@@ -4,9 +4,9 @@ This example demonstrates how to use [declarative configuration](https://opentel
 
 The configuration file is located at [otel-sdk-config.yaml](./otel-sdk-config.yaml).
 
-# How to Run
+## How to Run
 
-## Prerequisites
+### Prerequisites
 
 * Java 17 or higher is required to run Gradle and build this example
 * Java 8 or higher may be used to run the example once it has been built

doc-snippets/README.md

@@ -1,3 +1,5 @@
-The projects in this directory contain code snippets that are used in the OpenTelemetry 
-documentation in https://opentelemetry.io/docs/languages/java/ and 
-https://opentelemetry.io/docs/zero-code/java/. 
+# Documentation Snippets
+
+The projects in this directory contain code snippets that are used in the OpenTelemetry
+documentation in <https://opentelemetry.io/docs/languages/java/> and
+<https://opentelemetry.io/docs/zero-code/java/>.

doc-snippets/extensions-minimal/README.md

@@ -25,11 +25,13 @@ This module includes OATS (OpenTelemetry Acceptance Tests) to verify the extensi
 ### Prerequisites
 
 Install OATS:
+
 ```bash
 go install github.com/grafana/oats@latest
 ```
 
 Build both the extension and the test application:
+
 ```bash
 cd /path/to/opentelemetry-java-examples
 ./gradlew :doc-snippets:extensions-testapp:jar :doc-snippets:extensions-minimal:shadowJar
@@ -42,4 +44,4 @@ cd doc-snippets/extensions-minimal
 oats oats/oats.yaml
 ```
 
-The test will verify that the custom `custom.processor: "active"` attribute is added to all spans.
+The test will verify that the custom `custom.processor: "active"` attribute is added to all spans.

doc-snippets/extensions-testapp/README.md

@@ -34,4 +34,4 @@ curl http://localhost:8080/hello
 ## Usage with Extensions
 
 This application is designed to be used with the extensions-minimal module to test custom OpenTelemetry extensions.
-See the extensions-minimal readme for details on running OATS tests.
+See the extensions-minimal readme for details on running OATS tests.