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

package/docs/configuration.zh.md

@@ -1,8 +1,8 @@
 # 配置指南
 
-AIGNE DocSmith 的行为由一个中心文件 `config.yaml` 控制，该文件通常位于 `.aigne/doc-smith/config.yaml`。此文件规定了文档的风格、目标受众、语言和结构。
+AIGNE DocSmith 的行为由一个位于 `.aigne/doc-smith/config.yaml` 的核心文件 `config.yaml` 控制。该文件决定了文档的风格、目标受众、语言和结构。
 
-你可以通过运行 `aigne doc init`，使用交互式设置向导来创建和管理此文件。有关分步指南，请参阅[交互式设置](./configuration-interactive-setup.md)指南。
+你可以通过运行 `aigne doc init` 使用交互式设置向导来创建和管理此文件。有关分步演练，请参阅 [交互式设置](./configuration-interactive-setup.md) 指南。
 
 ## 核心配置区域
 
@@ -10,7 +10,7 @@ AIGNE DocSmith 的行为由一个中心文件 `config.yaml` 控制，该文件
 
 <x-cards data-columns="2">
   <x-card data-title="交互式设置" data-icon="lucide:wand-2" data-href="/configuration/interactive-setup">
-    了解引导式向导，它能帮助你从头开始配置文档项目，包括设置建议。
+    了解引导式向导如何帮助你配置文档项目，包括设置建议和冲突检测。
   </x-card>
   <x-card data-title="LLM 设置" data-icon="lucide:brain-circuit" data-href="/configuration/llm-setup">
     了解如何连接不同的 AI 模型，包括使用无需 API 密钥的内置 AIGNE Hub。
@@ -29,12 +29,12 @@ AIGNE DocSmith 的行为由一个中心文件 `config.yaml` 控制，该文件
 
 ### 项目信息
 
-这些设置提供了关于你项目的基本背景信息，用于发布文档。
+这些设置提供了关于项目的基本背景信息，用于发布文档。
 
 | Parameter | Description |
 |---|---|
-| `projectName` | 你的项目名称。如果 `package.json` 文件存在，则自动从中检测。 |
-| `projectDesc` | 你的项目的简短描述。自动从 `package.json` 检测。 |
+| `projectName` | 你的项目名称。如果可用，将从 `package.json` 中检测。 |
+| `projectDesc` | 你的项目的简短描述。从 `package.json` 中检测。 |
 | `projectLogo` | 你的项目徽标图片的路径或 URL。 |
 
 ### 文档策略
@@ -42,23 +42,23 @@ AIGNE DocSmith 的行为由一个中心文件 `config.yaml` 控制，该文件
 这些参数定义了生成内容的基调、风格和深度。
 
 #### `documentPurpose`
-你希望读者实现的主要成果是什么？此设置会影响文档的整体结构和重点。
+定义你希望读者达到的主要成果。此设置会影响文档的整体结构和重点。
 
 | Option | Name | Description |
 |---|---|---|
 | `getStarted` | 快速入门 | 帮助新用户在 30 分钟内从零开始上手。 |
-| `completeTasks` | 完成特定任务 | 引导用户完成常见工作流和用例。 |
+| `completeTasks` | 完成特定任务 | 引导用户完成常见工作流程和用例。 |
 | `findAnswers` | 快速查找答案 | 为所有功能和 API 提供可搜索的参考。 |
 | `understandSystem`| 理解系统 | 解释其工作原理以及做出设计决策的原因。 |
-| `solveProblems` | 排查常见问题 | 帮助用户排查和修复问题。 |
+| `solveProblems` | 解决常见问题 | 帮助用户排查和修复问题。 |
 | `mixedPurpose` | 服务于多种目的 | 涵盖多种需求的文档。 |
 
 #### `targetAudienceTypes`
-谁会最常阅读这份文档？这个选择会影响写作风格和示例。
+定义最常阅读此文档的受众。此选择会影响写作风格和示例。
 
 | Option | Name | Description |
 |---|---|---|
-| `endUsers` | 最终用户（非技术人员） | 使用产品但不编写代码的人员。 |
+| `endUsers` | 最终用户（非技术人员） | 使用产品但不编码的人员。 |
 | `developers` | 集成你的产品/API 的开发者 | 将此添加到其项目中的工程师。 |
 | `devops` | DevOps / SRE / 基础设施团队 | 部署、监控和维护系统的团队。 |
 | `decisionMakers`| 技术决策者 | 评估或规划实施的架构师或负责人。 |
@@ -66,25 +66,25 @@ AIGNE DocSmith 的行为由一个中心文件 `config.yaml` 控制，该文件
 | `mixedTechnical`| 混合技术受众 | 开发者、DevOps 和其他技术用户。 |
 
 #### `readerKnowledgeLevel`
-读者通常具备哪些知识？这会调整所假定的基础知识水平。
+定义读者通常具备的知识水平。这会调整对基础知识的假设程度。
 
 | Option | Name | Description |
 |---|---|---|
-| `completeBeginners` | 完全的初学者，从零开始 | 完全不了解此领域/技术。 |
-| `domainFamiliar` | 之前使用过类似的工具 | 了解问题领域，但对这个具体解决方案不熟悉。 |
-| `experiencedUsers` | 希望完成特定任务的专家 | 需要参考或高级主题的普通用户。 |
+| `completeBeginners` | 完全的初学者，从零开始 | 完全不熟悉此领域/技术。 |
+| `domainFamiliar` | 之前使用过类似工具 | 了解问题领域，但对这个特定解决方案不熟悉。 |
+| `experiencedUsers` | 试图做特定事情的专家 | 需要参考或高级主题的常规用户。 |
 | `emergencyTroubleshooting`| 紧急情况/故障排查 | 出现问题，需要快速修复。 |
 | `exploringEvaluating` | 正在评估此工具并与其他工具进行比较 | 试图了解这是否符合他们的需求。 |
 
 #### `documentationDepth`
-文档应有多全面？
+定义文档应达到的全面程度。
 
 | Option | Name | Description |
 |---|---|---|
-| `essentialOnly` | 仅包含核心内容 | 覆盖 80% 的用例，保持简洁。 |
+| `essentialOnly` | 仅限基本内容 | 涵盖 80% 的用例，保持简洁。 |
 | `balancedCoverage`| 均衡覆盖 | 具有良好深度和实际示例 [推荐]。 |
-| `comprehensive` | 全面 | 覆盖所有功能、边缘情况和高级场景。 |
-| `aiDecide` | 由 AI 决定 | 分析代码复杂性并建议合适的深度。 |
+| `comprehensive` | 全面 | 涵盖所有功能、边缘情况和高级场景。 |
+| `aiDecide` | 让 AI 决定 | 分析代码复杂性并建议适当的深度。 |
 
 ### 自定义指令
 
@@ -92,8 +92,8 @@ AIGNE DocSmith 的行为由一个中心文件 `config.yaml` 控制，该文件
 
 | Parameter | Description |
 |---|---|
-| `rules` | 一个多行字符串，你可以在其中定义具体的文档生成规则和要求（例如，“始终包含性能基准测试”）。 |
-| `targetAudience`| 一个多行字符串，用于比预设更详细地描述你的特定目标受众及其特征。 |
+| `rules` | 一个多行字符串，你可以在其中定义特定的文档生成规则（例如，“始终包含性能基准测试”）。 |
+| `targetAudience`| 一个多行字符串，用于比预设更详细地描述你的特定目标受众。 |
 
 ### 语言和路径配置
 
@@ -101,7 +101,7 @@ AIGNE DocSmith 的行为由一个中心文件 `config.yaml` 控制，该文件
 
 | Parameter | Description |
 |---|---|
-| `locale` | 文档的主要语言（例如，`en`、`zh`）。 |
+| `locale` | 文档的主语言（例如，`en`、`zh`）。 |
 | `translateLanguages` | 要将文档翻译成的语言代码列表（例如，`[ja, fr, es]`）。 |
 | `docsDir` | 保存生成的文档文件的目录。 |
 | `sourcesPath` | 供 DocSmith 分析的源代码路径或 glob 模式列表（例如，`['./src', './lib/**/*.js']`）。 |
@@ -109,59 +109,38 @@ AIGNE DocSmith 的行为由一个中心文件 `config.yaml` 控制，该文件
 
 ## config.yaml 示例
 
-这是一个完整的配置文件示例，其中包含解释每个部分的注释。你可以随时直接编辑此文件以更改设置。
+这是一个完整的配置文件示例。你可以随时直接编辑此文件以更改设置。
 
 ```yaml Example config.yaml icon=logos:yaml
 # 用于文档发布的项目信息
 projectName: AIGNE DocSmith
-projectDesc: A powerful, AI-driven documentation generation tool.
+projectDesc: An AI-driven documentation generation tool.
 projectLogo: https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png
 
 # =============================================================================
 # 文档配置
 # =============================================================================
 
-# 目的：你希望读者实现的主要成果是什么？
-# 可用选项（根据需要取消注释并修改）：
-#   getStarted       - 快速入门：帮助新用户在 30 分钟内从零开始上手
-#   completeTasks    - 完成特定任务：引导用户完成常见工作流和用例
-#   findAnswers      - 快速查找答案：为所有功能和 API 提供可搜索的参考
-#   understandSystem - 理解系统：解释其工作原理以及做出设计决策的原因
-#   solveProblems    - 排查常见问题：帮助用户排查和修复问题
-#   mixedPurpose     - 服务于多种目的：涵盖多种需求的综合性文档
+# 目的：你希望读者达到的主要成果是什么？
+# 选项：getStarted, completeTasks, findAnswers, understandSystem, solveProblems, mixedPurpose
 documentPurpose:
   - completeTasks
   - findAnswers
 
-# 目标受众：谁会最常阅读这份文档？
-# 可用选项（根据需要取消注释并修改）：
-#   endUsers         - 最终用户（非技术人员）：使用产品但不编写代码的人员
-#   developers       - 集成你的产品/API 的开发者：将此添加到其项目中的工程师
-#   devops           - DevOps / SRE / 基础设施团队：部署、监控、维护系统的团队
-#   decisionMakers   - 技术决策者：评估或规划实施的架构师、负责人
-#   supportTeams     - 支持团队：帮助他人使用产品的人员
-#   mixedTechnical   - 混合技术受众：开发者、DevOps 和技术用户
+# 目标受众：谁会最常阅读此文档？
+# 选项：endUsers, developers, devops, decisionMakers, supportTeams, mixedTechnical
 targetAudienceTypes:
   - developers
 
-# 读者知识水平：读者通常具备哪些知识？
-# 可用选项（根据需要取消注释并修改）：
-#   completeBeginners    - 完全的初学者，从零开始：完全不了解此领域/技术
-#   domainFamiliar       - 之前使用过类似的工具：了解问题领域，但对这个具体解决方案不熟悉
-#   experiencedUsers     - 希望完成特定任务的专家：需要参考/高级主题的普通用户
-#   emergencyTroubleshooting - 紧急情况/故障排查：出现问题，需要快速修复
-#   exploringEvaluating  - 正在评估此工具并与其他工具进行比较：试图了解这是否符合他们的需求
+# 读者知识水平：读者通常具备什么知识？
+# 选项：completeBeginners, domainFamiliar, experiencedUsers, emergencyTroubleshooting, exploringEvaluating
 readerKnowledgeLevel: domainFamiliar
 
-# 文档深度：文档应有多全面？
-# 可用选项（根据需要取消注释并修改）：
-#   essentialOnly      - 仅包含核心内容：覆盖 80% 的用例，保持简洁
-#   balancedCoverage   - 均衡覆盖：具有良好深度和实际示例 [推荐]
-#   comprehensive      - 全面：覆盖所有功能、边缘情况和高级场景
-#   aiDecide           - 由 AI 决定：分析代码复杂性并建议合适的深度
+# 文档深度：文档应该有多全面？
+# 选项：essentialOnly, balancedCoverage, comprehensive, aiDecide
 documentationDepth: balancedCoverage
 
-# 自定义规则：定义具体的文档生成规则和要求
+# 自定义规则：定义特定的文档生成规则和要求
 rules: |+
   
 
@@ -169,18 +148,25 @@ rules: |+
 targetAudience: |+
   
 
-# 术语表：定义项目特定的术语和定义
-# glossary: "@glossary.md"  # 包含术语表定义的 markdown 文件路径
+# 术语表：包含项目特定术语和定义的 markdown 文件的路径
+# glossary: "@glossary.md"
 
+# 文档的主语言
 locale: en
-# translateLanguages:  # 要将文档翻译成的语言列表
-#   - zh  # 示例：中文翻译
-#   - fr  # 示例：法语翻译
-docsDir: .aigne/doc-smith/docs  # 保存生成的文档的目录
-sourcesPath:  # 要分析的源代码路径
+
+# 要将文档翻译成的语言列表
+# translateLanguages:
+#   - zh
+#   - fr
+
+# 保存生成的文档的目录
+docsDir: .aigne/doc-smith/docs
+
+# 要分析的源代码路径
+sourcesPath:
   - ./
 ```
 
-配置设置完成后，你就可以创建符合项目需求的文档了。下一步是运行生成命令。
+完成配置后，你就可以创建符合项目需求的文档了。下一步是运行生成命令。
 
 ➡️ **下一步：** [生成文档](./features-generate-documentation.md)

package/docs/features-generate-documentation.md

@@ -1,8 +1,6 @@
 # Generate Documentation
 
-The `aigne doc generate` command is the core function of DocSmith, designed to transform your source code into a structured documentation suite with a single command.
-
-This process analyzes your codebase, plans a logical document structure, and then generates content for each section. It's the primary way to create your documentation from scratch.
+The `aigne doc generate` command is the core function for creating a complete documentation set from your source code. This process analyzes your codebase, plans a logical document structure, and then generates content for each section. It's the primary way to create your documentation from scratch.
 
 ## Your First Generation
 
@@ -14,17 +12,18 @@ aigne doc generate
 
 ### Automatic Configuration
 
-If you're running this command for the first time in a project, DocSmith will detect that no configuration exists. It will automatically launch an interactive setup wizard to guide you through the initial setup. This ensures you have a properly configured environment before generation begins.
+If you run this command for the first time in a project, DocSmith detects that no configuration exists. It will then launch an interactive setup wizard to guide you through the initial setup. This ensures you have a properly configured environment before generation begins.
 
 ![Running the generate command for the first time triggers the setup wizard](https://docsmith.aigne.io/image-bin/uploads/0c45a32667c5250e54194a61d9495965.png)
 
 You will be asked a series of questions to define:
+
 - Document generation rules and style
 - The target audience
 - Primary and translation languages
 - Source code and output paths
 
-![Answer a few questions to configure your documentation style, languages, and source paths](https://docsmith.aigne.io/image-bin/uploads/fbedbfa256036ad6375a6c18047a75ad.png)
+![Answer the questions to configure your documentation style, languages, and source paths](https://docsmith.aigne.io/image-bin/uploads/fbedbfa256036ad6375a6c18047a75ad.png)
 
 Once the configuration is complete, DocSmith proceeds with the documentation generation.
 
@@ -36,7 +35,7 @@ Upon successful completion, your newly created documentation will be available i
 
 ## The Generation Process
 
-The `generate` command follows an automated workflow to ensure consistent results. The process can be visualized as follows:
+The `generate` command follows an automated workflow. The process can be visualized as follows:
 
 ```d2
 direction: down
@@ -98,5 +97,5 @@ While the default `generate` command is sufficient for most use cases, you can u
 Now that you have generated your initial documentation, your project will continue to evolve. To keep your documents synchronized with your code, you will need to update them. Proceed to the next section to learn how to make targeted changes and regenerate specific files.
 
 <x-card data-title="Update and Refine" data-icon="lucide:file-edit" data-href="/features/update-and-refine">
-  Discover how to update documents when your code changes or make specific improvements using feedback.
+  Learn how to update documents when your code changes or make specific improvements using feedback.
 </x-card>

package/docs/features-generate-documentation.zh.md

@@ -1,12 +1,10 @@
 # 生成文档
 
-`aigne doc generate` 命令是 DocSmith 的核心功能，旨在通过一个命令将您的源代码转换为结构化的文档套件。
-
-该过程会分析您的代码库，规划逻辑文档结构，然后为每个部分生成内容。这是从零开始创建文档的主要方式。
+`aigne doc generate` 命令是从源代码创建完整文档集的核心功能。该过程会分析你的代码库，规划逻辑化的文档结构，然后为每个部分生成内容。这是从零开始创建文档的主要方式。
 
 ## 首次生成
 
-首先，请导航至您项目的根目录并运行以下命令：
+首先，请导航到项目的根目录并运行以下命令：
 
 ```bash
 aigne doc generate
@@ -14,29 +12,30 @@ aigne doc generate
 
 ### 自动配置
 
-如果您首次在项目中运行此命令，DocSmith 会检测到尚无配置。它将自动启动交互式设置向导，引导您完成初始设置。这可以确保您在生成开始前拥有一个正确配置的环境。
+如果这是你首次在项目中运行此命令，DocSmith 会检测到尚无配置。接着，它将启动一个交互式设置向导，引导你完成初始设置。这能确保在生成开始前，你拥有一个正确配置的环境。
 
 ![首次运行 generate 命令会触发设置向导](https://docsmith.aigne.io/image-bin/uploads/0c45a32667c5250e54194a61d9495965.png)
 
-系统会询问您一系列问题，用于定义：
+系统将询问你一系列问题，以定义：
+
 - 文档生成规则和风格
 - 目标受众
 - 主要语言和翻译语言
 - 源代码和输出路径
 
-![回答几个问题以配置您的文档风格、语言和源路径](https://docsmith.aigne.io/image-bin/uploads/fbedbfa256036ad6375a6c18047a75ad.png)
+![回答问题以配置文档风格、语言和源路径](https://docsmith.aigne.io/image-bin/uploads/fbedbfa256036ad6375a6c18047a75ad.png)
 
-配置完成后，DocSmith 会继续进行文档生成。
+配置完成后，DocSmith 将继续进行文档生成。
 
-![DocSmith 会分析您的代码、规划结构并生成每个文档](https://docsmith.aigne.io/image-bin/uploads/d0766c19380a02eb8a6f8ce86a838849.png)
+![DocSmith 分析你的代码、规划结构并生成每个文档](https://docsmith.aigne.io/image-bin/uploads/d0766c19380a02eb8a6f8ce86a838849.png)
 
-成功完成后，您新创建的文档将位于您指定的输出目录中。
+成功完成后，新创建的文档将位于你指定的输出目录中。
 
-![完成后，您将在指定的输出目录中找到新文档](https://docsmith.aigne.io/image-bin/uploads/0967443611408ad9d0042793d590b8fd.png)
+![完成后，你将在指定的输出目录中找到新文档](https://docsmith.aigne.io/image-bin/uploads/0967443611408ad9d0042793d590b8fd.png)
 
 ## 生成过程
 
-`generate` 命令遵循自动化工作流以确保结果的一致性。该过程可按如下方式可视化：
+`generate` 命令遵循一个自动化的工作流程。该过程可直观地表示如下：
 
 ```d2
 direction: down
@@ -57,7 +56,7 @@ interactive_setup: "启动交互式设置向导" {
   shape: rectangle
 }
 
-plan_structure: "1. 分析代码和规划结构" {
+plan_structure: "1. 分析代码并规划结构" {
   shape: rectangle
 }
 
@@ -85,18 +84,18 @@ save_docs -> end
 
 ## 命令选项
 
-虽然默认的 `generate` 命令足以满足大多数用例，但您可以使用多个选项来控制生成过程。这些选项对于重新生成内容或优化文档结构非常有用。
+虽然默认的 `generate` 命令足以满足大多数使用场景，但你可以使用几个选项来控制生成过程。这些选项在重新生成内容或优化文档结构时非常有用。
 
-| 选项                | 描述                                                                                                                                     | 示例                                                                 |
-|---------------------|------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
-| `--forceRegenerate` | 删除所有现有文档并从头开始重新生成。在对源代码或配置进行重大更改后使用此选项。                                                                 | `aigne doc generate --forceRegenerate`                                 |
-| `--feedback`        | 提供高层级反馈以优化整体文档结构规划，例如添加、删除或重组部分。                                                                             | `aigne doc generate --feedback "添加一个 API 参考部分"`                  |
-| `--model`           | 指定 AIGNE Hub 中的特定大型语言模型用于内容生成，允许您在不同模型之间切换。                                                                  | `aigne doc generate --model claude:claude-3-5-sonnet`                |
+| 选项                | 描述                                                                                                                             | 示例                                                                 |
+|---------------------|----------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
+| `--forceRegenerate` | 删除所有现有文档并从头开始重新生成。在对源代码或配置进行重大更改后使用此选项。                                                     | `aigne doc generate --forceRegenerate`                                 |
+| `--feedback`        | 提供高层反馈以优化整体文档结构，例如添加、删除或重组章节。                                                                       | `aigne doc generate --feedback "Add an API Reference section"`         |
+| `--model`           | 指定 AIGNE Hub 中的特定大型语言模型用于内容生成，允许你切换模型。                                                                  | `aigne doc generate --model claude:claude-3-5-sonnet`                |
 
-## 后续步骤
+## 接下来做什么？
 
-既然您已经生成了初始文档，您的项目将继续发展。为了使文档与代码保持同步，您需要更新它们。请继续阅读下一部分，了解如何进行有针对性的更改和重新生成特定文件。
+既然你已经生成了初始文档，你的项目将继续演进。为使文档与代码保持同步，你需要更新它们。请继续阅读下一部分，了解如何进行有针对性的更改和重新生成特定文件。
 
 <x-card data-title="更新和优化" data-icon="lucide:file-edit" data-href="/features/update-and-refine">
-  了解当代码发生变化时如何更新文档，或使用反馈进行特定改进。
+  了解当代码变更时如何更新文档，或使用反馈进行特定改进。
 </x-card>

package/docs/features-publish-your-docs.md

@@ -1,14 +1,12 @@
 # Publish Your Docs
 
-Once your documentation is generated, the next step is to make it accessible online. AIGNE DocSmith simplifies this process with the `aigne doc publish` command, which uploads your content to a Discuss Kit platform, making it available to your audience.
-
-This guide covers how to publish your documentation, whether you are using the official platform or your own website.
+After generating your documentation, the `aigne doc publish` command uploads your content to a Discuss Kit platform, making it accessible online. This guide explains how to publish your documentation to either the official platform or your own self-hosted website.
 
 ## The Publishing Process
 
-The `aigne doc publish` command initiates an interactive process that guides you through the necessary steps. The diagram below shows the typical workflow for publishing your documentation for the first time.
+The `aigne doc publish` command initiates an interactive process. The first time you publish to a new destination, it will guide you through authentication. Subsequent publishes will use saved credentials.
 
-```d2
+```d2 The Publishing Flow icon=lucide:upload-cloud
 direction: down
 shape: sequence_diagram
 
@@ -32,47 +30,49 @@ alt: "First-time publish or missing config" {
 CLI -> Platform: "Uploads docs & media files"
 Platform -> CLI: "Success response"
 CLI -> User: "✅ Published Successfully!"
+
 ```
 
 ## Publishing Options
 
-You have two primary options for hosting your documentation, catering to different needs for visibility and control.
-
-### Official Platform
-
-Publish to [docsmith.aigne.io](https://docsmith.aigne.io), the official hosting platform. This option is free, makes your documentation publicly accessible, and is recommended for open-source projects.
-
-### Your Own Website
+You have two main options for hosting your documentation:
 
-Publish to your own website by running a Discuss Kit instance. This gives you full control over who can access your documentation, making it suitable for internal or private projects. You can get started with running your own Discuss Kit from the [official store](https://www.arcblock.io/store/z8iZhf67n368m2k5a9fXvCL778jAnf3e5n2b).
+<x-cards data-columns="2">
+  <x-card data-title="Official Platform" data-icon="lucide:globe">
+    Publish to [docsmith.aigne.io](https://docsmith.aigne.io/app/), a free, public hosting platform provided by AIGNE. This is a good option for open-source projects or to quickly share your docs.
+  </x-card>
+  <x-card data-title="Your Own Website" data-icon="lucide:server">
+    Publish to your own Discuss Kit instance for full control over access and branding. This is suitable for internal or private documentation. You can get a Discuss Kit instance from the [Blocklet Store](https://store.blocklet.dev/blocklets/z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu).
+  </x-card>
+</x-cards>
 
 ## Step-by-Step Guide
 
-Publishing your documentation for the first time is a simple, interactive process.
+Follow these steps to publish your documentation for the first time.
 
 ### 1. Run the Publish Command
 
-Navigate to your project's root directory in your terminal and run the following command:
+In your project's root directory, run the following command:
 
-```bash
+```bash Terminal icon=lucide:terminal
 aigne doc publish
 ```
 
 ### 2. Choose Your Platform
 
-If you have not configured a publishing destination before, you will be prompted to choose between the official platform and a self-hosted one. Select the option that best suits your needs.
+If this is your first time publishing, you will be prompted to select a destination. Choose the option that fits your needs.
 
 ![Choose between the official platform or a self-hosted instance](https://docsmith.aigne.io/image-bin/uploads/9fd929060b5abe13d03cf5eb7aea85aa.png)
 
-If you select your own website, you will be asked to enter the URL for your Discuss Kit instance.
+If you select your own website, you will be asked to enter its URL.
 
 ### 3. Authenticate Your Account
 
-For the first connection to a new platform, DocSmith will automatically open a browser window for you to log in and authorize the CLI. This is a one-time step; your access token will be saved locally for all future publishes to that platform.
+For the first connection to a new platform, a browser window will open for you to log in and authorize the CLI. This is a one-time step per platform; your access token is saved locally in `~/.aigne/doc-smith-connected.yaml` for future use.
 
 ### 4. Confirmation
 
-Once the upload is complete, you will see a success message in your terminal, and your documentation will be live.
+Once the upload is complete, a success message will appear in your terminal.
 
 ```
 ✅ Documentation Published Successfully!
@@ -80,20 +80,28 @@ Once the upload is complete, you will see a success message in your terminal, an
 
 ## Publishing in CI/CD Environments
 
-For automated workflows, you can bypass the interactive prompts by using command-line arguments or environment variables.
+For automated workflows, you can provide arguments and environment variables to bypass the interactive prompts.
 
-| Method     | Name                           | Description                                                                              | Example                                                     |
-| ---------- | ------------------------------ | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
-| **Argument** | `--appUrl`                     | Specifies the URL of your Discuss Kit instance directly.                                 | `aigne doc publish --appUrl https://docs.mycompany.com`       |
-| **Env Var**  | `DOC_DISCUSS_KIT_URL`          | Sets the target platform URL, overriding any other configuration.                        | `export DOC_DISCUSS_KIT_URL=...`                              |
-| **Env Var**  | `DOC_DISCUSS_KIT_ACCESS_TOKEN` | Provides the access token directly, skipping the interactive login.                      | `export DOC_DISCUSS_KIT_ACCESS_TOKEN=...`                     |
+| Method | Name | Description |
+|---|---|---|
+| **Argument** | `--appUrl` | Specifies the URL of your Discuss Kit instance directly. |
+| **Env Var** | `DOC_DISCUSS_KIT_ACCESS_TOKEN` | Provides the access token, skipping the interactive login. |
+
+Here is an example of a non-interactive publish command suitable for a CI/CD pipeline:
+
+```bash CI/CD Example icon=lucide:workflow
+export DOC_DISCUSS_KIT_ACCESS_TOKEN="your_access_token_here"
+aigne doc publish --appUrl https://docs.mycompany.com
+```
 
 ## Troubleshooting
 
-If you encounter issues during the publishing process, here are some common causes and their solutions:
+If you encounter an issue during publishing, check for these common problems:
+
+- **Connection Error**: The provided URL for your self-hosted instance might be incorrect, or the server may be unreachable. Verify the URL and your network connection.
+
+- **Invalid Website URL**: The URL must point to a valid website built on the ArcBlock platform. The CLI will show an error like `The provided URL is not a valid website on ArcBlock platform`. To host your documentation, you can start by getting a [Discuss Kit instance from the store](https://store.blocklet.dev/blocklets/z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu).
 
--   **Connection Error**: This can happen if the provided URL for your own instance is incorrect or the server is not reachable. Check the URL and your network connection.
--   **Invalid Website URL**: The provided URL is not a valid website on the ArcBlock platform. To host your documentation, you need a website running on this platform. You can start by visiting the [Discuss Kit Store](https://www.arcblock.io/store/z8iZhf67n368m2k5a9fXvCL778jAnf3e5n2b).
--   **Missing Required Components**: The destination website must have the Discuss Kit component installed to host the documentation. If it is missing, the CLI will return an error with guidance on how to add the component. You can find instructions in the [Discuss Kit documentation](https://www.arcblock.io/docs/web3-kit/en/discuss-kit).
+- **Missing Required Components**: The destination website must have the Discuss Kit component installed. If it is missing, the CLI will return an error like `This website does not have required components for publishing`. Please refer to the [Discuss Kit documentation](https://www.arcblock.io/docs/web3-kit/en/discuss-kit) to add the necessary component.
 
 For a complete list of commands and options, refer to the [CLI Command Reference](./cli-reference.md).

package/docs/features-publish-your-docs.zh.md

@@ -1,30 +1,28 @@
 # 发布你的文档
 
-文档生成后，下一步是使其可以在线访问。AIGNE DocSmith 通过 `aigne doc publish` 命令简化了这一过程，该命令会将你的内容上传到 Discuss Kit 平台，供你的受众访问。
+生成文档后，`aigne doc publish` 命令会将你的内容上传到 Discuss Kit 平台，使其可以在线访问。本指南将说明如何将文档发布到官方平台或你自己的自托管网站。
 
-本指南将介绍如何发布文档，无论你是使用官方平台还是自己的网站。
+## 发布过程
 
-## 发布流程
+`aigne doc publish` 命令会启动一个交互式过程。当你首次发布到新目标时，它将引导你完成身份验证。后续的发布将使用已保存的凭据。
 
-`aigne doc publish` 命令会启动一个交互式流程，引导你完成必要的步骤。下图展示了首次发布文档的典型工作流程。
-
-```d2
+```d2 发布流程 icon=lucide:upload-cloud
 direction: down
 shape: sequence_diagram
 
 User: { shape: c4-person }
 CLI: { label: "AIGNE CLI" }
-Browser: { label: "Browser" }
-Platform: { label: "Discuss Kit Platform" }
+Browser: { label: "浏览器" }
+Platform: { label: "Discuss Kit 平台" }
 
 User -> CLI: "aigne doc publish"
 
 alt: "首次发布或缺少配置" {
-  CLI -> User: "选择平台\n（官方/自托管）"
+  CLI -> User: "选择平台\n(官方 / 自托管)"
   User -> CLI: "提供选择"
   CLI -> Browser: "打开认证 URL"
   User -> Browser: "登录并授权"
-  Browser -> Platform: "发送凭证"
+  Browser -> Platform: "发送凭据"
   Platform -> CLI: "返回访问令牌"
   CLI -> CLI: "保存令牌以备将来使用"
 }
@@ -32,47 +30,49 @@ alt: "首次发布或缺少配置" {
 CLI -> Platform: "上传文档和媒体文件"
 Platform -> CLI: "成功响应"
 CLI -> User: "✅ 发布成功！"
+
 ```
 
 ## 发布选项
 
-你有两种主要选项来托管文档，以满足对可见性和控制的不同需求。
-
-### 官方平台
-
-发布到官方托管平台 [docsmith.aigne.io](https://docsmith.aigne.io)。此选项免费，可使你的文档公开访问，推荐用于开源项目。
-
-### 你自己的网站
+你有两种主要选项来托管你的文档：
 
-通过运行 Discuss Kit 实例发布到你自己的网站。这使你可以完全控制谁能访问你的文档，适合内部或私有项目。你可以从[官方商店](https://www.arcblock.io/store/z8iZhf67n368m2k5a9fXvCL778jAnf3e5n2b)开始运行你自己的 Discuss Kit。
+<x-cards data-columns="2">
+  <x-card data-title="官方平台" data-icon="lucide:globe">
+    发布到 [docsmith.aigne.io](https://docsmith.aigne.io/app/)，这是 AIGNE 提供的一个免费的公共托管平台。对于开源项目或希望快速分享文档的用户来说，这是一个不错的选择。
+  </x-card>
+  <x-card data-title="你自己的网站" data-icon="lucide:server">
+    发布到你自己的 Discuss Kit 实例，以完全控制访问和品牌。这适用于内部或私有文档。你可以从 [Blocklet 商店](https://store.blocklet.dev/blocklets/z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu) 获取 Discuss Kit 实例。
+  </x-card>
+</x-cards>
 
 ## 分步指南
 
-首次发布文档是一个简单的交互式过程。
+按照以下步骤首次发布你的文档。
 
 ### 1. 运行发布命令
 
-在终端中导航到项目根目录，并运行以下命令：
+在你的项目根目录中，运行以下命令：
 
-```bash
+```bash Terminal icon=lucide:terminal
 aigne doc publish
 ```
 
 ### 2. 选择你的平台
 
-如果你之前没有配置过发布目的地，系统将提示你在官方平台和自托管平台之间进行选择。请选择最适合你需求的选项。
+如果这是你第一次发布，系统将提示你选择一个目标。选择适合你需求的选项。
 
 ![在官方平台或自托管实例之间选择](https://docsmith.aigne.io/image-bin/uploads/9fd929060b5abe13d03cf5eb7aea85aa.png)
 
-如果你选择自己的网站，系统将要求你输入 Discuss Kit 实例的 URL。
+如果你选择自己的网站，系统将要求你输入其 URL。
 
-### 3. 认证你的账户
+### 3. 验证你的账户
 
-首次连接到新平台时，DocSmith 会自动打开浏览器窗口，以便你登录并授权 CLI。这是一个一次性步骤；你的访问令牌将保存在本地，用于将来对该平台的所有发布操作。
+首次连接到新平台时，浏览器窗口将打开，以便你登录并授权 CLI。每个平台只需执行此步骤一次；你的访问令牌会保存在本地的 `~/.aigne/doc-smith-connected.yaml` 文件中，以供将来使用。
 
 ### 4. 确认
 
-上传完成后，你将在终端看到一条成功消息，你的文档即已上线。
+上传完成后，你的终端将显示一条成功消息。
 
 ```
 ✅ 文档发布成功！
@@ -80,20 +80,28 @@ aigne doc publish
 
 ## 在 CI/CD 环境中发布
 
-对于自动化工作流，你可以使用命令行参数或环境变量来绕过交互式提示。
+对于自动化工作流，你可以提供参数和环境变量来绕过交互式提示。
 
-| Method     | Name                           | Description                                                                              | Example                                                     |
-| ---------- | ------------------------------ | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
-| **Argument** | `--appUrl`                     | 直接指定你的 Discuss Kit 实例的 URL。                                 | `aigne doc publish --appUrl https://docs.mycompany.com`       |
-| **Env Var**  | `DOC_DISCUSS_KIT_URL`          | 设置目标平台 URL，覆盖任何其他配置。                        | `export DOC_DISCUSS_KIT_URL=...`                              |
-| **Env Var**  | `DOC_DISCUSS_KIT_ACCESS_TOKEN` | 直接提供访问令牌，跳过交互式登录。                      | `export DOC_DISCUSS_KIT_ACCESS_TOKEN=...`                     |
+| 方法 | 名称 | 描述 |
+|---|---|---|
+| **参数** | `--appUrl` | 直接指定你的 Discuss Kit 实例的 URL。 |
+| **环境变量** | `DOC_DISCUSS_KIT_ACCESS_TOKEN` | 提供访问令牌，跳过交互式登录。 |
+
+以下是一个适用于 CI/CD 流程的非交互式发布命令示例：
+
+```bash CI/CD Example icon=lucide:workflow
+export DOC_DISCUSS_KIT_ACCESS_TOKEN="your_access_token_here"
+aigne doc publish --appUrl https://docs.mycompany.com
+```
 
 ## 故障排除
 
-如果你在发布过程中遇到问题，以下是一些常见原因及其解决方案：
+如果你在发布过程中遇到问题，请检查以下常见问题：
+
+- **连接错误**：提供的自托管实例 URL 可能不正确，或者服务器可能无法访问。请验证 URL 和你的网络连接。
+
+- **无效的网站 URL**：该 URL 必须指向一个基于 ArcBlock 平台构建的有效网站。CLI 将显示类似 `The provided URL is not a valid website on ArcBlock platform` 的错误。要托管你的文档，你可以先从[商店获取一个 Discuss Kit 实例](https://store.blocklet.dev/blocklets/z8ia1WEiBZ7hxURf6LwH21Wpg99vophFwSJdu)。
 
--   **连接错误**：如果提供的自有实例 URL 不正确或服务器无法访问，可能会发生此问题。请检查 URL 和你的网络连接。
--   **无效的网站 URL**：提供的 URL 不是 ArcBlock 平台上的有效网站。要托管你的文档，你需要一个在该平台上运行的网站。你可以从访问 [Discuss Kit 商店](https://www.arcblock.io/store/z8iZhf67n368m2k5a9fXvCL778jAnf3e5n2b) 开始。
--   **缺少必需组件**：目标网站必须安装 Discuss Kit 组件才能托管文档。如果缺少该组件，CLI 将返回错误并提供有关如何添加该组件的指导。你可以在 [Discuss Kit 文档](https://www.arcblock.io/docs/web3-kit/en/discuss-kit) 中找到相关说明。
+- **缺少必需组件**：目标网站必须安装 Discuss Kit 组件。如果缺少该组件，CLI 将返回类似 `This website does not have required components for publishing` 的错误。请参阅 [Discuss Kit 文档](https://www.arcblock.io/docs/web3-kit/en/discuss-kit) 以添加必要的组件。
 
-如需完整的命令和选项列表，请参阅 [CLI 命令参考](./cli-reference.md)。
+有关命令和选项的完整列表，请参阅 [CLI 命令参考](./cli-reference.md)。