@aigne/doc-smith 0.6.0 → 0.7.0

package/utils/constants.mjs

@@ -343,79 +343,8 @@ export const SUPPORTED_FILE_EXTENSIONS = [".txt", ".md", ".json", ".yaml", ".yml
 export const CONFLICT_RULES = {
   // Internal conflicts within the same question (multi-select conflicts)
   internalConflicts: {
-    documentPurpose: [
-      {
-        conflictItems: ["getStarted", "findAnswers"],
-        severity: "severe",
-        reason:
-          "Quick start guide (skips complex cases) conflicts with comprehensive API reference (skips beginner explanations)",
-        suggestion: "Choose one as primary goal, or consider creating layered documentation",
-      },
-      {
-        conflictItems: ["getStarted", "understandSystem"],
-        severity: "severe",
-        reason: "30-minute quick start conflicts with deep architectural concept explanations",
-        suggestion: "Consider creating separate quick start and architecture design docs",
-      },
-      {
-        conflictItems: ["completeTasks", "understandSystem"],
-        severity: "moderate",
-        reason:
-          "Practical task guidance and theoretical concept explanation have different focuses",
-        suggestion:
-          "Can be handled through layered document structure: concepts first, then practice",
-      },
-      {
-        conflictItems: ["getStarted", "solveProblems"],
-        severity: "moderate",
-        reason:
-          "Quick start (success cases) and troubleshooting (error scenarios) have different focuses",
-        suggestion: "Create separate tutorial and troubleshooting guides",
-      },
-      {
-        conflictItems: ["findAnswers", "solveProblems"],
-        severity: "moderate",
-        reason: "API reference and diagnostic documentation have different organizational logic",
-        suggestion: "Add troubleshooting section to reference documentation",
-      },
-    ],
-    targetAudienceTypes: [
-      {
-        conflictItems: ["endUsers", "developers"],
-        severity: "severe",
-        reason:
-          "Non-technical users (avoid technical terms) conflict with developers (code-first approach)",
-        suggestion:
-          "Create separate documentation for different audiences or use layered content design",
-      },
-      {
-        conflictItems: ["endUsers", "devops"],
-        severity: "severe",
-        reason: "Non-technical users and operations technical personnel have very different needs",
-        suggestion: "Consider creating separate user guides and operations documentation",
-      },
-      {
-        conflictItems: ["endUsers", "decisionMakers"],
-        severity: "severe",
-        reason:
-          "Non-technical users (simple language) and decision makers (architecture diagrams) have different needs",
-        suggestion: "Create high-level overview for management and user operation manuals",
-      },
-      {
-        conflictItems: ["developers", "decisionMakers"],
-        severity: "moderate",
-        reason:
-          "Developers (code details) and decision makers (high-level overview) have different focus areas",
-        suggestion: "Use progressive disclosure: high-level first, then details",
-      },
-      {
-        conflictItems: ["supportTeams", "decisionMakers"],
-        severity: "moderate",
-        reason:
-          "Support teams (problem diagnosis) and decision makers (architecture decisions) have different focus areas",
-        suggestion: "Include operational considerations in decision documentation",
-      },
-    ],
+    // Note: Most conflicts can be resolved through intelligent document structure planning
+    // Only keeping conflicts that represent fundamental incompatibilities
   },
 
   // Cross-question conflicts (conflicts between different questions)
@@ -483,66 +412,138 @@ export const CONFLICT_RULES = {
         readerKnowledgeLevel: ["emergencyTroubleshooting"],
       },
     },
+  ],
+};
+
+// Conflict resolution rules - defines how to handle conflicts when users select conflicting options
+export const CONFLICT_RESOLUTION_RULES = {
+  // Document purpose conflicts that can be resolved through structure planning
+  documentPurpose: [
     {
-      conditions: {
-        documentPurpose: ["getStarted"],
-        documentationDepth: ["comprehensive"],
-      },
-      severity: "severe",
-      reason: "Quick start tutorials contradict comprehensive coverage documentation",
-      action: "filter",
-      conflictingOptions: {
-        documentationDepth: ["comprehensive"],
-      },
+      conflictItems: ["getStarted", "findAnswers"],
+      strategy: "layered_structure",
+      description: "Quick start and API reference conflict, resolved through layered structure",
     },
     {
-      conditions: {
-        documentPurpose: ["solveProblems"],
-        documentationDepth: ["essentialOnly"],
-      },
-      severity: "moderate",
-      reason:
-        "Troubleshooting usually needs to cover edge cases, basic content alone may not be sufficient",
-      action: "filter",
-      conflictingOptions: {
-        documentationDepth: ["essentialOnly"],
-      },
+      conflictItems: ["getStarted", "understandSystem"],
+      strategy: "separate_sections",
+      description:
+        "Quick start and system understanding conflict, resolved through separate sections",
     },
     {
-      conditions: {
-        targetAudienceTypes: ["endUsers"],
-        documentationDepth: ["comprehensive"],
-      },
-      severity: "moderate",
-      reason: "Non-technical users typically do not need comprehensive technical coverage",
-      action: "filter",
-      conflictingOptions: {
-        documentationDepth: ["comprehensive"],
-      },
+      conflictItems: ["completeTasks", "understandSystem"],
+      strategy: "concepts_then_practice",
+      description:
+        "Task guidance and system understanding conflict, resolved through concepts-then-practice structure",
     },
     {
-      conditions: {
-        targetAudienceTypes: ["decisionMakers"],
-        documentationDepth: ["essentialOnly"],
-      },
-      severity: "moderate",
-      reason: "Decision makers may need more comprehensive information to make decisions",
-      action: "filter",
-      conflictingOptions: {
-        documentationDepth: ["essentialOnly"],
-      },
+      conflictItems: ["findAnswers", "solveProblems"],
+      strategy: "reference_with_troubleshooting",
+      description:
+        "API reference and problem solving conflict, resolved through reference with troubleshooting",
     },
+  ],
+
+  // Target audience conflicts that can be resolved through structure planning
+  targetAudienceTypes: [
     {
-      conditions: {
-        readerKnowledgeLevel: ["completeBeginners"],
-        documentationDepth: ["essentialOnly"],
-      },
-      severity: "moderate",
-      reason: "Complete beginners may need more explanations, not just core content",
-      action: "filter",
-      conflictingOptions: {
-        documentationDepth: ["essentialOnly"],
-      },
+      conflictItems: ["endUsers", "developers"],
+      strategy: "separate_user_paths",
+      description: "End users and developers conflict, resolved through separate user paths",
+    },
+    {
+      conflictItems: ["endUsers", "devops"],
+      strategy: "role_based_sections",
+      description: "End users and DevOps conflict, resolved through role-based sections",
+    },
+    {
+      conflictItems: ["developers", "decisionMakers"],
+      strategy: "progressive_disclosure",
+      description:
+        "Developers and decision makers conflict, resolved through progressive disclosure",
     },
   ],
 };
+
+// Resolution strategy descriptions
+export const RESOLUTION_STRATEGIES = {
+  layered_structure: (items) =>
+    `Detected "${items.join('" and "')}" purpose conflict. Resolution strategy: Create layered document structure
+- Quick start section: Uses "get started" style - optimizes for speed, key steps, working examples, skips complex edge cases
+- API reference section: Uses "find answers" style - comprehensive coverage, searchability, rich examples, skips narrative flow
+- Ensure sections complement rather than conflict with each other`,
+
+  separate_sections: (items) =>
+    `Detected "${items.join('" and "')}" purpose conflict. Resolution strategy: Create separate sections
+- Quick start section: Uses "get started" style - focuses on practical operations, completable within 30 minutes
+- System understanding section: Uses "understand system" style - dedicated to explaining architecture, concepts, design decision rationale
+- Meet different depth needs through clear section separation`,
+
+  concepts_then_practice: (items) =>
+    `Detected "${items.join('" and "')}" purpose conflict. Resolution strategy: Use progressive "concepts-then-practice" structure
+- Concepts section: Uses "understand system" style - first explains core concepts and architecture principles
+- Practice section: Uses "complete tasks" style - then provides specific step guidance and practical scenarios
+- Ensure smooth transition between theory and practice`,
+
+  reference_with_troubleshooting: (items) =>
+    `Detected "${items.join('" and "')}" purpose conflict. Resolution strategy: Integrate troubleshooting into API reference
+- API reference section: Uses "find answers" style - comprehensive feature documentation and parameter descriptions
+- Troubleshooting section: Uses "solve problems" style - add common issues and diagnostic methods for each feature
+- Create dedicated problem diagnosis index for quick location`,
+
+  separate_user_paths: (items) =>
+    `Detected "${items.join('" and "')}" audience conflict. Resolution strategy: Create separate user paths
+- User guide path: Uses "end users" style - simple language, UI operations, screenshot instructions, business outcome oriented
+- Developer guide path: Uses "developers" style - code-first, technical precision, SDK examples, configuration snippets
+- Provide clear path navigation for users to choose appropriate entry point`,
+
+  role_based_sections: (items) =>
+    `Detected "${items.join('" and "')}" audience conflict. Resolution strategy: Organize content by role
+- Create dedicated sections for different roles, each section uses corresponding audience style
+- Ensure content depth and expression precisely match the needs and background of corresponding audience
+- Provide cross-references between sections to facilitate collaborative understanding between roles`,
+
+  progressive_disclosure: (items) =>
+    `Detected "${items.join('" and "')}" audience conflict. Resolution strategy: Use progressive information disclosure
+- Overview level: Uses "decision makers" style - high-level architecture diagrams, decision points, business value
+- Detail level: Uses "developers" style - technical implementation details, code examples, best practices
+- Ensure smooth transition from strategic to tactical`,
+};
+
+export const D2_CONFIG = `vars: {
+  d2-config: {
+    layout-engine: elk
+    theme-id: 0
+    theme-overrides: {
+      N1: "#2AA7A1"
+      N2: "#73808C"
+
+      N4: "#FFFFFF"
+      N5: "#FAFBFC"
+
+      N7: "#ffffff"
+
+      B1: "#8EDDD9"
+      B2: "#C9DCE6"
+      B3: "#EEF9F9"
+      B4: "#F7F8FA"
+      B5: "#FCFDFD"
+      B6: "#E3E9F0"
+
+
+      AA2: "#9EB7C5"
+      AA4: "#E3EBF2"
+      AA5: "#F6FAFC"
+
+      AB4: "#B8F1F6"
+      AB5: "#E3F8FA"
+    }
+  }
+}`;
+
+export const KROKI_CONCURRENCY = 5;
+export const FILE_CONCURRENCY = 3;
+export const TMP_DIR = ".tmp";
+export const TMP_DOCS_DIR = "docs";
+
+export const TMP_ASSETS_DIR = "assets";

package/utils/kroki-utils.mjs

@@ -0,0 +1,162 @@
+import path from "node:path";
+
+import fs from "fs-extra";
+import { glob } from "glob";
+import pMap from "p-map";
+import { joinURL } from "ufo";
+
+import {
+  D2_CONFIG,
+  FILE_CONCURRENCY,
+  KROKI_CONCURRENCY,
+  TMP_ASSETS_DIR,
+  TMP_DIR,
+} from "./constants.mjs";
+import { getContentHash } from "./utils.mjs";
+
+export async function getChart({ chart = "d2", format = "svg", content, strict }) {
+  const baseUrl = "https://chart.abtnet.io";
+
+  try {
+    const res = await fetch(joinURL(baseUrl, chart, format), {
+      method: "POST",
+      body: content,
+      headers: {
+        Accept: "image/svg+xml",
+        "Content-Type": "text/plain",
+      },
+    });
+    if (strict && !res.ok) {
+      throw new Error(`Failed to fetch chart: ${res.status} ${res.statusText}`);
+    }
+
+    const data = await res.text();
+    return data;
+  } catch (err) {
+    if (strict) throw err;
+
+    console.error("Failed to generate chart from:", baseUrl, err);
+    return null;
+  }
+}
+
+export async function getD2Svg({ content, strict = false }) {
+  const svgContent = await getChart({
+    chart: "d2",
+    format: "svg",
+    content,
+    strict,
+  });
+  return svgContent;
+}
+
+// Helper: save d2 svg assets alongside document
+export async function saveD2Assets({ markdown, docsDir }) {
+  const codeBlockRegex = /```d2\n([\s\S]*?)```/g;
+
+  const { replaced } = await runIterator({
+    input: markdown,
+    regexp: codeBlockRegex,
+    replace: true,
+    fn: async ([_match, _code]) => {
+      const assetDir = path.join(docsDir, "../", TMP_ASSETS_DIR, "d2");
+      await fs.ensureDir(assetDir);
+      const d2Content = [D2_CONFIG, _code].join("\n");
+      const fileName = `${getContentHash(d2Content)}.svg`;
+      const svgPath = path.join(assetDir, fileName);
+
+      if (await fs.pathExists(svgPath)) {
+        if (process.env.DEBUG) {
+          console.log("Found assets cache, skipping generation", svgPath);
+        }
+      } else {
+        if (process.env.DEBUG) {
+          console.log("start generate d2 chart", svgPath);
+        }
+        try {
+          const svg = await getD2Svg({ content: d2Content });
+          if (svg) {
+            await fs.writeFile(svgPath, svg, { encoding: "utf8" });
+          }
+        } catch (error) {
+          if (process.env.DEBUG) {
+            console.warn("Failed to generate D2 chart:", error);
+          }
+          return _code;
+        }
+      }
+      return `![](../${TMP_ASSETS_DIR}/d2/${fileName})`;
+    },
+    options: { concurrency: KROKI_CONCURRENCY },
+  });
+
+  return replaced;
+}
+
+export async function beforePublishHook({ docsDir }) {
+  // Example: process each markdown file (replace with your logic)
+  const mdFilePaths = await glob("**/*.md", { cwd: docsDir });
+  await pMap(
+    mdFilePaths,
+    async (filePath) => {
+      let finalContent = await fs.readFile(path.join(docsDir, filePath), { encoding: "utf8" });
+      finalContent = await saveD2Assets({ markdown: finalContent, docsDir });
+
+      await fs.writeFile(path.join(docsDir, filePath), finalContent, { encoding: "utf8" });
+    },
+    { concurrency: FILE_CONCURRENCY },
+  );
+}
+
+async function runIterator({ input, regexp, fn = () => {}, options, replace = false }) {
+  if (!input) return input;
+  const matches = [...input.matchAll(regexp)];
+  const results = [];
+  await pMap(
+    matches,
+    async (...args) => {
+      const resultItem = await fn(...args);
+      results.push(resultItem);
+    },
+    options,
+  );
+
+  let replaced = input;
+  if (replace) {
+    let index = 0;
+    replaced = replaced.replace(regexp, () => {
+      return results[index++];
+    });
+  }
+
+  return {
+    results,
+    replaced,
+  };
+}
+
+export async function checkD2Content({ content }) {
+  await ensureTmpDir();
+  const assetDir = path.join(".aigne", "doc-smith", TMP_DIR, TMP_ASSETS_DIR, "d2");
+  await fs.ensureDir(assetDir);
+  const d2Content = [D2_CONFIG, content].join("\n");
+  const fileName = `${getContentHash(d2Content)}.svg`;
+  const svgPath = path.join(assetDir, fileName);
+  if (await fs.pathExists(svgPath)) {
+    if (process.env.DEBUG) {
+      console.log("Found assets cache, skipping generation", svgPath);
+    }
+    return;
+  }
+
+  const svg = await getD2Svg({ content: d2Content, strict: true });
+  await fs.writeFile(svgPath, svg, { encoding: "utf8" });
+}
+
+export async function ensureTmpDir() {
+  const tmpDir = path.join(".aigne", "doc-smith", TMP_DIR);
+  if (!(await fs.pathExists(path.join(tmpDir, ".gitignore")))) {
+    await fs.ensureDir(tmpDir);
+    await fs.writeFile(path.join(tmpDir, ".gitignore"), "**/*", { encoding: "utf8" });
+  }
+}

package/utils/markdown-checker.mjs

@@ -1,11 +1,14 @@
 import fs from "node:fs";
 import path from "node:path";
+import pMap from "p-map";
 import remarkGfm from "remark-gfm";
 import remarkLint from "remark-lint";
 import remarkParse from "remark-parse";
 import { unified } from "unified";
 import { visit } from "unist-util-visit";
 import { VFile } from "vfile";
+import { KROKI_CONCURRENCY } from "./constants.mjs";
+import { checkD2Content } from "./kroki-utils.mjs";
 import { validateMermaidSyntax } from "./mermaid-validator.mjs";
 
 /**
@@ -67,7 +70,10 @@ function checkDeadLinks(markdown, source, allowedLinks, errorMessages) {
   const linkRegex = /(?<!!)\[([^\]]+)\]\(([^)]+)\)/g;
   let match;
 
-  while ((match = linkRegex.exec(markdown)) !== null) {
+  while (true) {
+    match = linkRegex.exec(markdown);
+    if (match === null) break;
+
     const link = match[2];
     const trimLink = link.trim();
 
@@ -173,7 +179,9 @@ function checkLocalImages(markdown, source, errorMessages, markdownFilePath, bas
   const imageRegex = /!\[([^\]]*)\]\(([^)]+)\)/g;
   let match;
 
-  while ((match = imageRegex.exec(markdown)) !== null) {
+  while (true) {
+    match = imageRegex.exec(markdown);
+    if (match === null) break;
     const imagePath = match[2].trim();
     const altText = match[1];
 
@@ -370,91 +378,102 @@ export async function checkMarkdown(markdown, source = "content", options = {})
 
     // Check mermaid code blocks and other custom validations
     const mermaidChecks = [];
+    const d2ChecksList = [];
     visit(ast, "code", (node) => {
-      if (node.lang && node.lang.toLowerCase() === "mermaid") {
-        // Check for mermaid syntax errors
-        mermaidChecks.push(
-          validateMermaidSyntax(node.value).catch((error) => {
-            const errorMessage = error?.message || String(error) || "Unknown mermaid syntax error";
-
-            // Format mermaid error in check-detail-result style
-            const line = node.position?.start?.line || "unknown";
-            errorMessages.push(
-              `Found Mermaid syntax error in ${source} at line ${line}: ${errorMessage}`,
-            );
-          }),
-        );
-
-        // Check for specific mermaid rendering issues
-        const mermaidContent = node.value;
+      if (node.lang) {
         const line = node.position?.start?.line || "unknown";
 
-        // Check for backticks in node labels
-        const nodeLabelRegex = /[A-Za-z0-9_]+\["([^"]*`[^"]*)"\]|[A-Za-z0-9_]+{"([^}]*`[^}]*)"}/g;
-        let match;
-        match = nodeLabelRegex.exec(mermaidContent);
-        while (match !== null) {
-          const label = match[1] || match[2];
-          errorMessages.push(
-            `Found backticks in Mermaid node label in ${source} at line ${line}: "${label}" - backticks in node labels cause rendering issues in Mermaid diagrams`,
+        if (node.lang.toLowerCase() === "mermaid") {
+          // Check for mermaid syntax errors
+          mermaidChecks.push(
+            validateMermaidSyntax(node.value).catch((error) => {
+              const errorMessage =
+                error?.message || String(error) || "Unknown mermaid syntax error";
+
+              // Format mermaid error in check-detail-result style
+              errorMessages.push(
+                `Found Mermaid syntax error in ${source} at line ${line}: ${errorMessage}`,
+              );
+            }),
           );
-          match = nodeLabelRegex.exec(mermaidContent);
-        }
 
-        // Check for numbered list format in edge descriptions
-        const edgeDescriptionRegex = /--\s*"([^"]*)"\s*-->/g;
-        let edgeMatch;
-        edgeMatch = edgeDescriptionRegex.exec(mermaidContent);
-        while (edgeMatch !== null) {
-          const description = edgeMatch[1];
-          if (/^\d+\.\s/.test(description)) {
+          // Check for specific mermaid rendering issues
+          const mermaidContent = node.value;
+
+          // Check for backticks in node labels
+          const nodeLabelRegex = /[A-Za-z0-9_]+\["([^"]*`[^"]*)"\]|[A-Za-z0-9_]+{"([^}]*`[^}]*)"}/g;
+          let match;
+          match = nodeLabelRegex.exec(mermaidContent);
+          while (match !== null) {
+            const label = match[1] || match[2];
             errorMessages.push(
-              `Unsupported markdown: list - Found numbered list format in Mermaid edge description in ${source} at line ${line}: "${description}" - numbered lists in edge descriptions are not supported`,
+              `Found backticks in Mermaid node label in ${source} at line ${line}: "${label}" - backticks in node labels cause rendering issues in Mermaid diagrams`,
             );
+            match = nodeLabelRegex.exec(mermaidContent);
           }
-          edgeMatch = edgeDescriptionRegex.exec(mermaidContent);
-        }
 
-        // Check for numbered list format in node labels (for both [] and {} syntax)
-        const nodeLabelWithNumberRegex =
-          /[A-Za-z0-9_]+\["([^"]*\d+\.\s[^"]*)"\]|[A-Za-z0-9_]+{"([^}]*\d+\.\s[^}]*)"}/g;
-        let numberMatch;
-        numberMatch = nodeLabelWithNumberRegex.exec(mermaidContent);
-        while (numberMatch !== null) {
-          const label = numberMatch[1] || numberMatch[2];
-          // Check if the label contains numbered list format
-          if (/\d+\.\s/.test(label)) {
-            errorMessages.push(
-              `Unsupported markdown: list - Found numbered list format in Mermaid node label in ${source} at line ${line}: "${label}" - numbered lists in node labels cause rendering issues`,
-            );
+          // Check for numbered list format in edge descriptions
+          const edgeDescriptionRegex = /--\s*"([^"]*)"\s*-->/g;
+          let edgeMatch;
+          edgeMatch = edgeDescriptionRegex.exec(mermaidContent);
+          while (edgeMatch !== null) {
+            const description = edgeMatch[1];
+            if (/^\d+\.\s/.test(description)) {
+              errorMessages.push(
+                `Unsupported markdown: list - Found numbered list format in Mermaid edge description in ${source} at line ${line}: "${description}" - numbered lists in edge descriptions are not supported`,
+              );
+            }
+            edgeMatch = edgeDescriptionRegex.exec(mermaidContent);
           }
-          numberMatch = nodeLabelWithNumberRegex.exec(mermaidContent);
-        }
 
-        // Check for special characters in node labels that should be quoted
-        const nodeWithSpecialCharsRegex = /([A-Za-z0-9_]+)\[([^\]]*[(){}:;,\-\s.][^\]]*)\]/g;
-        let specialCharMatch;
-        specialCharMatch = nodeWithSpecialCharsRegex.exec(mermaidContent);
-        while (specialCharMatch !== null) {
-          const nodeId = specialCharMatch[1];
-          const label = specialCharMatch[2];
-
-          // Check if label contains special characters but is not quoted
-          if (!/^".*"$/.test(label)) {
-            // List of characters that typically need quoting
-            const specialChars = ["(", ")", "{", "}", ":", ";", ",", "-", "."];
-            const foundSpecialChars = specialChars.filter((char) => label.includes(char));
-
-            if (foundSpecialChars.length > 0) {
+          // Check for numbered list format in node labels (for both [] and {} syntax)
+          const nodeLabelWithNumberRegex =
+            /[A-Za-z0-9_]+\["([^"]*\d+\.\s[^"]*)"\]|[A-Za-z0-9_]+{"([^}]*\d+\.\s[^}]*)"}/g;
+          let numberMatch;
+          numberMatch = nodeLabelWithNumberRegex.exec(mermaidContent);
+          while (numberMatch !== null) {
+            const label = numberMatch[1] || numberMatch[2];
+            // Check if the label contains numbered list format
+            if (/\d+\.\s/.test(label)) {
               errorMessages.push(
-                `Found unquoted special characters in Mermaid node label in ${source} at line ${line}: "${label}" contains ${foundSpecialChars.join(
-                  ", ",
-                )} - node labels with special characters should be quoted like ${nodeId}["${label}"]`,
+                `Unsupported markdown: list - Found numbered list format in Mermaid node label in ${source} at line ${line}: "${label}" - numbered lists in node labels cause rendering issues`,
               );
             }
+            numberMatch = nodeLabelWithNumberRegex.exec(mermaidContent);
           }
+
+          // Check for special characters in node labels that should be quoted
+          const nodeWithSpecialCharsRegex = /([A-Za-z0-9_]+)\[([^\]]*[(){}:;,\-\s.][^\]]*)\]/g;
+          let specialCharMatch;
           specialCharMatch = nodeWithSpecialCharsRegex.exec(mermaidContent);
+          while (specialCharMatch !== null) {
+            const nodeId = specialCharMatch[1];
+            const label = specialCharMatch[2];
+
+            // Check if label contains special characters but is not quoted
+            if (!/^".*"$/.test(label)) {
+              // List of characters that typically need quoting
+              const specialChars = ["(", ")", "{", "}", ":", ";", ",", "-", "."];
+              const foundSpecialChars = specialChars.filter((char) => label.includes(char));
+
+              if (foundSpecialChars.length > 0) {
+                errorMessages.push(
+                  `Found unquoted special characters in Mermaid node label in ${source} at line ${line}: "${label}" contains ${foundSpecialChars.join(
+                    ", ",
+                  )} - node labels with special characters should be quoted like ${nodeId}["${label}"]`,
+                );
+              }
+            }
+            specialCharMatch = nodeWithSpecialCharsRegex.exec(mermaidContent);
+          }
+        }
+        if (node.lang.toLowerCase() === "d2") {
+          d2ChecksList.push({
+            content: node.value,
+            line,
+          });
         }
+        // TODO: @zhanghan need to check correctness of every code language
       }
     });
 
@@ -505,6 +524,15 @@ export async function checkMarkdown(markdown, source = "content", options = {})
 
     // Wait for all mermaid checks to complete
     await Promise.all(mermaidChecks);
+    await pMap(
+      d2ChecksList,
+      async ({ content, line }) =>
+        checkD2Content({ content }).catch((err) => {
+          const errorMessage = err?.message || String(err) || "Unknown d2 syntax error";
+          errorMessages.push(`Found D2 syntax error in ${source} at line ${line}: ${errorMessage}`);
+        }),
+      { concurrency: KROKI_CONCURRENCY },
+    );
 
     // Run markdown linting rules
     await processor.run(ast, file);