test(docs): validate the Kubernetes manifest examples parse

i18n/zh/docusaurus-plugin-content-docs/current/userguide/metax-device/metax-gpu/enable-metax-gpu-schedule.md

@@ -51,13 +51,14 @@ apiVersion: v1
 kind: Pod
 metadata:
   name: gpu-pod1
-  annotations: hami.io/node-scheduler-policy: "spread" # 当此参数设置为 spread 时，调度器将尝试为此任务找到最佳拓扑。
+  annotations:
+    hami.io/node-scheduler-policy: "spread" # 当此参数设置为 spread 时，调度器将尝试为此任务找到最佳拓扑。
 spec:
   containers:
     - name: ubuntu-container
       image: cr.metax-tech.com/public-ai-release/c500/colossalai:2.24.0.5-py38-ubuntu20.04-amd64
       imagePullPolicy: IfNotPresent
-      command: ["sleep","infinity"]
+      command: ["sleep", "infinity"]
       resources:
         limits:
           metax-tech.com/gpu: 1 # 请求 1 个 GPU

i18n/zh/docusaurus-plugin-content-docs/version-v2.9.0/userguide/metax-device/metax-gpu/enable-metax-gpu-schedule.md

@@ -51,7 +51,8 @@ apiVersion: v1
 kind: Pod
 metadata:
   name: gpu-pod1
-  annotations: hami.io/node-scheduler-policy: "spread" # 当此参数设置为 spread 时，调度器将尝试为此任务找到最佳拓扑。
+  annotations:
+    hami.io/node-scheduler-policy: "spread" # 当此参数设置为 spread 时，调度器将尝试为此任务找到最佳拓扑。
 spec:
   containers:
     - name: ubuntu-container

package.json

@@ -65,6 +65,7 @@
   "devDependencies": {
     "@docusaurus/faster": "^3.10.1",
     "@swc/core": "^1.15.47",
+    "js-yaml": "^5.2.3",
     "markdownlint-cli": "^0.49.0",
     "prettier": "^3.9.6",
     "swc-loader": "^0.2.7"

test/doc-manifests.test.mjs

@@ -0,0 +1,63 @@
+/**
+ * Validates the Kubernetes manifest examples embedded in the documentation.
+ *
+ * Many pages show YAML the reader is expected to copy and apply. A block is
+ * treated as a manifest only when it declares both `apiVersion` and `kind`;
+ * bare snippets (a lone `resources:` block) and annotated example lists (which
+ * deliberately repeat keys to contrast valid and invalid requests) are not full
+ * manifests and are skipped. Every manifest that remains must parse as YAML, so
+ * a broken example can't ship.
+ *
+ * Versioned snapshots under versioned_docs/ are frozen and excluded, matching
+ * the lint:md scope.
+ */
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import { loadAll } from "js-yaml";
+
+const roots = ["docs", "tutorials", "i18n/zh/docusaurus-plugin-content-docs/current"];
+
+function markdownFiles(dir, out = []) {
+  // withFileTypes avoids following symlinks into directories.
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, entry.name);
+    if (entry.isDirectory()) markdownFiles(p, out);
+    else if (entry.isFile() && (entry.name.endsWith(".md") || entry.name.endsWith(".mdx")))
+      out.push(p);
+  }
+  return out;
+}
+
+function manifestBlocks(markdown) {
+  const blocks = [];
+  const fence = /```ya?ml\n([\s\S]*?)```/g;
+  let match;
+  while ((match = fence.exec(markdown))) {
+    const body = match[1];
+    if (/^\s*apiVersion:/m.test(body) && /^\s*kind:/m.test(body)) {
+      blocks.push(body);
+    }
+  }
+  return blocks;
+}
+
+describe("documentation manifest examples", () => {
+  it("parse as valid YAML", () => {
+    const failures = [];
+    for (const root of roots) {
+      for (const file of markdownFiles(root)) {
+        manifestBlocks(readFileSync(file, "utf8")).forEach((body, i) => {
+          try {
+            loadAll(body);
+          } catch (err) {
+            failures.push(`${file} (manifest #${i + 1}): ${err.reason || err.message}`);
+          }
+        });
+      }
+    }
+    assert.deepEqual(failures, [], `\n${failures.join("\n")}`);
+  });
+});