@aigne/doc-smith 0.8.11-beta.5 → 0.8.11-beta.7

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

@@ -1,96 +1,92 @@
 # 品質保証
 
-生成されるすべてのドキュメントが機能的、明確、かつプロフェッショナルであることを保証するため、DocSmithには自動品質保証プロセスが組み込まれています。このプロセスは、公開前にMarkdownコンテンツに対して一連のチェックを実行し、リンク切れから不正な形式の図まで、一般的な問題を検出して報告します。
+生成されるすべてのドキュメントが高い品質、一貫性、正確性の基準を満たすように、DocSmithには包括的で自動化された品質保証パイプラインが含まれています。これらの組み込みチェックは自動的に実行され、公開前に一般的なフォーマットエラー、リンク切れ、構造的な問題を特定してフラグを立てます。このプロセスにより、最終的な出力がプロフェッショナルで信頼性が高く、ユーザーがナビゲートしやすいものになることが保証されます。
 
-この自動化されたパイプラインは、コンテンツの構造、リンク、メディア、構文を検証し、一貫した品質基準を維持します。
-
-```d2
+```d2 品質保証パイプライン icon=lucide:shield-check
 direction: down
 
-Input-Markdown-Content: {
-  label: "入力: Markdownコンテンツ"
+Documentation-Content: {
+  label: "ドキュメントコンテンツ"
   shape: rectangle
 }
 
-QA-Pipeline: {
-  label: "QAパイプライン"
+Quality-Assurance-Pipeline: {
+  label: "品質保証パイプライン"
   shape: rectangle
-  grid-columns: 1
+  grid-columns: 3
   grid-gap: 50
 
-  Structural-Checks: {
-    label: "構造チェック"
+  Markdown-Validation: {
+    label: "1. Markdownとコンテンツの検証\n(remark-lintベース)"
     shape: rectangle
-    grid-columns: 2
-    Completeness: "コンテンツが切り捨てられていないことを保証"
-    Code-Blocks: "ブロックの構文とインデントを検証"
+
+    Check-1: "有効なMarkdown構文"
+    Check-2: "見出しの整合性"
+    Check-3: "テーブルのフォーマット"
+    Check-4: "コードブロックの整合性"
+    Check-5: "コンテンツの完全性"
   }
 
-  Content-Validation: {
-    label: "コンテンツ検証"
+  Link-Asset-Validation: {
+    label: "2. リンクとアセットの整合性"
     shape: rectangle
-    grid-columns: 2
-    Link-Integrity: "内部リンクを検証"
-    Image-Paths: "ローカル画像の存在を確認"
-    Table-Formatting: "列数が一致するか確認"
+
+    Check-6: "リンク切れの検出"
+    Check-7: "ローカル画像の検証"
   }
 
-  Syntax-Validation: {
-    label: "構文検証"
+  D2-Diagram-Validation: {
+    label: "3. D2ダイアグラムの検証"
     shape: rectangle
-    grid-columns: 2
-    D2-Diagrams: "D2構文を検証"
-    Markdown-Linting: "スタイルルールを強制"
+
+    Check-8: "D2構文チェック"
   }
 }
 
-Output-Validated-Content-or-Error-Report: {
-  label: "出力: 検証済みコンテンツまたはエラーレポート"
-  shape: rectangle
+Validation-Result: {
+  label: "すべてのチェックに合格？"
+  shape: diamond
 }
 
-Input-Markdown-Content -> QA-Pipeline
-QA-Pipeline -> Output-Validated-Content-or-Error-Report
-```
-
-### 主要な検証領域
-
-DocSmithの品質保証プロセスは、ドキュメントの完全性を保証するため、いくつかの主要な領域をカバーしています。
-
-#### コンテンツの構造と完全性
-
-DocSmithは、コンテンツの構造的完全性を保証するために、いくつかのチェックを実行します：
+Published-Documentation: {
+  label: "公開済みドキュメント"
+  shape: rectangle
+  style.fill: "#d4edda"
+}
 
-- **不完全なコードブロック**: ` ``` ` で開始されて閉じられていないコードブロックを検出します。
-- **改行の欠落**: 1行に表示されるコンテンツを特定します。これは改行が欠落している可能性を示します。
-- **コンテンツの末尾**: コンテンツが適切な句読点（例：`.`, `)`, `|`, `>`）で終わっていることを確認し、出力が切り捨てられるのを防ぎます。
-- **コードブロックのインデント**: コードブロックのインデントの不整合を分析します。コード行のインデントが開始の ` ``` ` マーカーよりも少ない場合、レンダリングの問題を引き起こす可能性があります。このチェックは、正しいコードの表示を維持するのに役立ちます。
+Error-Report: {
+  label: "エラーレポート"
+  shape: rectangle
+  style.fill: "#f8d7da"
+}
 
-#### リンクとメディアの整合性
+Documentation-Content -> Quality-Assurance-Pipeline: "入力"
+Quality-Assurance-Pipeline -> Validation-Result: "検証"
+Validation-Result -> Published-Documentation: "はい"
+Validation-Result -> Error-Report: "いいえ"
+```
 
-- **リンクの整合性**: ドキュメント内のすべての相対リンクは、ドキュメント構造計画と照らし合わせて検証され、リンク切れを防ぎます。これにより、すべての内部ナビゲーションが期待どおりに機能することが保証されます。チェッカーは外部リンク（`http://` または `https://` で始まる）および `mailto:` リンクを無視します。
+## Markdownとコンテンツ構造の検証
 
-- **画像の検証**: 画像の破損を避けるため、チェッカーはドキュメントで参照されているローカル画像ファイルがファイルシステムに存在することを確認します。相対パスと絶対パスの両方を解決して、ファイルの存在を確認します。外部リンクのURLやデータURLはチェックされません。
+品質保証の基盤は、コアとなるMarkdownが整形され、構造的に健全であることを保証することです。DocSmithは`remark-lint`をベースにした高度なリンターを採用しており、一般的な構造上の問題を検出するためのカスタムチェックで補完されています。
 
-#### 図の構文検証
+主な構造およびフォーマットのチェックには、次のものが含まれます。
 
-- **D2図**: DocSmithは、コードをSVG画像にコンパイルしようとすることでD2図の構文を検証します。このプロセスにより、構文エラーが図の破損につながる前に捕捉されます。
+*   **有効なMarkdown構文**：標準のMarkdownおよびGFM（GitHub Flavored Markdown）仕様への準拠。
+*   **見出しの整合性**：同一ドキュメント内の重複した見出し、不適切な見出しのインデント、複数のトップレベル見出し（H1）の使用などの問題を検出します。
+*   **テーブルのフォーマット**：テーブル構造が正しいことを検証します。特に、ヘッダー、区切り線、およびデータ行の列数の不一致をチェックします。
+*   **コードブロックの整合性**：すべてのコードブロックが ``` で適切に開始および終了していることを保証します。また、レンダリングに影響を与える可能性のある、コードブロック内の一貫性のないインデントもチェックします。
+*   **コンテンツの完全性**：生成されたコンテンツが適切な句読点で終わっていることを確認し、コンテンツが切り捨てられていないことを保証する検証ステップです。
 
-#### フォーマットとスタイルの強制
+## リンクとアセットの整合性
 
-- **テーブルのフォーマット**: ヘッダー、区切り線、データ行の間で列数が一致しないテーブルを検査します。このチェックにより、一般的なテーブルのレンダリング失敗を防ぎます。
+リンク切れや画像が見つからないことは、ユーザーエクスペリエンスを低下させます。DocSmithは、すべてのローカルリソースを検証するためのチェックを実行します。
 
-- **Markdownリンティング**: 組み込みのリンターが一貫したMarkdown構造を強制します。主要なルールには以下が含まれます：
+*   **リンク切れの検出**：システムはすべての相対Markdownリンクをスキャンし、ターゲットパスがプロジェクトのドキュメント構造で定義された有効なドキュメントに対応していることを検証します。このチェックにより、ユーザーがドキュメントをナビゲートする際に「404 Not Found」エラーに遭遇するのを防ぎます。`http://`または`https://`で始まる外部リンクはチェックされません。
+*   **ローカル画像の検証**：`![]()`を介して含まれるすべてのローカル画像について、バリデーターは参照されている画像ファイルが指定されたパスに存在することを確認します。これにより、最終的な出力に壊れた画像が表示されないようにします。
 
-| ルールID | 説明 |
-|---|---|
-| `no-duplicate-headings` | 同じセクション内で同じ内容の複数の見出しを防ぎます。 |
-| `no-undefined-references` | すべてのリンクと画像の参照が定義されていることを保証します。 |
-| `no-unused-definitions` | 使用されていないリンクや画像の定義にフラグを立てます。 |
-| `no-heading-content-indent` | 見出しの内容の前にインデントを許可しません。 |
-| `no-multiple-toplevel-headings` | ドキュメントごとにトップレベルの見出し（H1）を1つだけ許可します。 |
-| `code-block-style` | コードブロックに一貫したスタイル（例：バッククォートの使用）を強制します。 |
+## D2ダイアグラムの検証
 
-これらのチェックを自動化することで、DocSmithはドキュメントの一貫した基準を維持し、最終的な出力が正確でナビゲート可能であることを保証します。
+すべてのダイアグラムが正しくレンダリングされることを保証するため、DocSmithはすべてのD2ダイアグラムの構文を検証します。
 
-全体的なアーキテクチャについて詳しく知るには、[仕組み](./advanced-how-it-works.md)のセクションを参照してください。
+`d2`とマークされた各コードブロックは、厳密な構文チェッカーによって処理されます。構文エラーが見つかった場合、生成プロセスは説明的なエラーメッセージとともに停止されます。これにより、壊れた、または不適切にレンダリングされた視覚的なダイアグラムを含むドキュメントの公開を防ぎます。

package/docs/advanced-quality-assurance.md

@@ -1,96 +1,92 @@
 # Quality Assurance
 
-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.
+To ensure that all generated documentation meets a high standard of quality, consistency, and accuracy, DocSmith includes a comprehensive, automated quality assurance pipeline. These built-in checks run automatically to identify and flag common formatting errors, broken links, and structural issues before publication. This process guarantees that the final output is professional, reliable, and easy for users to navigate.
 
-This automated pipeline validates content structure, links, media, and syntax to maintain a consistent standard of quality.
-
-```d2
+```d2 Quality Assurance Pipeline icon=lucide:shield-check
 direction: down
 
-Input-Markdown-Content: {
-  label: "Input: Markdown Content"
+Documentation-Content: {
+  label: "Documentation Content"
   shape: rectangle
 }
 
-QA-Pipeline: {
-  label: "QA Pipeline"
+Quality-Assurance-Pipeline: {
+  label: "Quality Assurance Pipeline"
   shape: rectangle
-  grid-columns: 1
+  grid-columns: 3
   grid-gap: 50
 
-  Structural-Checks: {
-    label: "Structural Checks"
+  Markdown-Validation: {
+    label: "1. Markdown & Content Validation\n(remark-lint based)"
     shape: rectangle
-    grid-columns: 2
-    Completeness: "Ensures content is not truncated"
-    Code-Blocks: "Validates block syntax & indentation"
+
+    Check-1: "Valid Markdown Syntax"
+    Check-2: "Heading Integrity"
+    Check-3: "Table Formatting"
+    Check-4: "Code Block Integrity"
+    Check-5: "Content Completeness"
   }
 
-  Content-Validation: {
-    label: "Content Validation"
+  Link-Asset-Validation: {
+    label: "2. Link & Asset Integrity"
     shape: rectangle
-    grid-columns: 2
-    Link-Integrity: "Verifies internal links"
-    Image-Paths: "Checks local image existence"
-    Table-Formatting: "Matches column counts"
+
+    Check-6: "Dead Link Detection"
+    Check-7: "Local Image Validation"
   }
 
-  Syntax-Validation: {
-    label: "Syntax Validation"
+  D2-Diagram-Validation: {
+    label: "3. D2 Diagram Validation"
     shape: rectangle
-    grid-columns: 2
-    D2-Diagrams: "Validates D2 syntax"
-    Markdown-Linting: "Enforces style rules"
+
+    Check-8: "D2 Syntax Check"
   }
 }
 
-Output-Validated-Content-or-Error-Report: {
-  label: "Output: Validated Content or Error Report"
-  shape: rectangle
+Validation-Result: {
+  label: "All Checks Pass?"
+  shape: diamond
 }
 
-Input-Markdown-Content -> QA-Pipeline
-QA-Pipeline -> Output-Validated-Content-or-Error-Report
-```
-
-### Core Validation Areas
-
-DocSmith's quality assurance process covers several key areas to ensure document integrity.
-
-#### Content Structure & Completeness
-
-DocSmith performs several checks to ensure the structural integrity of the content:
+Published-Documentation: {
+  label: "Published Documentation"
+  shape: rectangle
+  style.fill: "#d4edda"
+}
 
-- **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.
+Error-Report: {
+  label: "Error Report"
+  shape: rectangle
+  style.fill: "#f8d7da"
+}
 
-#### Link and Media Integrity
+Documentation-Content -> Quality-Assurance-Pipeline: "Input"
+Quality-Assurance-Pipeline -> Validation-Result: "Validation"
+Validation-Result -> Published-Documentation: "Yes"
+Validation-Result -> Error-Report: "No"
+```
 
-- **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.
+## Markdown and Content Structure Validation
 
-- **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.
+The foundation of quality assurance is ensuring the core Markdown is well-formed and structurally sound. DocSmith employs a sophisticated linter based on `remark-lint`, supplemented with custom checks to catch common structural problems.
 
-#### Diagram Syntax Validation
+Key structural and formatting checks include:
 
-- **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.
+*   **Valid Markdown Syntax**: Adherence to standard Markdown and GFM (GitHub Flavored Markdown) specifications.
+*   **Heading Integrity**: Detects issues such as duplicate headings within the same document, incorrect heading indentation, and the use of more than one top-level heading (H1).
+*   **Table Formatting**: Verifies that table structures are correct, specifically checking for mismatches between the number of columns in the header, the separator line, and the data rows.
+*   **Code Block Integrity**: Ensures that all code blocks are properly opened and closed with ```. It also checks for inconsistent indentation within a code block, which can affect rendering.
+*   **Content Completeness**: A verification step to ensure that generated content does not appear truncated by checking that it ends with appropriate punctuation.
 
-#### Formatting and Style Enforcement
+## Link and Asset Integrity
 
-- **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.
+Broken links and missing images degrade the user experience. DocSmith performs checks to validate all local resources.
 
-- **Markdown Linting**: A built-in linter enforces a consistent Markdown structure. Key rules include:
+*   **Dead Link Detection**: The system scans all relative Markdown links and verifies that the target path corresponds to a valid document defined in the project's documentation structure. This check prevents users from encountering "404 Not Found" errors when navigating the documentation. External links beginning with `http://` or `https://` are not checked.
+*   **Local Image Validation**: For all local images included via `![]()`, the validator confirms that the referenced image file exists at the specified path. This ensures that no broken images appear in the final output.
 
-| 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). |
+## D2 Diagram Validation
 
-By automating these checks, DocSmith maintains a consistent standard for documentation, ensuring the final output is accurate and navigable.
+To guarantee that all diagrams are rendered correctly, DocSmith validates the syntax of every D2 diagram.
 
-To learn more about the overall architecture, see the [How It Works](./advanced-how-it-works.md) section.
+Each code block marked with `d2` is processed through a strict syntax checker. If any syntax errors are found, the generation process is halted with a descriptive error message. This prevents the publication of documents containing broken or improperly rendered visual diagrams.

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

@@ -1,96 +1,92 @@
 # 品質保證
 
-為確保所有生成的文檔功能正常、清晰且專業，DocSmith 整合了一個自動化的品質保證流程。此流程會在發布前對 Markdown 內容執行一系列檢查，以偵測並報告從斷開的連結到格式錯誤的圖表等常見問題。
+為確保所有產生的文件都符合高品質、一致性和準確性的標準，DocSmith 內建了一個全面、自動化的品質保證流程。這些內建的檢查會在發布前自動運行，以識別並標記常見的格式錯誤、失效連結和結構性問題。此過程確保最終的輸出成品具備專業性、可靠性，並讓使用者易於瀏覽。
 
-這個自動化管道會驗證內容結構、連結、媒體和語法，以維持一致的品質標準。
-
-```d2
+```d2 品質保證流程 icon=lucide:shield-check
 direction: down
 
-Input-Markdown-Content: {
-  label: "輸入：Markdown 內容"
+Documentation-Content: {
+  label: "文件內容"
   shape: rectangle
 }
 
-QA-Pipeline: {
-  label: "QA 管道"
+Quality-Assurance-Pipeline: {
+  label: "品質保證流程"
   shape: rectangle
-  grid-columns: 1
+  grid-columns: 3
   grid-gap: 50
 
-  Structural-Checks: {
-    label: "結構檢查"
+  Markdown-Validation: {
+    label: "1. Markdown 與內容驗證\n(基於 remark-lint)"
     shape: rectangle
-    grid-columns: 2
-    Completeness: "確保內容未被截斷"
-    Code-Blocks: "驗證區塊語法與縮排"
+
+    Check-1: "有效的 Markdown 語法"
+    Check-2: "標題完整性"
+    Check-3: "表格格式"
+    Check-4: "程式碼區塊完整性"
+    Check-5: "內容完整性"
   }
 
-  Content-Validation: {
-    label: "內容驗證"
+  Link-Asset-Validation: {
+    label: "2. 連結與資源完整性"
     shape: rectangle
-    grid-columns: 2
-    Link-Integrity: "驗證內部連結"
-    Image-Paths: "檢查本地圖片是否存在"
-    Table-Formatting: "匹配欄位數量"
+
+    Check-6: "失效連結偵測"
+    Check-7: "本地圖片驗證"
   }
 
-  Syntax-Validation: {
-    label: "語法驗證"
+  D2-Diagram-Validation: {
+    label: "3. D2 圖表驗證"
     shape: rectangle
-    grid-columns: 2
-    D2-Diagrams: "驗證 D2 語法"
-    Markdown-Linting: "強制執行樣式規則"
+
+    Check-8: "D2 語法檢查"
   }
 }
 
-Output-Validated-Content-or-Error-Report: {
-  label: "輸出：已驗證的內容或錯誤報告"
-  shape: rectangle
+Validation-Result: {
+  label: "所有檢查是否通過？"
+  shape: diamond
 }
 
-Input-Markdown-Content -> QA-Pipeline
-QA-Pipeline -> Output-Validated-Content-or-Error-Report
-```
-
-### 核心驗證領域
-
-DocSmith 的品質保證流程涵蓋了幾個關鍵領域，以確保文檔的完整性。
-
-#### 內容結構與完整性
-
-DocSmith 執行多項檢查，以確保內容的結構完整性：
+Published-Documentation: {
+  label: "已發布的文件"
+  shape: rectangle
+  style.fill: "#d4edda"
+}
 
-- **不完整的程式碼區塊**：偵測以 ` ``` ` 開啟但未關閉的程式碼區塊。
-- **缺少換行符**：識別出現在單一行上的內容，這可能表示缺少換行符。
-- **內容結尾**：驗證內容是否以適當的標點符號（例如 `.`、`)`、`|`、`>`）結尾，以防止輸出被截斷。
-- **程式碼區塊縮排**：分析程式碼區塊中不一致的縮排。如果某一行程式碼的縮排少於開頭的 ` ``` ` 標記，可能會導致渲染問題。此檢查有助於維持正確的程式碼呈現。
+Error-Report: {
+  label: "錯誤報告"
+  shape: rectangle
+  style.fill: "#f8d7da"
+}
 
-#### 連結與媒體完整性
+Documentation-Content -> Quality-Assurance-Pipeline: "輸入"
+Quality-Assurance-Pipeline -> Validation-Result: "驗證"
+Validation-Result -> Published-Documentation: "是"
+Validation-Result -> Error-Report: "否"
+```
 
-- **連結完整性**：文檔中的所有相對連結都會根據文檔結構計畫進行驗證，以防止出現無效連結。這確保了所有內部導覽都能如預期般運作。檢查器會忽略外部連結（以 `http://` 或 `https://` 開頭）和 `mailto:` 連結。
+## Markdown 與內容結構驗證
 
-- **圖片驗證**：為避免圖片損壞，檢查器會驗證文檔中引用的任何本地圖片檔案是否存在於檔案系統中。它會解析相對和絕對路徑，以確認檔案存在。外部圖片 URL 和資料 URL 不會被檢查。
+品質保證的基礎是確保核心 Markdown 格式正確且結構健全。DocSmith 採用一個基於 `remark-lint` 的精密 linter，並輔以自訂檢查來捕捉常見的結構性問題。
 
-#### 圖表語法驗證
+主要的結構和格式檢查包括：
 
-- **D2 圖表**：DocSmith 透過嘗試將程式碼編譯成 SVG 圖片來驗證 D2 圖表語法。此過程能在語法錯誤導致圖形損壞前捕捉到它們。
+*   **有效的 Markdown 語法**：遵循標準 Markdown 和 GFM (GitHub Flavored Markdown) 規範。
+*   **標題完整性**：偵測同一文件內的重複標題、不正確的標題縮排，以及使用超過一個頂層標題 (H1) 等問題。
+*   **表格格式**：驗證表格結構是否正確，特別是檢查標頭、分隔線和資料列之間的欄位數量是否不匹配。
+*   **程式碼區塊完整性**：確保所有程式碼區塊都以 ``` 正確地開啟和關閉。它還會檢查程式碼區塊內可能影響渲染結果的不一致縮排。
+*   **內容完整性**：一個驗證步驟，透過檢查產生的內容是否以適當的標點符號結尾，來確保內容不會看似被截斷。
 
-#### 格式化與樣式強制執行
+## 連結與資源完整性
 
-- **表格格式化**：檢查表格的標頭、分隔線和資料行之間的欄位數量是否不匹配。此檢查可防止常見的表格渲染失敗。
+失效連結和遺失的圖片會降低使用者體驗。DocSmith 會執行檢查以驗證所有本地資源。
 
-- **Markdown 語法檢查**：內建的 linter 強制執行一致的 Markdown 結構。主要規則包括：
+*   **失效連結偵測**：系統會掃描所有相對 Markdown 連結，並驗證目標路徑是否對應到專案文件結構中定義的有效文件。此檢查可防止使用者在瀏覽文件時遇到「404 Not Found」錯誤。以 `http://` 或 `https://` 開頭的外部連結則不會被檢查。
+*   **本地圖片驗證**：對於所有透過 `![]()` 包含的本地圖片，驗證器會確認所引用的圖片檔案是否存在於指定路徑。這能確保最終的輸出成品中不會出現破損的圖片。
 
-| Rule ID | Description |
-|---|---|
-| `no-duplicate-headings` | 防止在同一部分中出現內容相同的多個標題。 |
-| `no-undefined-references` | 確保所有連結和圖片引用都已定義。 |
-| `no-unused-definitions` | 標記未使用的連結或圖片定義。 |
-| `no-heading-content-indent` | 不允許在標題內容前縮排。 |
-| `no-multiple-toplevel-headings` | 每個文件只允許一個頂層標題 (H1)。 |
-| `code-block-style` | 強制執行一致的程式碼區塊樣式（例如，使用反引號）。 |
+## D2 圖表驗證
 
-透過自動化這些檢查，DocSmith 維護了文檔的一致標準，確保最終輸出準確且易於導覽。
+為保證所有圖表都能正確渲染，DocSmith 會驗證每個 D2 圖表的語法。
 
-若要了解更多關於整體架構的資訊，請參閱 [運作方式](./advanced-how-it-works.md) 部分。
+每個標記為 `d2` 的程式碼區塊都會經過嚴格的語法檢查器處理。若發現任何語法錯誤，產生過程將會被中止，並顯示一則描述性的錯誤訊息。這可以防止發布含有破損或渲染不當的視覺圖表的文件。

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

@@ -1,96 +1,92 @@
 # 质量保证
 
-为确保所有生成的文档功能正常、清晰且专业，DocSmith 引入了自动化的质量保证流程。该流程在发布前对 Markdown 内容执行一系列检查，以检测和报告常见问题，从损坏的链接到格式错误的图表。
+为确保所有生成的文档都符合高质量、一致性和准确性的标准，DocSmith 包含一个全面的自动化质量保证流程。这些内置检查会自动运行，以在发布前识别并标记常见的格式错误、断开的链接和结构性问题。此过程保证最终输出专业、可靠且易于用户浏览。
 
-这个自动化管道会验证内容结构、链接、媒体和语法，以保持一致的质量标准。
-
-```d2
+```d2 质量保证流程 icon=lucide:shield-check
 direction: down
 
-Input-Markdown-Content: {
-  label: "输入：Markdown 内容"
+Documentation-Content: {
+  label: "文档内容"
   shape: rectangle
 }
 
-QA-Pipeline: {
-  label: "质量保证管道"
+Quality-Assurance-Pipeline: {
+  label: "质量保证流程"
   shape: rectangle
-  grid-columns: 1
+  grid-columns: 3
   grid-gap: 50
 
-  Structural-Checks: {
-    label: "结构检查"
+  Markdown-Validation: {
+    label: "1. Markdown 和内容验证\n（基于 remark-lint）"
     shape: rectangle
-    grid-columns: 2
-    Completeness: "确保内容不被截断"
-    Code-Blocks: "验证块语法和缩进"
+
+    Check-1: "有效的 Markdown 语法"
+    Check-2: "标题完整性"
+    Check-3: "表格格式"
+    Check-4: "代码块完整性"
+    Check-5: "内容完整性"
   }
 
-  Content-Validation: {
-    label: "内容验证"
+  Link-Asset-Validation: {
+    label: "2. 链接和资产完整性"
     shape: rectangle
-    grid-columns: 2
-    Link-Integrity: "验证内部链接"
-    Image-Paths: "检查本地图片是否存在"
-    Table-Formatting: "匹配列数"
+
+    Check-6: "死链检测"
+    Check-7: "本地图片验证"
   }
 
-  Syntax-Validation: {
-    label: "语法验证"
+  D2-Diagram-Validation: {
+    label: "3. D2 图表验证"
     shape: rectangle
-    grid-columns: 2
-    D2-Diagrams: "验证 D2 语法"
-    Markdown-Linting: "强制执行样式规则"
+
+    Check-8: "D2 语法检查"
   }
 }
 
-Output-Validated-Content-or-Error-Report: {
-  label: "输出：已验证内容或错误报告"
-  shape: rectangle
+Validation-Result: {
+  label: "所有检查是否通过？"
+  shape: diamond
 }
 
-Input-Markdown-Content -> QA-Pipeline
-QA-Pipeline -> Output-Validated-Content-or-Error-Report
-```
-
-### 核心验证领域
-
-DocSmith 的质量保证流程涵盖了几个关键领域，以确保文档的完整性。
-
-#### 内容结构与完整性
-
-DocSmith 执行多项检查以确保内容的结构完整性：
+Published-Documentation: {
+  label: "已发布的文档"
+  shape: rectangle
+  style.fill: "#d4edda"
+}
 
-- **不完整的代码块**：检测以 ` ``` ` 开始但未关闭的代码块。
-- **缺少换行符**：识别出现在单行上的内容，这可能表示缺少换行符。
-- **内容结尾**：验证内容是否以适当的标点符号（例如 `.`、`)`、`|`、`>`）结尾，以防止输出被截断。
-- **代码块缩进**：分析代码块中不一致的缩进。如果某行代码的缩进小于起始的 ` ``` ` 标记，可能会导致渲染问题。此检查有助于保持正确的代码呈现。
+Error-Report: {
+  label: "错误报告"
+  shape: rectangle
+  style.fill: "#f8d7da"
+}
 
-#### 链接与媒体完整性
+Documentation-Content -> Quality-Assurance-Pipeline: "输入"
+Quality-Assurance-Pipeline -> Validation-Result: "验证"
+Validation-Result -> Published-Documentation: "是"
+Validation-Result -> Error-Report: "否"
+```
 
-- **链接完整性**：文档中的所有相对链接都会根据文档结构计划进行验证，以防止出现死链接。这确保了所有内部导航都能正常工作。检查器会忽略外部链接（以 `http://` 或 `https://` 开头）和 `mailto:` 链接。
+## Markdown 和内容结构验证
 
-- **图片验证**：为避免图片损坏，检查器会验证文档中引用的任何本地图片文件是否存在于文件系统中。它会解析相对路径和绝对路径以确认文件存在。外部图片 URL 和数据 URL 不会被检查。
+质量保证的基础是确保核心 Markdown 格式良好且结构合理。DocSmith 采用基于 `remark-lint` 的精密 linter，并辅以自定义检查来捕获常见的结构性问题。
 
-#### 图表语法验证
+关键的结构和格式检查包括：
 
-- **D2 图表**：DocSmith 通过尝试将代码编译成 SVG 图片来验证 D2 图表语法。这个过程可以在语法错误导致图形损坏之前捕获它们。
+*   **有效的 Markdown 语法**：遵循标准 Markdown 和 GFM（GitHub Flavored Markdown）规范。
+*   **标题完整性**：检测同一文档中重复的标题、不正确的标题缩进以及使用多个顶级标题（H1）等问题。
+*   **表格格式**：验证表格结构是否正确，特别是检查表头、分隔行和数据行之间的列数是否不匹配。
+*   **代码块完整性**：确保所有代码块都使用 ``` 正确地开始和结束。它还会检查代码块内不一致的缩进，这可能会影响渲染。
+*   **内容完整性**：一个验证步骤，通过检查生成的内容是否以适当的标点符号结尾，来确保内容没有被截断。
 
-#### 格式与样式强制执行
+## 链接和资产完整性
 
-- **表格格式化**：检查表格的表头、分隔线和数据行之间的列数是否不匹配。此检查可防止常见的表格渲染失败。
+断开的链接和缺失的图片会降低用户体验。DocSmith 会执行检查以验证所有本地资源。
 
-- **Markdown 语法检查**：内置的 linter 会强制执行一致的 Markdown 结构。关键规则包括：
+*   **死链检测**：系统会扫描所有相对 Markdown 链接，并验证目标路径是否对应于项目文档结构中定义的有效文档。此检查可防止用户在浏览文档时遇到“404 Not Found”错误。以 `http://` 或 `https://` 开头的外部链接不会被检查。
+*   **本地图片验证**：对于所有通过 `![]()` 包含的本地图片，验证器会确认引用的图片文件是否存在于指定路径。这可以确保最终输出中不会出现损坏的图片。
 
-| Rule ID | Description |
-|---|---|
-| `no-duplicate-headings` | 防止在同一部分中出现内容相同的多个标题。 |
-| `no-undefined-references` | 确保所有链接和图片引用都已定义。 |
-| `no-unused-definitions` | 标记未被使用的链接或图片定义。 |
-| `no-heading-content-indent` | 禁止在标题内容前缩进。 |
-| `no-multiple-toplevel-headings` | 每个文档只允许一个顶级标题 (H1)。 |
-| `code-block-style` | 强制代码块使用一致的样式（例如，使用反引号）。 |
+## D2 图表验证
 
-通过自动化这些检查，DocSmith 为文档维护了一致的标准，确保最终输出准确且易于导航。
+为保证所有图表都能正确渲染，DocSmith 会验证每个 D2 图表的语法。
 
-要了解有关整体架构的更多信息，请参阅[工作原理](./advanced-how-it-works.md)部分。
+每个标记为 `d2` 的代码块都会经过严格的语法检查器处理。如果发现任何语法错误，生成过程将停止并显示描述性错误消息。这可以防止发布包含损坏或渲染不当的可视图表的文档。