@aigne/doc-smith 0.8.9 → 0.8.10-beta.1

package/agents/generate/user-review-document-structure.mjs

@@ -0,0 +1,168 @@
+import { getActiveRulesForScope } from "../../utils/preferences-utils.mjs";
+
+function formatDocumentStructure(structure) {
+  // Build a tree structure for better display
+  const nodeMap = new Map();
+  const rootNodes = [];
+
+  // First pass: create node map
+  structure.forEach((node) => {
+    nodeMap.set(node.path, {
+      ...node,
+      children: [],
+    });
+  });
+
+  // Second pass: build tree structure
+  structure.forEach((node) => {
+    if (node.parentId) {
+      const parent = nodeMap.get(node.parentId);
+      if (parent) {
+        parent.children.push(nodeMap.get(node.path));
+      } else {
+        rootNodes.push(nodeMap.get(node.path));
+      }
+    } else {
+      rootNodes.push(nodeMap.get(node.path));
+    }
+  });
+
+  function printNode(node, depth = 0) {
+    const INDENT_SPACES = "  ";
+    const FOLDER_ICON = "📁";
+    const FILE_ICON = "📄";
+    const indent = INDENT_SPACES.repeat(depth);
+    const prefix = depth === 0 ? FOLDER_ICON : FILE_ICON;
+
+    console.log(`${indent}${prefix} ${node.title}`);
+
+    if (node.children && node.children.length > 0) {
+      node.children.forEach((child) => {
+        printNode(child, depth + 1);
+      });
+    }
+  }
+
+  return { rootNodes, printNode };
+}
+
+export default async function userReviewDocumentStructure({ documentStructure, ...rest }, options) {
+  // Check if document structure exists
+  if (!documentStructure || !Array.isArray(documentStructure) || documentStructure.length === 0) {
+    console.log("No document structure was generated to review.");
+    return { documentStructure };
+  }
+
+  // Ask user if they want to review the document structure
+  const needReview = await options.prompts.select({
+    message:
+      "Would you like to review the document structure?\n  You can modify titles, reorganize sections, or refine content outlines.",
+    choices: [
+      {
+        name: "Looks good - proceed with current structure",
+        value: "no",
+      },
+      {
+        name: "Review and provide feedback",
+        value: "yes",
+      },
+    ],
+  });
+
+  if (needReview === "no") {
+    return { documentStructure };
+  }
+
+  let currentStructure = documentStructure;
+
+  const MAX_ITERATIONS = 100;
+  let iterationCount = 0;
+  while (iterationCount < MAX_ITERATIONS) {
+    iterationCount++;
+
+    // Print current document structure in a user-friendly format
+    console.log(`\n${"=".repeat(50)}`);
+    console.log("Current Document Structure");
+    console.log("=".repeat(50));
+
+    const { rootNodes, printNode } = formatDocumentStructure(currentStructure);
+
+    if (rootNodes.length === 0) {
+      console.log("No document structure found.");
+    } else {
+      rootNodes.forEach((node) => printNode(node));
+    }
+
+    console.log(`${"=".repeat(50)}\n`);
+
+    // Ask for feedback
+    const feedback = await options.prompts.input({
+      message:
+        "How would you like to improve the structure?\n" +
+        "  • Rename, reorganize, add, or remove sections\n" +
+        "  • Adjust content outlines for clarity\n\n" +
+        "  Press Enter to finish reviewing:",
+    });
+
+    // If no feedback, break the loop
+    if (!feedback?.trim()) {
+      break;
+    }
+
+    // Get the refineDocumentStructure agent
+    const refineAgent = options.context.agents["refineDocumentStructure"];
+    if (!refineAgent) {
+      console.log(
+        "Unable to process your feedback - the structure refinement feature is unavailable.",
+      );
+      console.log("Please try again later or contact support if this continues.");
+      break;
+    }
+
+    // Get user preferences
+    const structureRules = getActiveRulesForScope("structure", []);
+    const globalRules = getActiveRulesForScope("global", []);
+    const allApplicableRules = [...structureRules, ...globalRules];
+    const ruleTexts = allApplicableRules.map((rule) => rule.rule);
+    const userPreferences = ruleTexts.length > 0 ? ruleTexts.join("\n\n") : "";
+
+    try {
+      // Call refineDocumentStructure agent with feedback
+      const result = await options.context.invoke(refineAgent, {
+        ...rest,
+        feedback: feedback.trim(),
+        originalDocumentStructure: currentStructure,
+        userPreferences,
+      });
+
+      if (result.documentStructure) {
+        currentStructure = result.documentStructure;
+      }
+
+      // Check if feedback should be saved as user preference
+      const feedbackRefinerAgent = options.context.agents["checkFeedbackRefiner"];
+      if (feedbackRefinerAgent) {
+        try {
+          await options.context.invoke(feedbackRefinerAgent, {
+            documentStructureFeedback: feedback.trim(),
+            stage: "structure",
+          });
+        } catch (refinerError) {
+          console.warn("Could not save feedback as user preference:", refinerError.message);
+          console.warn("Your feedback was applied but not saved as a preference.");
+        }
+      }
+    } catch (error) {
+      console.error("Error processing your feedback:");
+      console.error(`Type: ${error.name}`);
+      console.error(`Message: ${error.message}`);
+      console.error(`Stack: ${error.stack}`);
+      console.log("\nPlease try rephrasing your feedback or continue with the current structure.");
+      break;
+    }
+  }
+
+  return { documentStructure: currentStructure };
+}
+
+userReviewDocumentStructure.taskTitle = "User review and modify document structure";

package/agents/update/generate-and-translate-document.yaml

@@ -1,6 +1,6 @@
 type: team
 name: generateAndTranslateDocument
-description: Generate document and translate
+description: Generate and translate documents
 skills:
   - ../utils/transform-detail-datasources.mjs
   - type: team
@@ -70,12 +70,12 @@ input_schema:
       type: array
       items:
         type: string
-        description: Included file names
+        description: Included file name patterns
     excludePatterns:
       type: array
       items:
         type: string
-        description: Excluded file names
+        description: Excluded file name patterns
     outputDir:
       type: string
       description: Output directory

package/agents/utils/check-feedback-refiner.mjs

@@ -77,3 +77,5 @@ checkFeedbackRefiner.input_schema = {
     },
   },
 };
+
+checkFeedbackRefiner.taskRenderMode = "collapse";

package/agents/utils/save-docs.mjs

@@ -42,38 +42,32 @@ export default async function saveDocs({
     console.error("Failed to cleanup invalid .md files:", err.message);
   }
 
-  const message = `## ✅ Documentation Generated Successfully!
+  const message = `# ✅ Documentation Generated Successfully!
 
-  Successfully generated **${documentStructure.length}** documents and saved to:
-  \`${docsDir}\`
-  ${projectInfoMessage || ""}
-  ### 🚀 Next Steps
+Generated **${documentStructure.length}** documents and saved to: \`${docsDir}\`
+${projectInfoMessage || ""}
+## 🚀 Next Steps
 
-  1. Publish Documentation
+**Publish Your Documentation**
 
-     \`\`\`bash
-     aigne doc publish
-     \`\`\`
+Generate a shareable preview link for your team:
 
-     Get an online preview link to share with your team
+  \`aigne doc publish\`
 
-  ### 🔧 Optional Improvements
+## 🔧 Optional Actions
 
-  1. Update Specific Documents
+**Update Specific Documents**
 
-     \`\`\`bash
-     aigne doc update
-     \`\`\`
+Regenerate content for individual documents:
 
-     Regenerate content for specific documents
+  \`aigne doc update\`
 
-  2. Provide Structure Feedback
-     \`\`\`bash
-     aigne doc generate --feedback "Your feedback on document structure"
-     \`\`\`
-     Improve the overall documentation structure
+**Refine Document Structure**
+
+Review and improve your documentation organization:
+
+  \`aigne doc generate\`
 
-  ---
   `;
 
   // Shutdown mermaid worker pool to ensure clean exit

package/aigne.yaml

@@ -40,6 +40,7 @@ agents:
   - ./agents/utils/feedback-refiner.yaml
   - ./agents/prefs/index.mjs
   - ./agents/chat/index.yaml
+  - ./agents/generate/user-review-document-structure.mjs
 cli:
   chat: ./agents/chat/index.yaml
   agents:

package/docs/advanced-how-it-works.md

@@ -1,12 +1,14 @@
 # How It Works
 
-AIGNE DocSmith automates documentation using a multi-agent system. Instead of a single AI model, DocSmith orchestrates a pipeline of specialized AI agents, where each agent is an expert in a specific task. This collaborative approach generates structured and detailed documentation directly from your source code.
+AIGNE DocSmith operates on a multi-agent system built within the AIGNE Framework. Instead of a single monolithic process, it orchestrates a pipeline of specialized AI agents, where each agent is responsible for a specific task. This approach allows for a structured and modular process that transforms source code into complete documentation.
 
-At its core, DocSmith operates as a pipeline, processing your source code through several distinct stages, each managed by one or more dedicated AI agents.
+The tool is an integral part of the larger AIGNE ecosystem, which provides a platform for developing and deploying AI applications.
+
+![AIGNE Ecosystem Architecture](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
 
 ## The Documentation Generation Pipeline
 
-The entire process, from analyzing your code to publishing the final documents, follows a structured pipeline. This ensures consistency and allows for targeted refinements at any stage.
+The core of DocSmith is a pipeline that processes your source code through several distinct stages. Each stage is managed by one or more dedicated agents. The primary workflow, typically initiated by the `aigne doc generate` command, can be visualized as follows:
 
 ```d2
 direction: down
@@ -17,23 +19,23 @@ Input: {
 }
 
 Pipeline: {
-  label: "Documentation Generation Pipeline"
+  label: "Core Generation Pipeline"
   shape: rectangle
   grid-columns: 1
   grid-gap: 40
 
   Structure-Planning: {
-    label: "1. Structure Planning\n(reflective-structure-planner)"
+    label: "1. Structure Planning"
     shape: rectangle
   }
 
   Content-Generation: {
-    label: "2. Content Generation\n(content-detail-generator)"
+    label: "2. Content Generation"
     shape: rectangle
   }
 
   Saving: {
-    label: "3. Save Documents\n(save-docs)"
+    label: "3. Save Documents"
     shape: rectangle
   }
 }
@@ -44,7 +46,7 @@ User-Feedback: {
 }
 
 Optional-Steps: {
-  label: "Optional Steps"
+  label: "Optional Post-Generation Steps"
   shape: rectangle
   grid-columns: 2
   grid-gap: 40
@@ -69,31 +71,31 @@ User-Feedback -> Pipeline.Structure-Planning: "Refine Structure"
 User-Feedback -> Pipeline.Content-Generation: "Regenerate Content"
 ```
 
-1.  **Input Analysis**: The process begins with agents like `load-sources` and `load-config`, which gather your source code, configuration files (`aigne.yaml`), and any user-defined rules.
+1.  **Input Analysis**: The process begins when agents load your source code and project configuration (`aigne.yaml`).
 
-2.  **Structure Planning**: The `reflective-structure-planner` agent analyzes the codebase to propose a logical document structure. It considers your specified target audience, rules, and feedback to create an optimal outline.
+2.  **Structure Planning**: An agent analyzes the codebase to propose a logical document structure. It creates an outline based on the project's composition and any specified rules.
 
-3.  **Content Generation**: Once the structure is defined, the `content-detail-generator` and `batch-docs-detail-generator` agents take over. They populate each section of the document plan with detailed content, ensuring technical accuracy and adherence to the defined style.
+3.  **Content Generation**: With the structure in place, content generation agents populate each section of the document plan with detailed text, code examples, and explanations.
 
-4.  **Refinement and Updates**: If you provide feedback using `aigne doc update` or `aigne doc generate --feedback`, the `detail-regenerator` and `feedback-refiner` agents are activated. They update specific documents or adjust the overall structure based on your input.
+4.  **Refinement and Updates**: When you provide input via `aigne doc update` or `aigne doc generate --feedback`, specific agents are activated to update individual documents or adjust the overall structure.
 
-5.  **Translation and Publishing**: Finally, optional agents like `translate` and `publish-docs` handle multi-language translation and publishing to Discuss Kit platforms, completing the end-to-end workflow.
+5.  **Translation and Publishing**: After the primary content is generated, optional agents handle tasks like multi-language translation and publishing the final documentation to a web platform.
 
 ## Key AI Agents
 
-DocSmith's functionality comes from its team of specialized agents. While many agents work behind the scenes, here are some of the key players in the documentation pipeline:
+DocSmith's functionality is provided by a collection of agents defined in the project's configuration. Each agent has a specific role. The table below lists some of the key agents and their functions.
 
-| Agent Role | Primary Function | Governing File(s) |
-|---|---|---|
-| **Structure Planner** | Analyzes source code and rules to generate the overall documentation outline. | `structure-planning.yaml`, `reflective-structure-planner.yaml` |
-| **Content Generator** | Writes detailed content for each individual document section based on the plan. | `content-detail-generator.yaml`, `batch-docs-detail-generator.yaml` |
-| **Translation Agent** | Translates generated documentation into multiple target languages. | `translate.yaml`, `batch-translate.yaml` |
-| **Refinement Agent** | Regenerates or modifies content and structure based on user feedback. | `detail-regenerator.yaml`, `feedback-refiner.yaml` |
-| **Publishing Agent** | Manages the process of publishing documents to Discuss Kit instances. | `publish-docs.mjs`, `team-publish-docs.yaml` |
-| **Configuration Loader** | Reads and interprets the project's configuration and source files. | `load-config.mjs`, `load-sources.mjs` |
+| Functional Role          | Key Agent Files                                      | Description                                                                          |
+| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| **Structure Planning**   | `generate/generate-structure.yaml`                   | Analyzes source code to propose the initial document outline.                        |
+| **Structure Refinement** | `generate/refine-document-structure.yaml`            | Modifies the document structure based on user feedback.                              |
+| **Content Generation**   | `update/batch-generate-document.yaml`, `generate-document.yaml` | Populates the document structure with detailed content for each section.             |
+| **Translation**          | `translate/translate-document.yaml`, `translate-multilingual.yaml` | Translates generated documentation into multiple target languages.                   |
+| **Publishing**           | `publish/publish-docs.mjs`                           | Manages the process of publishing documents to Discuss Kit instances.                |
+| **Data I/O**             | `utils/load-sources.mjs`, `utils/save-docs.mjs`      | Responsible for reading source files and writing the final markdown documents to disk. |
 
-This modular, agent-based architecture makes DocSmith flexible and robust, allowing each step of the process to be optimized independently.
+This agent-based architecture allows each step of the documentation process to be handled by a specialized tool, ensuring a structured and maintainable workflow.
 
 ---
 
-Now that you understand the mechanics behind DocSmith, learn about the measures in place to guarantee output quality in the [Quality Assurance](./advanced-quality-assurance.md) section.
+To understand the measures DocSmith takes to ensure the accuracy and format of the output, proceed to the [Quality Assurance](./advanced-quality-assurance.md) section.

package/docs/advanced-how-it-works.zh.md

@@ -1,61 +1,63 @@
 # 工作原理
 
-AIGNE DocSmith 使用一个多 Agent 系统来自动化文档生成。DocSmith 不使用单个 AI 模型，而是协调一个由专业化 AI Agent 组成的流水线，其中每个 Agent 都是特定任务的专家。这种协作方法可以直接从您的源代码生成结构化且详细的文档。
+AIGNE DocSmith 在 AIGNE 框架内构建的多 Agent 系统上运行。它并非一个单一的整体进程，而是协调一个由专业化 AI Agent 组成的流水线，其中每个 Agent 负责一项特定任务。这种方法实现了一个结构化和模块化的流程，可将源代码转换为完整的文档。
 
-其核心是，DocSmith 作为一个流水线运行，通过几个不同的阶段处理您的源代码，每个阶段都由一个或多个专用的 AI Agent 管理。
+该工具是更庞大的 AIGNE 生态系统的一个组成部分，该生态系统为开发和部署 AI 应用程序提供了一个平台。
+
+![AIGNE 生态系统架构](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
 
 ## 文档生成流水线
 
-从分析代码到发布最终文档的整个过程，都遵循一个结构化的流水线。这确保了一致性，并允许在任何阶段进行有针对性的优化。
+DocSmith 的核心是一个通过几个不同阶段处理源代码的流水线。每个阶段都由一个或多个专用 Agent 管理。主要工作流程通常由 `aigne doc generate` 命令启动，其可视化如下：
 
 ```d2
 direction: down
 
 Input: {
-  label: "Source Code & Config"
+  label: "源代码和配置"
   shape: rectangle
 }
 
 Pipeline: {
-  label: "Documentation Generation Pipeline"
+  label: "核心生成流水线"
   shape: rectangle
   grid-columns: 1
   grid-gap: 40
 
   Structure-Planning: {
-    label: "1. Structure Planning\n(reflective-structure-planner)"
+    label: "1. 结构规划"
     shape: rectangle
   }
 
   Content-Generation: {
-    label: "2. Content Generation\n(content-detail-generator)"
+    label: "2. 内容生成"
     shape: rectangle
   }
 
   Saving: {
-    label: "3. Save Documents\n(save-docs)"
+    label: "3. 保存文档"
     shape: rectangle
   }
 }
 
 User-Feedback: {
-  label: "User Feedback Loop\n(via --feedback flag)"
+  label: "用户反馈循环\n(通过 --feedback 标志)"
   shape: rectangle
 }
 
 Optional-Steps: {
-  label: "Optional Steps"
+  label: "可选的生成后步骤"
   shape: rectangle
   grid-columns: 2
   grid-gap: 40
   
   Translation: {
-    label: "Translate\n(aigne doc translate)"
+    label: "翻译\n(aigne doc translate)"
     shape: rectangle
   }
 
   Publishing: {
-    label: "Publish\n(aigne doc publish)"
+    label: "发布\n(aigne doc publish)"
     shape: rectangle
   }
 }
@@ -65,35 +67,35 @@ Pipeline.Structure-Planning -> Pipeline.Content-Generation
 Pipeline.Content-Generation -> Pipeline.Saving
 Pipeline.Saving -> Optional-Steps
 
-User-Feedback -> Pipeline.Structure-Planning: "Refine Structure"
-User-Feedback -> Pipeline.Content-Generation: "Regenerate Content"
+User-Feedback -> Pipeline.Structure-Planning: "优化结构"
+User-Feedback -> Pipeline.Content-Generation: "重新生成内容"
 ```
 
-1.  **输入分析**：该过程始于 `load-sources` 和 `load-config` 等 Agent，它们会收集您的源代码、配置文件（`aigne.yaml`）以及任何用户定义的规则。
+1.  **输入分析**：当 Agent 加载你的源代码和项目配置（`aigne.yaml`）时，该过程开始。
 
-2.  **结构规划**：`reflective-structure-planner` Agent 会分析代码库，以提出一个逻辑化的文档结构。它会考虑您指定的目标受众、规则和反馈，以创建一个最佳大纲。
+2.  **结构规划**：一个 Agent 会分析代码库，以提出一个逻辑性的文档结构。它会根据项目的构成和任何指定的规则创建一个大纲。
 
-3.  **内容生成**：一旦结构确定，`content-detail-generator` 和 `batch-docs-detail-generator` Agent 就会接管。它们会用详细内容填充文档计划的每个部分，确保技术准确性并遵循定义的风格。
+3.  **内容生成**：结构就位后，内容生成 Agent 会为文档计划的每个部分填充详细的文本、代码示例和解释。
 
-4.  **优化与更新**：如果您使用 `aigne doc update` 或 `aigne doc generate --feedback` 提供反馈，`detail-regenerator` 和 `feedback-refiner` Agent 将被激活。它们会根据您的输入更新特定文档或调整整体结构。
+4.  **优化和更新**：当你通过 `aigne doc update` 或 `aigne doc generate --feedback` 提供输入时，特定的 Agent 会被激活，以更新单个文档或调整整体结构。
 
-5.  **翻译与发布**：最后，像 `translate` 和 `publish-docs` 这样的可选 Agent 会处理多语言翻译和发布到 Discuss Kit 平台的工作，从而完成端到端的工作流。
+5.  **翻译和发布**：主要内容生成后，可选的 Agent 会处理多语言翻译和将最终文档发布到网络平台等任务。
 
 ## 关键 AI Agent
 
-DocSmith 的功能源于其专业化的 Agent 团队。虽然许多 Agent 在幕后工作，但以下是文档生成流水线中的一些关键角色：
+DocSmith 的功能由项目配置中定义的一组 Agent 提供。每个 Agent 都有特定的角色。下表列出了一些关键 Agent 及其功能。
 
-| Agent 角色 | 主要功能 | 相关文件 |
-|---|---|---|
-| **Structure Planner** | 分析源代码和规则，生成整体文档大纲。 | `structure-planning.yaml`, `reflective-structure-planner.yaml` |
-| **Content Generator** | 根据计划为每个独立的文档部分撰写详细内容。 | `content-detail-generator.yaml`, `batch-docs-detail-generator.yaml` |
-| **Translation Agent** | 将生成的文档翻译成多种目标语言。 | `translate.yaml`, `batch-translate.yaml` |
-| **Refinement Agent** | 根据用户反馈重新生成或修改内容和结构。 | `detail-regenerator.yaml`, `feedback-refiner.yaml` |
-| **Publishing Agent** | 管理将文档发布到 Discuss Kit 实例的过程。 | `publish-docs.mjs`, `team-publish-docs.yaml` |
-| **Configuration Loader** | 读取并解析项目的配置文件和源文件。 | `load-config.mjs`, `load-sources.mjs` |
+| 功能角色 | 关键 Agent 文件 | 描述 |
+| --- | --- | --- |
+| **结构规划** | `generate/generate-structure.yaml` | 分析源代码以提出初始文档大纲。 |
+| **结构优化** | `generate/refine-document-structure.yaml` | 根据用户反馈修改文档结构。 |
+| **内容生成** | `update/batch-generate-document.yaml`, `generate-document.yaml` | 为每个部分填充详细内容，以充实文档结构。 |
+| **翻译** | `translate/translate-document.yaml`, `translate-multilingual.yaml` | 将生成的文档翻译成多种目标语言。 |
+| **发布** | `publish/publish-docs.mjs` | 管理将文档发布到 Discuss Kit 实例的过程。 |
+| **数据 I/O** | `utils/load-sources.mjs`, `utils/save-docs.mjs` | 负责读取源文件并将最终的 markdown 文档写入磁盘。 |
 
-这种模块化的、基于 Agent 的架构使得 DocSmith 灵活而强大，允许流程中的每一步都能被独立优化。
+这种基于 Agent 的架构使得文档流程的每一步都由一个专门的工具来处理，从而确保了工作流程的结构化和可维护性。
 
 ---
 
-现在您已经了解了 DocSmith 背后的工作原理，请在 [质量保证](./advanced-quality-assurance.md) 部分了解为保证输出质量而采取的措施。
+要了解 DocSmith 为确保输出的准确性和格式而采取的措施，请继续阅读[质量保证](./advanced-quality-assurance.md)部分。

package/docs/advanced-quality-assurance.md

@@ -40,7 +40,6 @@ QA-Pipeline: {
     shape: rectangle
     grid-columns: 2
     D2-Diagrams: "Validates D2 syntax"
-    Mermaid-Diagrams: "Validates Mermaid syntax"
     Markdown-Linting: "Enforces style rules"
   }
 }
@@ -62,38 +61,36 @@ DocSmith's quality assurance process covers several key areas to ensure document
 
 DocSmith performs several checks to ensure the structural integrity of the content:
 
-- **Incomplete Code Blocks**: Detects code blocks that are opened with ```` ``` ```` but never closed.
+- **Incomplete Code Blocks**: Detects code blocks that are opened with ` ``` ` but never closed.
 - **Missing Line Breaks**: Identifies content that appears on a single line, which may indicate missing newlines.
 - **Content Endings**: Verifies that the content ends with appropriate punctuation (e.g., `.`, `)`, `|`, `>`) to prevent truncated output.
+- **Code Block Indentation**: Analyzes code blocks for inconsistent indentation. If a line of code has less indentation than the opening ` ``` ` marker, it can cause rendering problems. This check helps maintain correct code presentation.
 
 #### Link and Media Integrity
 
-- **Link Integrity**: All relative links within the documentation are validated against the project's `structurePlan` to prevent dead links. This ensures that all internal navigation works as expected. The checker ignores external links (starting with `http://` or `https://`) and `mailto:` links.
+- **Link Integrity**: All relative links within the documentation are validated against the document structure plan to prevent dead links. This ensures that all internal navigation works as expected. The checker ignores external links (starting with `http://` or `https://`) and `mailto:` links.
 
 - **Image Validation**: To avoid broken images, the checker verifies that any local image file referenced in the documentation exists on the file system. It resolves both relative and absolute paths to confirm the file is present. External image URLs and data URLs are not checked.
 
 #### Diagram Syntax Validation
 
-- **D2 Diagrams**: DocSmith validates D2 diagram syntax by sending the code to a rendering service. This process confirms that the diagram can be successfully compiled into an SVG image, catching any syntax errors before they result in a broken graphic.
-
-- **Mermaid Diagrams**: Mermaid diagrams undergo several checks: a primary syntax validation, and specific checks for patterns known to cause rendering issues, such as backticks or numbered lists within node labels, and unquoted special characters that require quotes.
+- **D2 Diagrams**: DocSmith validates D2 diagram syntax by attempting to compile the code into an SVG image. This process catches any syntax errors before they can result in a broken graphic.
 
 #### Formatting and Style Enforcement
 
 - **Table Formatting**: Tables are inspected for mismatched column counts between the header, the separator line, and the data rows. This check prevents common table rendering failures.
 
-- **Code Block Indentation**: The checker analyzes code blocks for inconsistent indentation. If a line of code has less indentation than the opening ```` ``` ```` marker, it can cause rendering problems. This check helps maintain correct code presentation.
-
 - **Markdown Linting**: A built-in linter enforces a consistent Markdown structure. Key rules include:
 
 | Rule ID | Description |
 |---|---|
 | `no-duplicate-headings` | Prevents multiple headings with the same content in the same section. |
 | `no-undefined-references` | Ensures all link and image references are defined. |
+| `no-unused-definitions` | Flags link or image definitions that are not used. |
 | `no-heading-content-indent` | Disallows indentation before heading content. |
 | `no-multiple-toplevel-headings` | Allows only one top-level heading (H1) per document. |
 | `code-block-style` | Enforces a consistent style for code blocks (e.g., using backticks). |
 
 By automating these checks, DocSmith maintains a consistent standard for documentation, ensuring the final output is accurate and navigable.
 
-To learn more about the overall architecture, see the [How It Works](./advanced-how-it-works.md) section.
+To learn more about the overall architecture, see the [How It Works](./advanced-how-it-works.md) section.