@aigne/doc-smith 0.8.3 → 0.8.5

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.

package/docs/advanced-quality-assurance.zh.md

@@ -1,64 +1,99 @@
----
-labels: ["Reference"]
----
-
 # 质量保证
 
-为确保您的文档始终保持高质量，DocSmith 内置了一个强大的自动化质量保证流程。这些内置检查在生成和更新过程中自动运行，以检测并报告常见问题（从链接失效到格式错误），从而在问题影响到读者之前予以解决。
+为确保所有生成的文档功能正常、清晰且专业，DocSmith 引入了自动化的质量保证流程。该流程会对 Markdown 内容执行一系列检查，以便在发布前检测并报告从链接失效到图表格式错误等常见问题。
 
-该流程会验证您内容的多个方面，以保持结构的完整性和准确性。
+该自动化流程会验证内容结构、链接、媒体和语法，以保持一致的质量标准。
 
 ```d2
-direction: right
+direction: down
+
+Input-Markdown-Content: {
+  label: "输入：Markdown 内容"
+  shape: rectangle
+}
+
+QA-Pipeline: {
+  label: "质量保证流程"
+  shape: rectangle
+  grid-columns: 1
+  grid-gap: 50
 
-Input: "Markdown 内容"
+  Structural-Checks: {
+    label: "结构检查"
+    shape: rectangle
+    grid-columns: 2
+    Completeness: "确保内容未被截断"
+    Code-Blocks: "验证代码块语法和缩进"
+  }
+
+  Content-Validation: {
+    label: "内容验证"
+    shape: rectangle
+    grid-columns: 2
+    Link-Integrity: "验证内部链接"
+    Image-Paths: "检查本地图片是否存在"
+    Table-Formatting: "匹配列数"
+  }
 
-QA_Pipeline: "DocSmith QA 流程" {
-  shape: package
-  
-  Checks: {
+  Syntax-Validation: {
+    label: "语法验证"
+    shape: rectangle
     grid-columns: 2
-    "结构完整性": "代码块不完整和缩进不一致"
-    "链接和资源健康状况": "失效链接和本地图片缺失"
-    "图表验证": "D2 语法检查"
-    "Markdown 语法检查": "表格格式和标准规则"
+    D2-Diagrams: "验证 D2 语法"
+    Mermaid-Diagrams: "验证 Mermaid 语法"
+    Markdown-Linting: "强制执行样式规则"
   }
 }
 
-Output: "经验证的文档"
+Output-Validated-Content-or-Error-Report: {
+  label: "输出：验证通过的内容或错误报告"
+  shape: rectangle
+}
 
-Input -> QA_Pipeline: "分析"
-QA_Pipeline -> Output: "生成"
+Input-Markdown-Content -> QA-Pipeline
+QA-Pipeline -> Output-Validated-Content-or-Error-Report
 ```
 
-### 内容和结构完整性
+### 核心验证领域
+
+DocSmith 的质量保证流程涵盖了几个关键领域，以确保文档的完整性。
+
+#### 内容结构与完整性
 
-DocSmith 会分析 Markdown 文件的基本结构，以捕获那些经常导致渲染失败或输出混乱的问题。
+DocSmith 会执行多项检查以确保内容的结构完整性：
 
-- **代码块不完整**：验证器会确保每个以 ` ``` ` 开始的代码块都已正确关闭。未关闭的代码块可能导致文档的大部分内容无法正确渲染。
-- **缩进不一致**：系统会标记出缩进不一致的代码块。这对于缩进具有语法意义的代码示例以及防止意外的渲染问题尤为重要。
-- **内容完整性**：系统通过验证内容是否以适当的标点符号（例如 `.`、`)`、`|`）结尾，来检查内容是否被截断。这有助于捕获不完整的生成结果。
+- **不完整的代码块**：检测以 ```` ``` ```` 开头但未关闭的代码块。
+- **缺少换行符**：识别显示在单行上的内容，这可能表示缺少换行符。
+- **内容结尾**：验证内容是否以适当的标点符号（例如 `.`、`)`、`|`、`>`）结尾，以防止输出被截断。
 
-### 链接和资源验证
+#### 链接和媒体完整性
 
-失效链接和缺失图片会降低用户体验。DocSmith 会自动验证这些资源，以确保读者始终可以访问它们。
+- **链接完整性**：文档中的所有相对链接都会根据项目的 `structurePlan` 进行验证，以防止出现死链接。这确保了所有内部导航都能正常工作。检查程序会忽略外部链接（以 `http://` 或 `https://` 开头）和 `mailto:` 链接。
 
-- **失效链接检查**：所有内部链接都会与您项目结构计划中定义的路径进行交叉引用。任何指向不存在页面的链接都将被报告为失效链接。
-- **本地图片验证**：对于本地图片（即未托管在外部服务器上的图片），系统会检查引用的图片文件是否存在于指定的相对或绝对路径中。
+- **图片验证**：为避免图片损坏，检查程序会验证文档中引用的任何本地图片文件是否存在于文件系统中。它会解析相对路径和绝对路径以确认文件存在。外部图片 URL 和数据 URL 不会被检查。
 
-### 图表验证
+#### 图表语法验证
 
-为确保所有图表都能正确渲染，DocSmith 会专门验证 D2 代码块的语法。在处理之前，系统会检查 D2 内容的语法正确性。如果发现错误，系统会进行标记，以防止发布损坏的图表。
+- **D2 图表**：DocSmith 通过将代码发送到渲染服务来验证 D2 图表语法。此过程会确认图表能否成功编译为 SVG 图片，从而在导致图形损坏前捕获任何语法错误。
 
-### Markdown 格式化与语法检查
+- **Mermaid 图表**：Mermaid 图表会经过多项检查：一次主语法验证，以及针对已知会导致渲染问题的模式的特定检查，例如节点标签内的反引号或编号列表，以及需要加引号但未加的特殊字符。
 
-除了主要的结构性问题，DocSmith 还会对 Markdown 进行语法检查，以确保格式的一致性和正确性，并利用既定标准来强制执行清晰易读的风格。关键检查包括：
+#### 格式化与样式强制
 
-| 检查类别 | 描述 |
+- **表格格式化**：检查表格的表头、分隔线和数据行之间的列数是否不匹配。此检查可防止常见的表格渲染失败。
+
+- **代码块缩进**：检查程序会分析代码块中不一致的缩进。如果某行代码的缩进小于开头的 ```` ``` ```` 标记，可能会导致渲染问题。此检查有助于保持正确的代码呈现。
+
+- **Markdown Linting**：内置的 linter 会强制执行一致的 Markdown 结构。关键规则包括：
+
+| 规则 ID | 描述 |
 |---|---|
-| **表格格式化** | 验证表格的表头、分隔线和数据行中的列数是否一致。列数不匹配是导致表格损坏的常见原因。 |
-| **标题问题** | 检测同一文档中的重复标题或使用不当缩进的标题，这些问题可能会破坏文档大纲。 |
-| **引用验证** | 检查未定义的引用，例如使用了链接引用 `[text][ref]`，但未在其他地方定义 `[ref]: url`。 |
-| **代码块样式** | 确保一致地使用代码块标记，以提高可读性和解析效率。 |
+| `no-duplicate-headings` | 防止同一节中出现内容相同的多个标题。 |
+| `no-undefined-references` | 确保所有链接和图片引用都已定义。 |
+| `no-heading-content-indent` | 不允许在标题内容前缩进。 |
+| `no-multiple-toplevel-headings` | 每个文档只允许一个顶级标题 (H1)。 |
+| `code-block-style` | 强制代码块使用一致的样式（例如，使用反引号）。 |
+
+通过自动化这些检查，DocSmith 保持了文档的一致标准，确保最终输出准确且易于导航。
 
-这个自动化的质量保证层是 DocSmith 架构的核心部分，旨在最大限度地减少人工审查，并确保您的文档始终准确、专业且可靠。要了解有关整体生成流程的更多信息，请参阅[工作原理](./advanced-how-it-works.md)。
+要了解有关整体架构的更多信息，请参阅 [工作原理](./advanced-how-it-works.md) 部分。

package/docs/advanced.md

@@ -1,18 +1,6 @@
----
-labels: ["Reference"]
----
-
 # Advanced Topics
 
-For those who wish to look under the hood, this section provides a deeper dive into the architecture of AIGNE DocSmith. Here, you'll learn how the tool functions, its place within the AIGNE ecosystem, and the internal mechanisms it uses to generate high-quality documentation.
-
-While a deep understanding of these topics isn't necessary for general use, it can be valuable for customizing behavior, troubleshooting issues, or contributing to the project.
-
-## The AIGNE Ecosystem
-
-AIGNE DocSmith is not a standalone tool; it is a key component of the [AIGNE Framework](https://www.aigne.io/en/framework), a comprehensive platform for AI application development. This integration allows DocSmith to leverage the platform's advanced AI capabilities and robust infrastructure. The following diagram illustrates how DocSmith fits into the broader ecosystem.
-
-![AIGNE Ecosystem Architecture](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
+For users who wish to understand the internal mechanics, this section provides a deeper look into the architecture of AIGNE DocSmith. It explains how the tool functions behind the scenes. While this level of detail is not required for general use, it can be valuable for customizing behavior or contributing to the project.
 
 To better understand the internal processes and quality controls, explore the following sections.
 
@@ -21,7 +9,7 @@ To better understand the internal processes and quality controls, explore the fo
     An architectural overview of DocSmith, explaining the role of AI agents in the documentation generation pipeline.
   </x-card>
   <x-card data-title="Quality Assurance" data-href="/advanced/quality-assurance" data-icon="lucide:shield-check">
-    Understand the built-in checks DocSmith performs to ensure high-quality, well-formatted, and error-free documentation.
+    Understand the built-in checks DocSmith performs to ensure well-formatted and error-free documentation, including link checking and diagram validation.
   </x-card>
 </x-cards>
 

package/docs/advanced.zh.md

@@ -1,28 +1,16 @@
----
-labels: ["Reference"]
----
-
 # 高级主题
 
-对于希望深入了解其内部机制的用户，本节将深入解析 AIGNE DocSmith 的架构。在这里，你将了解到该工具的运作方式、其在 AIGNE 生态系统中的定位，以及它用于生成高质量文档的内部机制。
-
-虽然深入理解这些主题对于一般使用并非必要，但它对于自定义行为、排查问题或为项目做出贡献非常有价值。
-
-## AIGNE 生态系统
-
-AIGNE DocSmith 并非一个独立的工具，而是 [AIGNE 框架](https://www.aigne.io/en/framework) 的关键组件，该框架是一个用于 AI 应用开发的综合平台。这种集成使 DocSmith 能够利用该平台的先进 AI 功能和强大的基础设施。下图展示了 DocSmith 如何融入更广泛的生态系统。
-
-![AIGNE 生态系统架构](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
+对于希望了解内部机制的用户，本节将深入介绍 AIGNE DocSmith 的架构。它解释了该工具在后台如何运作。虽然一般使用不需要了解这些细节，但对于自定义行为或为项目做贡献而言，这些信息可能很有价值。
 
-要更好地了解其内部流程和质量控制，请浏览以下章节。
+要更好地了解内部流程和质量控制，请浏览以下部分。
 
 <x-cards data-columns="2">
   <x-card data-title="工作原理" data-href="/advanced/how-it-works" data-icon="lucide:cpu">
-    DocSmith 的架构概览，解释了 AI Agent 在文档生成流程中的作用。
+    DocSmith 的架构概述，解释了 AI Agent 在文档生成流程中的作用。
   </x-card>
   <x-card data-title="质量保证" data-href="/advanced/quality-assurance" data-icon="lucide:shield-check">
-    了解 DocSmith 为确保文档高质量、格式良好且无错误而执行的内置检查。
+    了解 DocSmith 为确保文档格式正确、无错误而执行的内置检查，包括链接检查和图表验证。
   </x-card>
 </x-cards>
 
-通过探索这些主题，你可以更全面地了解 DocSmith 的功能。要获取所有可用命令及其选项的详细说明，请参阅 [CLI 命令参考](./cli-reference.md)。
+通过探索这些主题，你可以更全面地了解 DocSmith 的功能。要详细了解所有可用命令及其选项，请继续阅读 [CLI 命令参考](./cli-reference.md)。

package/docs/changelog.md

@@ -1,11 +1,48 @@
----
-labels: ["Reference"]
----
-
 # Changelog
 
 A detailed log of all notable changes, features, and bug fixes for each version of the project.
 
+## [0.8.2](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.1...v0.8.2) (2025-09-04)
+
+
+### Miscellaneous Chores
+
+* release 0.8.2 ([849bc69](https://github.com/AIGNE-io/aigne-doc-smith/commit/849bc694edf167187f65cb34f1dd9a3966efd96c))
+
+## [0.8.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.8.0...v0.8.1) (2025-09-03)
+
+
+### Features
+
+* tune d2 chart generating with comprehensive examples ([#80](https://github.com/AIGNE-io/aigne-doc-smith/issues/80)) ([3423e4c](https://github.com/AIGNE-io/aigne-doc-smith/commit/3423e4cff24335552503916694a3489e5d91bf6c))
+
+
+### Miscellaneous Chores
+
+* release 0.8.1 ([21f64d4](https://github.com/AIGNE-io/aigne-doc-smith/commit/21f64d450377b1aef00f12613ba3b87aa4ef1d31))
+
+## [0.8.0](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.7.2...v0.8.0) (2025-09-03)
+
+
+### Features
+
+* **tests:** add comprehensive workflow test coverage ([#76](https://github.com/AIGNE-io/aigne-doc-smith/issues/76)) ([d5f6062](https://github.com/AIGNE-io/aigne-doc-smith/commit/d5f6062311f36dc5b6394ae0768583fb8f3853a4))
+* update custom component guidelines with formatting restrictions ([#79](https://github.com/AIGNE-io/aigne-doc-smith/issues/79)) ([76158de](https://github.com/AIGNE-io/aigne-doc-smith/commit/76158de236696e68c63c057f5ea4b8458a15e787))
+
+## [0.7.2](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.7.1...v0.7.2) (2025-09-01)
+
+
+### Miscellaneous Chores
+
+* release 0.7.2 ([c3be232](https://github.com/AIGNE-io/aigne-doc-smith/commit/c3be2323e885cf5d11d654629fe30cc3720f79d3))
+
+## [0.7.1](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.7.0...v0.7.1) (2025-08-31)
+
+
+### Bug Fixes
+
+* fix tab key path selection bug ([#72](https://github.com/AIGNE-io/aigne-doc-smith/issues/72)) ([369b342](https://github.com/AIGNE-io/aigne-doc-smith/commit/369b342d8ab8ce95b61a3b72e367157d2f71cce4))
+
 ## [0.7.0](https://github.com/AIGNE-io/aigne-doc-smith/compare/v0.6.0...v0.7.0) (2025-08-30)