Add markdown action (openhab#19010)

Signed-off-by: Leo Siepel <leosiepel@gmail.com>

Author: lsiepel

.github/markdownlint.yaml

@@ -0,0 +1,39 @@
+# From: https://github.com/openhab/openhab-docs/blob/main/.github/.markdownlint.yaml
+
+default: true
+
+# Expect dash usage for unordered lists
+MD004:
+  style: dash
+
+# Allow long line lengths
+MD013: false
+
+# Allow duplicate headers for different nesting
+MD024:
+  siblings_only: true
+
+# Allow Multiple top level headers in the same document
+MD025: false
+
+# Allow trailing punctuation in headers
+MD026: false
+MD029:
+  style: one
+
+# Allow inline HTML
+MD033: false
+
+# Code block style
+MD046:
+  style: fenced
+
+# Emphasis in underscore
+MD049:
+  style: underscore
+
+# Strong in asterisk
+MD050:
+  style: asterisk
+
+MD060: false

.github/scripts/maven-build

@@ -14,16 +14,58 @@ function print_reactor_summary() {
     cat "$BUILD_LOG" | sed -n "${start},${end}p" | sed 's/\[INFO\] //'
 }
 
+gha_escape() {
+  sed -e 's/%/%25/g' -e 's/\r/%0D/g' -e 's/\n/%0A/g'
+}
+
+emit_markdownlint_annotations() {
+  [[ -f "$BUILD_LOG" ]] || return 0
+
+  while IFS= read -r l; do
+    file=$(echo "$l" | sed -E 's/^([^:]+\.md):.*/\1/')
+    line=$(echo "$l" | sed -E 's/^[^:]+\.md:([0-9]+).*/\1/')
+
+    # Repair path so GitHub can link it (repo-root relative)
+    if [[ ! -f "$file" ]]; then
+      if [[ -f "bundles/$file" ]]; then
+        file="bundles/$file"
+      elif [[ -f "itests/$file" ]]; then
+        file="itests/$file"
+      fi
+    fi
+
+    if echo "$l" | grep -qE '^[^:]+\.md:[0-9]+:[0-9]+ error MD'; then
+      col=$(echo "$l" | sed -E 's/^[^:]+\.md:[0-9]+:([0-9]+) error .*/\1/')
+      rule=$(echo "$l" | sed -E 's/^[^:]+\.md:[0-9]+:[0-9]+ error (MD[^ ]+) .*/\1/')
+      rest=$(echo "$l" | sed -E 's/^[^:]+\.md:[0-9]+:[0-9]+ error MD[^ ]+ (.*)$/\1/')
+      rest_esc=$(printf '%s' "$rest" | gha_escape)
+      echo "::error file=$file,line=$line,col=$col,title=$rule::$rest_esc"
+    else
+      rule=$(echo "$l" | sed -E 's/^[^:]+\.md:[0-9]+ error (MD[^ ]+) .*/\1/')
+      rest=$(echo "$l" | sed -E 's/^[^:]+\.md:[0-9]+ error MD[^ ]+ (.*)$/\1/')
+      rest_esc=$(printf '%s' "$rest" | gha_escape)
+      echo "::error file=$file,line=$line,title=$rule::$rest_esc"
+    fi
+  done < <(
+    grep -aE '\[INFO\] .*\.md:[0-9]+(:[0-9]+)? error MD' "$BUILD_LOG" \
+    | sed -E 's/^.*\[INFO\] //'
+  )
+}
+
 function mvnp() {
-    set -o pipefail # exit build with error when pipes fail
-    local reactor_size=$(find -name "pom.xml" | grep -vE '/src/|/target/' | wc -l)
-    local padding=$(bc -l <<< "scale=0;2*(l($reactor_size)/l(10)+1)")
-    local command=(./mvnw $@)
-    exec "${command[@]}" 2>&1 | # execute, redirect stderr to stdout
-        tee "$BUILD_LOG" | # write output to log
-        stdbuf -oL grep -aE '^\[INFO\] Building .+ \[.+\]$' | # filter progress
-        stdbuf -o0 sed -uE 's/^\[INFO\] Building (.*[^ ])[ ]+\[([0-9]+\/[0-9]+)\]$/\2| \1/' | # prefix project name with progress
-        stdbuf -o0 sed -e :a -e "s/^.\{1,${padding}\}|/ &/;ta" # right align progress with padding
+  set -o pipefail # exit build with error when pipes fail
+  local reactor_size=$(find -name "pom.xml" | grep -vE '/src/|/target/' | wc -l)
+  local padding=$(bc -l <<< "scale=0;2*(l($reactor_size)/l(10)+1)")
+  local command=(bash ./mvnw "$@")
+
+  "${command[@]}" 2>&1 | \ # execute, redirect stderr to stdout
+    tee "$BUILD_LOG" | \ # write output to log
+    stdbuf -oL grep -aE '^\[INFO\] Building .+ \[.+\]$' | \ # filter progress
+    stdbuf -o0 sed -uE 's/^\[INFO\] Building (.*[^ ])[ ]+\[([0-9]+\/[0-9]+)\]$/\2| \1/' | \ # prefix project name with progress
+    stdbuf -o0 sed -e :a -e "s/^.\{1,${padding}\}|/ &/;ta" # right align progress with padding
+
+  # Exit code of Maven is the first command in the pipeline
+  return "${PIPESTATUS[0]}"
 }
 
 function build_all() {
@@ -38,6 +80,8 @@ function build_all() {
     status=$?
     echo
 
+	emit_markdownlint_annotations
+
     if [ $status -eq 0 ]; then
         print_reactor_summary
     else
@@ -104,5 +148,5 @@ function build_based_on_changes() {
     fi
 }
 
-./mvnw -v
+bash ./mvnw -v
 build_based_on_changes

.github/workflows/ci-build.yml

@@ -67,7 +67,7 @@ jobs:
 
       - name: Build
         id: build
-        run: './.github/scripts/maven-build'
+        run: bash './.github/scripts/maven-build'
         env:
           CHANGED_FILES: ${{ steps.files.outputs.all }}
           MAVEN_OPTS: >-

README.md

@@ -85,11 +85,12 @@ mvn clean install karaf:kar -pl :org.openhab.binding.astro
 To improve build times you can add the following options to the command:
 
 | Option                        | Description                                         |
-| ----------------------------- | --------------------------------------------------- |
+|-------------------------------|-----------------------------------------------------|
 | `-DskipChecks`                | Skip the static analysis (Checkstyle, FindBugs)     |
 | `-DskipTests`                 | Skip the execution of tests                         |
 | `-Dmaven.test.skip=true`      | Skip the compilation and execution of tests         |
 | `-Dfeatures.verify.skip=true` | Skip the Karaf feature verification                 |
+| `-Dmarkdownlint.skip=true`    | Skip the Markdown linting                           |
 | `-Dspotless.check.skip=true`  | Skip the Spotless code style checks                 |
 | `-o`                          | Work offline so Maven does not download any updates |
 | `-T 1C`                       | Build in parallel, using 1 thread per core          |

bundles/org.openhab.automation.jsscripting/pom.xml

@@ -47,6 +47,7 @@
         <artifactId>frontend-maven-plugin</artifactId>
         <version>2.0.0</version>
         <configuration>
+          <installDirectory>target/js</installDirectory>
           <nodeVersion>${node.version}</nodeVersion>
           <workingDirectory>target/js</workingDirectory>
         </configuration>

bundles/pom.xml

@@ -526,6 +526,7 @@
   <properties>
     <m2e.jdt.annotationpath>target/dependency</m2e.jdt.annotationpath>
     <dep.noembedding/>
+    <markdownlint.skip>false</markdownlint.skip>
   </properties>
 
   <dependencies>
@@ -784,6 +785,44 @@
           </execution>
         </executions>
       </plugin>
+      <plugin>
+        <groupId>com.github.eirslett</groupId>
+        <artifactId>frontend-maven-plugin</artifactId>
+        <version>2.0.0</version>
+
+        <configuration>
+          <skip>${markdownlint.skip}</skip>
+
+          <!-- Central toolchain for markdownlint (Node 24) -->
+          <installDirectory>${maven.multiModuleProjectDirectory}/target/.mvn/node-markdownlint</installDirectory>
+          <nodeVersion>v24.12.0</nodeVersion>
+
+          <!-- Recommended: pin npm too for reproducibility -->
+          <npmVersion>11.6.2</npmVersion>
+        </configuration>
+
+        <executions>
+          <execution>
+            <id>install-node-and-npm</id>
+            <goals>
+              <goal>install-node-and-npm</goal>
+            </goals>
+            <phase>validate</phase>
+          </execution>
+
+          <execution>
+            <id>markdownlint</id>
+            <goals>
+              <goal>npm</goal>
+            </goals>
+            <phase>validate</phase>
+            <configuration>
+              <workingDirectory>${project.basedir}</workingDirectory>
+              <arguments>exec --yes markdownlint-cli2 -- **/*.md !**/target/** !**/node_modules/** --config ${maven.multiModuleProjectDirectory}/.github/markdownlint.yaml</arguments>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
     </plugins>
   </build>