Link checker and documentation updates (#264)

* Link checker and documentation updates

* check links script

Author: soumeh01

.github/markdown-link-check.jsonc

@@ -7,4 +7,8 @@
       }
     }
   ],
+  "ignorePatterns": [
+    { "pattern": "^#" },
+    { "pattern": "https://www\\.st\\.com/en/development-tools/hardware-debugger-and-programmer-tools-for-stm32/products\\.html" }
+  ]
 }

DEVELOPMENT.md

@@ -86,3 +86,30 @@ Tool dependencies are recorded in `package.json`:
 ````
 
 The `<version>` must match the tools release version tag.
+
+## Updating documentation
+
+Contributors who make changes to the documentation are encouraged to validate their updates using the
+Markdown linter to ensure consistency and adherence to the project's formatting standards.
+
+Run the following command from the project root:
+
+```bash
+    yarn lint:md
+````
+
+This command checks Markdown files against the linting rules defined in the
+[markdownlint.jsonc](./.github/markdownlint.jsonc) configuration file.
+
+Any formatting issues or deviations from the defined standards will be reported in the console. Addressing these helps
+maintain high-quality, readable, and standardized documentation across the project.
+
+Additionally, if your changes involve updating or adding links within the documentation, you can verify the validity
+of all links by running:
+
+```bash
+    yarn check:links
+````
+
+This will check each link to ensure it is reachable (i.e., returns a 200 OK status). Identifying and correcting broken
+links contributes to a better reader experience and ensures long-term reliability of the documentation.

package.json

@@ -221,7 +221,8 @@
     "test": "jest",
     "package": "vsce package --yarn",
     "tpip:report": "ts-node scripts/tpip-reporter --header docs/tpip-header.md docs/third-party-licenses.json TPIP.md",
-    "lint:md": "markdownlint **/*.md -c ./.github/markdownlint.jsonc -i ./node_modules ./dist ./coverage ./tools"
+    "lint:md": "markdownlint **/*.md -c ./.github/markdownlint.jsonc -i ./node_modules ./dist ./coverage ./tools",
+    "check:links": "ts-node scripts/check-links.ts -i ./node_modules/** -i ./.github/** -c ./.github/markdown-link-check.jsonc"
   },
   "vsce": {
     "yarn": true,
@@ -243,8 +244,10 @@
     "@yarnpkg/lockfile": "^1.1.0",
     "eslint": "^9.26.0",
     "extract-zip": "^2.0.1",
+    "globby": "^13.2.2",
     "jest": "^29.7.0",
     "markdownlint-cli": "^0.45.0",
+    "markdown-link-check": "^3.13.7",
     "node-fetch": "^3.3.2",
     "octokit": "^4.1.3",
     "tempfile": "^5.0.0",

scripts/check-links.ts

@@ -0,0 +1,72 @@
+#!npx ts-node
+
+/**
+ * Copyright 2025 Arm Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { resolve } from "path";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+
+const execFileAsync = promisify(execFile);
+
+async function main() {
+    const argv = yargs(hideBin(process.argv))
+        .option("config", {
+            alias: "c",
+            type: "string",
+            description: "Path to markdown-link-check config file"
+        })
+        .option("ignore", {
+            alias: "i",
+            type: "array",
+            description: "Directories to ignore",
+            default: ["node_modules/**"],
+        })
+        .help()
+        .alias("help", "h")
+        .parseSync();
+
+    const { globby } = await import("globby");
+    const ignorePatterns = (argv.ignore as string[]).map((pattern) => `!${pattern}`);
+    const configPath = resolve(argv.config as string);
+    const mdFiles = await globby(["**/*.md", ...ignorePatterns]);
+
+    if (mdFiles.length === 0) {
+        console.log("No markdown files found.");
+        return;
+    }
+
+    console.log(`Checking ${mdFiles.length} markdown file(s)...`);
+    for (const file of mdFiles) {
+        try {
+            const { stdout } = await execFileAsync(
+                "npx", ["markdown-link-check", "-v", "-c", configPath, file], { shell: true }
+            );
+            console.log(stdout);
+        } catch (err: any) {
+            console.error(`Error in file: ${file}`);
+            console.error(err.stdout || err.message);
+            process.exitCode = 1;
+        }
+    }
+}
+
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});