@aigne/doc-smith 0.8.3 → 0.8.4

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.8.4](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.3...v0.8.4) (2025-09-09)
+
+
+### Bug Fixes
+
+* parse markdown code blocks into custom x-code element ([#89](https://github.com/AIGNE-io/aigne-doc-smith/issues/89)) ([96ea776](https://github.com/AIGNE-io/aigne-doc-smith/commit/96ea7761299b93ea406abe04193f531fc406ccfa))
+* **utils:** update code block regex to support enhanced attributes ([#92](https://github.com/AIGNE-io/aigne-doc-smith/issues/92)) ([bf1fbab](https://github.com/AIGNE-io/aigne-doc-smith/commit/bf1fbabf193e90a83ed6e83e4ff4c5b3b2930477))
+* **ux:** make background transparent for d2 diagrams ([13eed81](https://github.com/AIGNE-io/aigne-doc-smith/commit/13eed81cb6be13c64ad04c41505d9d76f34d54bb))
+* **ux:** make background transparent for d2 diagrams ([#96](https://github.com/AIGNE-io/aigne-doc-smith/issues/96)) ([13eed81](https://github.com/AIGNE-io/aigne-doc-smith/commit/13eed81cb6be13c64ad04c41505d9d76f34d54bb))
+
 ## [0.8.3](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.2...v0.8.3) (2025-09-05)
 
 

package/README.md

@@ -19,9 +19,9 @@ As shown in the diagram, DocSmith integrates seamlessly with other [AIGNE](https
 
 - **Automated Structure Planning:** Intelligently analyzes your codebase to generate a comprehensive and logical document structure.
 - **AI-Powered Content Generation:** Populates the document structure with detailed, high-quality content.
-- **Multi-Language Support:** Seamlessly translates your documentation into 12+ languages including English, Chinese, Japanese, Korean, Spanish, French, German, Portuguese, Russian, Italian, and Arabic.
-- **AIGNE Hub Integration:** Use AIGNE Hub as your LLM provider without needing your own API keys, with easy switching between different large language models.
-- **Discuss Kit Publishing:** Publish documentation to the official platform at [docsmith.aigne.io](https://docsmith.aigne.io/app/) or your own independently deployed Discuss Kit instance.
+- **Multi-Language Support:** Seamlessly translates your documentation into 12 languages including English, Chinese, Japanese, Korean, Spanish, French, German, Portuguese, Russian, Italian, and Arabic.
+- **AIGNE Hub Integration:** Use [AIGNE Hub](https://www.aigne.io/en/hub) as your LLM provider without needing your own API keys, with easy switching between different large language models.
+- **Document Publishing:** Preview your documentation on the official platform at [docsmith.aigne.io](https://docsmith.aigne.io/app/), or publish to your own [Discuss Kit](https://www.arcblock.io/docs/web3-kit/en/discuss-kit) instance for full control.
 - **Document Update Mechanism:** Automatically detects source code changes and updates documentation accordingly.
 - **Individual Document Optimization:** Regenerate and optimize specific documents with targeted feedback.
 
@@ -29,9 +29,81 @@ As shown in the diagram, DocSmith integrates seamlessly with other [AIGNE](https
 
 ### Prerequisites
 
-- Node.js and pnpm
+- Node.js and npm
 - AIGNE CLI
 
+### Node.js Installation
+
+#### Windows
+1. Download Node.js installer from [nodejs.org](https://nodejs.org/)
+2. Run the installer (.msi file)
+3. Follow installation wizard steps
+4. Verify installation: `node --version`
+
+#### macOS
+**Option 1: Using Homebrew (Recommended)**
+```bash
+# Install Homebrew if not already installed
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Install Node.js
+brew install node
+```
+
+**Option 2: Using the Official Installer**
+1. Download the macOS installer from [nodejs.org](https://nodejs.org/)
+2. Double-click the .pkg file to run the installer
+3. Follow the installation wizard
+4. Verify installation: `node --version`
+
+#### Linux
+
+**Ubuntu/Debian:**
+```bash
+# Update package index
+sudo apt update
+
+# Install Node.js
+sudo apt install nodejs npm
+
+# Or install latest LTS version using NodeSource repository
+curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
+sudo apt-get install -y nodejs
+```
+
+**CentOS/RHEL/Fedora:**
+```bash
+# For CentOS/RHEL
+sudo yum install nodejs npm
+
+# For Fedora
+sudo dnf install nodejs npm
+
+# Or using NodeSource repository
+curl -fsSL https://rpm.nodesource.com/setup_lts.x | sudo bash -
+sudo yum install nodejs
+```
+
+**Using Node Version Manager (nvm) - All Linux Distributions:**
+```bash
+# Install nvm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
+
+# Restart terminal or run:
+source ~/.bashrc
+
+# Install latest LTS Node.js
+nvm install --lts
+nvm use --lts
+```
+
+#### Verification
+After installation on any platform, verify Node.js and npm are installed correctly:
+```bash
+node --version
+npm --version
+```
+
 ### Installation
 
 Install the latest version of AIGNE CLI globally:
@@ -161,7 +233,7 @@ aigne doc publish
 
 **Interactive Publishing:** When run `aigne doc publish` will present an interactive menu for you to choose between:
 - **Official Platform:** [docsmith.aigne.io](https://docsmith.aigne.io/app/)
-- **Self-Hosted Platform:** Your own deployed Discuss Kit instance
+- **Own Instance:** Your own deployed [Discuss Kit](https://store.blocklet.dev/blocklets/z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu) instance
 
 
 

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

@@ -1,16 +1,6 @@
----
-labels: ["Reference"]
----
-
 # How It Works
 
-AIGNE DocSmith provides a sophisticated, automated documentation solution by leveraging a multi-agent system built on the AIGNE Framework. Instead of relying on a single, monolithic AI, DocSmith orchestrates a pipeline of specialized AI agents, each an expert in its specific task. This collaborative approach ensures the generation of structured, detailed, and high-quality documentation directly from your source code.
-
-## Architectural Overview
-
-DocSmith is an integral part of the AIGNE ecosystem, a comprehensive platform for AI application development. It seamlessly integrates with other AIGNE components, utilizing the platform's core AI capabilities and infrastructure.
-
-![AIGNE Ecosystem Architecture](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
+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.
 
 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.
 
@@ -21,72 +11,77 @@ The entire process, from analyzing your code to publishing the final documents,
 ```d2
 direction: down
 
-"Source Code & Config": {
-  shape: step
-  label: "Input: Source Code & Configuration"
-}
-
-"Structure Planning": {
-  shape: step
-  label: "1. Structure Planning"
+Input: {
+  label: "Source Code & Config"
+  shape: rectangle
 }
 
-"Content Generation": {
-  shape: step
-  label: "2. Content Generation"
+Pipeline: {
+  label: "Documentation Generation Pipeline"
+  shape: rectangle
+  grid-columns: 1
+  grid-gap: 40
+
+  Structure-Planning: {
+    label: "1. Structure Planning\n(reflective-structure-planner)"
+    shape: rectangle
+  }
+
+  Content-Generation: {
+    label: "2. Content Generation\n(content-detail-generator)"
+    shape: rectangle
+  }
+
+  Saving: {
+    label: "3. Save Documents\n(save-docs)"
+    shape: rectangle
+  }
 }
 
-"Saving & Output": {
-  shape: step
-  label: "3. Saving & Output"
+User-Feedback: {
+  label: "User Feedback Loop\n(via --feedback flag)"
+  shape: rectangle
 }
 
-"Optional Processes": {
-  shape: diamond
-  label: "4. Optional Processes"
+Optional-Steps: {
+  label: "Optional Steps"
+  shape: rectangle
+  grid-columns: 2
+  grid-gap: 40
+  
+  Translation: {
+    label: "Translate\n(aigne doc translate)"
+    shape: rectangle
+  }
+
+  Publishing: {
+    label: "Publish\n(aigne doc publish)"
+    shape: rectangle
+  }
 }
 
-"Translation": {
-  shape: step
-  label: "Translation"
-}
-
-"Publishing": {
-  shape: step
-  label: "Publishing"
-}
-
-"Feedback Loop": {
-  shape: callout
-  label: "User Feedback Loop"
-}
-
-"Source Code & Config" -> "Structure Planning"
-"Structure Planning" -> "Content Generation"
-"Content Generation" -> "Saving & Output"
-"Saving & Output" -> "Optional Processes"
-
-"Optional Processes" -> "Translation": "Translate Docs"
-"Optional Processes" -> "Publishing": "Publish Docs"
-
-"Structure Planning" <- "Feedback Loop": "Refine Structure"
-"Content Generation" <- "Feedback Loop": "Regenerate Content"
+Input -> Pipeline.Structure-Planning
+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"
 ```
 
 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.
 
-2.  **Structure Planning**: The `reflective-structure-planner` agent analyzes the codebase to propose a comprehensive and logical document structure. It considers your specified target audience, rules, and feedback to create an optimal outline.
+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.
 
-3.  **Content Generation**: Once the structure is approved, the `content-detail-generator` and `batch-docs-detail-generator` agents take over. They populate each section of the document plan with detailed, high-quality content, ensuring technical accuracy and adherence to the defined style.
+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.
 
-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 intelligently update specific documents or adjust the overall structure based on your input.
+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.
 
 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.
 
 ## Key AI Agents
 
-DocSmith's power 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 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:
 
 | Agent Role | Primary Function | Governing File(s) |
 |---|---|---|
@@ -95,10 +90,10 @@ DocSmith's power comes from its team of specialized agents. While many agents wo
 | **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 from `aigne.yaml`. | `load-config.mjs` |
+| **Configuration Loader** | Reads and interprets the project's configuration and source files. | `load-config.mjs`, `load-sources.mjs` |
 
-This modular, agent-based architecture makes DocSmith highly flexible and robust, allowing each step of the process to be optimized independently.
+This modular, agent-based architecture makes DocSmith flexible and robust, allowing each step of the process to be optimized independently.
 
 ---
 
-Now that you understand the mechanics behind DocSmith, learn about the measures in place to guarantee high-quality output in the [Quality Assurance](./advanced-quality-assurance.md) section.
+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.

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

@@ -1,104 +1,99 @@
----
-labels: ["Reference"]
----
-
 # 工作原理
 
-AIGNE DocSmith 基于 AIGNE 框架构建的多 Agent 系统，提供了一套精密的自动化文档解决方案。 DocSmith 并非依赖单一、庞大的 AI，而是通过协调一系列专业的 AI Agent 组成的流水线，每个 Agent 都是其特定任务的专家。 这种协作方式确保了能够直接从您的源代码生成结构化、详细且高质量的文档。
-
-## 架构概述
+AIGNE DocSmith 使用一个多 Agent 系统来自动化文档生成。DocSmith 不使用单个 AI 模型，而是协调一个由专业化 AI Agent 组成的流水线，其中每个 Agent 都是特定任务的专家。这种协作方法可以直接从您的源代码生成结构化且详细的文档。
 
-DocSmith 是 AIGNE 生态系统不可或缺的一部分，AIGNE 是一个用于 AI 应用开发的综合平台。 它与其他 AIGNE 组件无缝集成，利用平台的核心 AI 能力和基础设施。
-
-![AIGNE Ecosystem Architecture](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
-
-DocSmith 的核心是一个处理流水线，它将您的源代码经过几个不同阶段的处理，每个阶段都由一个或多个专用的 AI Agent 管理。
+其核心是，DocSmith 作为一个流水线运行，通过几个不同的阶段处理您的源代码，每个阶段都由一个或多个专用的 AI Agent 管理。
 
 ## 文档生成流水线
 
-从分析代码到发布最终文档的整个过程，都遵循一个结构化的流水线。 这确保了过程的一致性，并允许在任何阶段进行有针对性的优化。
+从分析代码到发布最终文档的整个过程，都遵循一个结构化的流水线。这确保了一致性，并允许在任何阶段进行有针对性的优化。
 
 ```d2
 direction: down
 
-"Source Code & Config": {
-  shape: step
-  label: "输入：源代码与配置"
-}
-
-"Structure Planning": {
-  shape: step
-  label: "1. 结构规划"
+Input: {
+  label: "Source Code & Config"
+  shape: rectangle
 }
 
-"Content Generation": {
-  shape: step
-  label: "2. 内容生成"
+Pipeline: {
+  label: "Documentation Generation Pipeline"
+  shape: rectangle
+  grid-columns: 1
+  grid-gap: 40
+
+  Structure-Planning: {
+    label: "1. Structure Planning\n(reflective-structure-planner)"
+    shape: rectangle
+  }
+
+  Content-Generation: {
+    label: "2. Content Generation\n(content-detail-generator)"
+    shape: rectangle
+  }
+
+  Saving: {
+    label: "3. Save Documents\n(save-docs)"
+    shape: rectangle
+  }
 }
 
-"Saving & Output": {
-  shape: step
-  label: "3. 保存与输出"
+User-Feedback: {
+  label: "User Feedback Loop\n(via --feedback flag)"
+  shape: rectangle
 }
 
-"Optional Processes": {
-  shape: diamond
-  label: "4. 可选流程"
+Optional-Steps: {
+  label: "Optional Steps"
+  shape: rectangle
+  grid-columns: 2
+  grid-gap: 40
+  
+  Translation: {
+    label: "Translate\n(aigne doc translate)"
+    shape: rectangle
+  }
+
+  Publishing: {
+    label: "Publish\n(aigne doc publish)"
+    shape: rectangle
+  }
 }
 
-"Translation": {
-  shape: step
-  label: "翻译"
-}
-
-"Publishing": {
-  shape: step
-  label: "发布"
-}
-
-"Feedback Loop": {
-  shape: callout
-  label: "用户反馈循环"
-}
-
-"Source Code & Config" -> "Structure Planning"
-"Structure Planning" -> "Content Generation"
-"Content Generation" -> "Saving & Output"
-"Saving & Output" -> "Optional Processes"
-
-"Optional Processes" -> "Translation": "翻译文档"
-"Optional Processes" -> "Publishing": "发布文档"
-
-"Structure Planning" <- "Feedback Loop": "优化结构"
-"Content Generation" <- "Feedback Loop": "重新生成内容"
+Input -> Pipeline.Structure-Planning
+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"
 ```
 
-1.  **输入分析**：该过程始于 `load-sources` 和 `load-config` 等 Agent，它们负责收集您的源代码、配置文件（`aigne.yaml`）以及任何用户定义的规则。
+1.  **输入分析**：该过程始于 `load-sources` 和 `load-config` 等 Agent，它们会收集您的源代码、配置文件（`aigne.yaml`）以及任何用户定义的规则。
 
-2.  **结构规划**：`reflective-structure-planner` Agent 会分析代码库，以提出一个全面且逻辑清晰的文档结构。它会考虑您指定的目标受众、规则和反馈，以创建最佳大纲。
+2.  **结构规划**：`reflective-structure-planner` Agent 会分析代码库，以提出一个逻辑化的文档结构。它会考虑您指定的目标受众、规则和反馈，以创建一个最佳大纲。
 
-3.  **内容生成**：一旦结构获得批准，`content-detail-generator` 和 `batch-docs-detail-generator` Agent 就会接手。它们会用详细、高质量的内容填充文档计划的每个部分，确保技术准确性并遵循定义的风格。
+3.  **内容生成**：一旦结构确定，`content-detail-generator` 和 `batch-docs-detail-generator` Agent 就会接管。它们会用详细内容填充文档计划的每个部分，确保技术准确性并遵循定义的风格。
 
-4.  **优化与更新**：如果您使用 `aigne doc update` 或 `aigne doc generate --feedback` 提供反馈，`detail-regenerator` 和 `feedback-refiner` Agent 将被激活。它们会根据您的输入智能地更新特定文档或调整整体结构。
+4.  **优化与更新**：如果您使用 `aigne doc update` 或 `aigne doc generate --feedback` 提供反馈，`detail-regenerator` 和 `feedback-refiner` Agent 将被激活。它们会根据您的输入更新特定文档或调整整体结构。
 
 5.  **翻译与发布**：最后，像 `translate` 和 `publish-docs` 这样的可选 Agent 会处理多语言翻译和发布到 Discuss Kit 平台的工作，从而完成端到端的工作流。
 
 ## 关键 AI Agent
 
-DocSmith 的强大之处在于其专业的 Agent 团队。虽然许多 Agent 在幕后工作，但以下是文档生成流水线中的一些关键角色：
+DocSmith 的功能源于其专业化的 Agent 团队。虽然许多 Agent 在幕后工作，但以下是文档生成流水线中的一些关键角色：
 
 | Agent 角色 | 主要功能 | 相关文件 |
 |---|---|---|
-| **结构规划器** | 分析源代码和规则，以生成整体的文档大纲。 | `structure-planning.yaml`, `reflective-structure-planner.yaml` |
-| **内容生成器** | 根据计划为每个文档部分撰写详细内容。 | `content-detail-generator.yaml`, `batch-docs-detail-generator.yaml` |
+| **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` |
-| **配置加载器** | 从 `aigne.yaml` 读取并解释项目的配置。 | `load-config.mjs` |
+| **Configuration Loader** | 读取并解析项目的配置文件和源文件。 | `load-config.mjs`, `load-sources.mjs` |
 
-这种模块化的、基于 Agent 的架构使 DocSmith 变得高度灵活和健壮，允许流程的每一步都可以独立优化。
+这种模块化的、基于 Agent 的架构使得 DocSmith 灵活而强大，允许流程中的每一步都能被独立优化。
 
 ---
 
-现在您已经了解了 DocSmith 背后的工作机制，接下来请在 [质量保证](./advanced-quality-assurance.md) 部分了解为确保高质量输出而采取的措施。
+现在您已经了解了 DocSmith 背后的工作原理，请在 [质量保证](./advanced-quality-assurance.md) 部分了解为保证输出质量而采取的措施。

package/docs/advanced-quality-assurance.md

@@ -1,64 +1,99 @@
----
-labels: ["Reference"]
----
-
 # Quality Assurance
 
-To ensure your documentation is consistently high-quality, DocSmith includes a powerful automated quality assurance pipeline. These built-in checks run automatically during the generation and update processes to detect and report common issues—from broken links to formatting errors—before they reach your readers.
+To ensure all generated documentation is functional, clear, and professional, DocSmith incorporates an automated quality assurance process. This process executes a series of checks on the Markdown content to detect and report common issues, from broken links to malformed diagrams, before publication.
 
-The process validates multiple aspects of your content to maintain structural integrity and accuracy.
+This automated pipeline validates content structure, links, media, and syntax to maintain a consistent standard of quality.
 
 ```d2
-direction: right
+direction: down
+
+Input-Markdown-Content: {
+  label: "Input: Markdown Content"
+  shape: rectangle
+}
+
+QA-Pipeline: {
+  label: "QA Pipeline"
+  shape: rectangle
+  grid-columns: 1
+  grid-gap: 50
 
-Input: "Markdown Content"
+  Structural-Checks: {
+    label: "Structural Checks"
+    shape: rectangle
+    grid-columns: 2
+    Completeness: "Ensures content is not truncated"
+    Code-Blocks: "Validates block syntax & indentation"
+  }
+
+  Content-Validation: {
+    label: "Content Validation"
+    shape: rectangle
+    grid-columns: 2
+    Link-Integrity: "Verifies internal links"
+    Image-Paths: "Checks local image existence"
+    Table-Formatting: "Matches column counts"
+  }
 
-QA_Pipeline: "DocSmith QA Pipeline" {
-  shape: package
-  
-  Checks: {
+  Syntax-Validation: {
+    label: "Syntax Validation"
+    shape: rectangle
     grid-columns: 2
-    "Structural Integrity": "Incomplete code blocks & inconsistent indentation"
-    "Link & Asset Health": "Dead links & missing local images"
-    "Diagram Validation": "D2 syntax checks"
-    "Markdown Linting": "Table formatting & standard rules"
+    D2-Diagrams: "Validates D2 syntax"
+    Mermaid-Diagrams: "Validates Mermaid syntax"
+    Markdown-Linting: "Enforces style rules"
   }
 }
 
-Output: "Validated Documentation"
+Output-Validated-Content-or-Error-Report: {
+  label: "Output: Validated Content or Error Report"
+  shape: rectangle
+}
 
-Input -> QA_Pipeline: "Analyzed"
-QA_Pipeline -> Output: "Generated"
+Input-Markdown-Content -> QA-Pipeline
+QA-Pipeline -> Output-Validated-Content-or-Error-Report
 ```
 
-### Content and Structural Integrity
+### Core Validation Areas
+
+DocSmith's quality assurance process covers several key areas to ensure document integrity.
+
+#### Content Structure & Completeness
 
-DocSmith analyzes the fundamental structure of your markdown files to catch issues that often lead to rendering failures or confusing output.
+DocSmith performs several checks to ensure the structural integrity of the content:
 
-- **Incomplete Code Blocks**: The validator ensures that every code block opened with ` ``` ` is properly closed. Unclosed blocks can cause large portions of a document to render incorrectly.
-- **Inconsistent Indentation**: Code blocks with inconsistent indentation are flagged. This is particularly important for code samples where indentation is syntactically significant and for preventing unexpected rendering issues.
-- **Content Completeness**: The system checks if the content appears to be truncated by verifying that it ends with appropriate punctuation (e.g., `.`, `)`, `|`). This helps catch incomplete generation results.
+- **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.
 
-### Link and Asset Validation
+#### Link and Media Integrity
 
-Broken links and missing images can degrade the user experience. DocSmith validates these resources automatically to ensure they are always available to the reader.
+- **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.
 
-- **Dead Link Checking**: All internal links are cross-referenced against the paths defined in your project's structure plan. Any link pointing to a non-existent page is reported as a dead link.
-- **Local Image Verification**: For local images (i.e., those not hosted on an external server), the system checks that the referenced image file exists at the specified relative or absolute path.
+- **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 Validation
+#### Diagram Syntax Validation
 
-To ensure that all diagrams render correctly, DocSmith specifically validates the syntax of D2 code blocks. Before processing, the D2 content is checked for syntactical correctness. If an error is found, it is flagged to prevent a broken diagram from being published.
+- **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.
 
-### Markdown Formatting and Linting
+- **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.
 
-Beyond major structural issues, DocSmith lints the markdown for formatting consistency and correctness, leveraging established standards to enforce a clean and readable style. Key checks include:
+#### Formatting and Style Enforcement
 
-| Check Category | Description |
+- **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 |
 |---|---|
-| **Table Formatting** | Verifies that the number of columns in a table's header, separator line, and data rows are consistent. Mismatched column counts are a common cause of broken tables. |
-| **Heading Issues** | Detects duplicate headings within the same document or headings that use improper indentation, which can break the document outline. |
-| **Reference Validation** | Checks for undefined references, such as using a link reference `[text][ref]` without defining `[ref]: url` elsewhere. |
-| **Code Block Style** | Ensures consistent usage of code block markers for better readability and parsing. |
+| `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-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.
 
-This automated quality assurance layer is a core part of DocSmith's architecture, designed to minimize manual review and ensure that your documentation is always accurate, professional, and reliable. To learn more about the overall generation process, see [How It Works](./advanced-how-it-works.md).
+To learn more about the overall architecture, see the [How It Works](./advanced-how-it-works.md) section.