Check documentation MDX syntax (open-edge-platform#803)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: ivanzati

.github/components-path-filters.yml

@@ -26,3 +26,8 @@ markdown:
   - '!SECURITY.md'
   - '!.github/copilot-instructions.md'
   - .github/workflows/**
+
+documentation:
+  - application/docs/**/*.md
+  - library/docs/**/*.md
+  - .github/workflows/**

.github/workflows/documentation.yml

@@ -0,0 +1,76 @@
+name: documentation
+on:
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  documentation:
+    name: Documentation / MDX checks
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@6044e13b5dc448c55e2357c09f80417699197238 # v6.2.0
+        with:
+          node-version-file: application/ui/.nvmrc
+          package-manager-cache: false
+
+      - name: Validate MDX syntax in Documentation
+        shell: bash
+        run: |
+          echo "Validating MDX/JSX syntax in Documentation files..."
+          WORKDIR=$(mktemp -d)
+          cd "$WORKDIR"
+          npm init -y >/dev/null 2>&1
+          npm install --no-save @mdx-js/mdx@3 remark-comment@1.0.0 fast-glob@3.3.2 >/dev/null 2>&1
+          cat > "$WORKDIR/validate-mdx.mjs" << 'SCRIPT'
+          import { readFile } from "node:fs/promises";
+          import fg from "fast-glob";
+          import { compile } from "@mdx-js/mdx";
+          import remarkComment from 'remark-comment';
+          const workspace = process.env.WORKSPACE;
+          process.chdir(workspace);
+          const files = await fg(["application/docs/**/*.md", "library/docs/**/*.md"], {
+            ignore: [
+              "**/node_modules/**",
+              "**/.git/**",
+              "**/.venv/**",
+              "**/dist/**",
+              "**/build/**",
+              "**/.next/**"
+            ]
+          });
+          console.log(`Found ${files.length} documentation file(s) to validate\n`);
+          let hasErrors = false;
+          let errorCount = 0;
+          for (const file of files) {
+            try {
+              const source = await readFile(file, "utf8");
+              await compile(source, { filepath: file, remarkPlugins: [remarkComment] });
+              process.stdout.write(".");
+            } catch (error) {
+              hasErrors = true;
+              errorCount++;
+              process.stdout.write("\n");
+              console.error(`\n❌ MDX parse error in ${file}:`);
+              console.error(error.message ?? error);
+              if (error.position) {
+                console.error(`   Line ${error.position.start.line}, Column ${error.position.start.column}`);
+              }
+            }
+          }
+          console.log("\n");
+          if (hasErrors) {
+            console.error(`❌ Found ${errorCount} file(s) with MDX/JSX syntax errors`);
+            process.exit(1);
+          } else {
+            console.log(`✅ All ${files.length} file(s) passed MDX validation`);
+          }
+          SCRIPT
+          WORKSPACE="$GITHUB_WORKSPACE" NODE_PATH="$WORKDIR/node_modules" node "$WORKDIR/validate-mdx.mjs"

.github/workflows/main.yml

@@ -94,11 +94,19 @@ jobs:
 
       - uses: DavidAnson/markdownlint-cli2-action@07035fd053f7be764496c0f8d8f9f41f98305101 #v22.0.0
         with:
-          config: ".github/.markdownlint-cli2.jsonc"
+          config: '.github/.markdownlint-cli2.jsonc'
+
+  documentation:
+    name: Documentation markdown checks
+    needs: build-parameters
+    permissions:
+      contents: read
+    if: needs.build-parameters.outputs.components-list && contains(fromJson(needs.build-parameters.outputs.components-list), 'documentation')
+    uses: ./.github/workflows/documentation.yml
 
   success:
     name: Status checks
-    needs: [build-parameters, library, backend, ui, distrib, markdown]
+    needs: [ build-parameters, library, backend, ui, distrib, markdown, documentation ]
     runs-on: ubuntu-latest
     if: ${{ always() && !cancelled() }}
     env:

application/docs/04-concepts/01-architecture.md

@@ -56,7 +56,7 @@ The application is structured as a layered edge server. Each layer has a clear r
 
 <div align="center">
 
-<img src="media/system-architecture.svg" width="1200px" alt="Diagram showing the application system architecture">
+<img src="media/system-architecture.svg" width="1200px" alt="Diagram showing the application system architecture"/>
 </div>
 
 ### API Layer