# 内容编辑工作流程 ## 目的该技能指导创建和编辑 InfluxData 文档的完整工作流程，从最初的内容创建到测试和验证。它集成了文档 CLI 工具、MCP 服务器事实检查、共享内容管理和综合测试。 **在以下情况下使用此技能：** * 创建新的文档页面 * 编辑现有文档 * 处理影响多个页面的共享内容 * 验证文档的准确性和功能 ## 快速决策树需要决定何时使用 CLI 与直接编辑？ └─ 请参阅 docs-cli-workflow 技能以获取决策指导进行了内容更改吗？ ├─ 分享内容？触摸采购文件！（参见第 1 部分：共享内容） ├─ Run Vale linting（参见第 3 部分：Vale 风格 Linting） └─ 运行测试（参见第 2 部分：测试）需要验证技术准确性吗？ └─ 使用文档MCP服务器（参见第4部分：事实检查）需要编写/调试 Vale 规则吗？ └─ 请参阅 vale-rule-config 技能（针对 CI/质量工程师） ## 使用 `docs create` 和 `docs edit` **有关何时以及如何使用 docs CLI 工具的详细指南**，请参阅 **docs-cli-workflow** 技能，其中涵盖： * 何时建议“创建文档”与直接创建文件 * 何时建议“文档编辑”与直接文件编辑 * CLI命令语法和示例 * 如何向用户呈现推荐 * 边缘情况和用户偏好处理 **此工作流程的快速参考：** # 从草稿创建新文档文档 create <草稿路径> --products <产品密钥> # 通过 URL 或路径编辑现有文档文档编辑 # 无需打开编辑器即可列出文件（代理友好）文档编辑 --list # 将占位符语法添加到代码块中文档占位符 # 重要提示：默认情况下这两个命令都是非阻塞的 # - 在后台启动编辑器 # - 立即返回（代理友好） # - 使用 --wait 标志来阻止行为 ## 第 1 部分：共享内容管理 ### 什么是共享内容？出现在多个产品中的内容使用 Hugo 的 **内容适配器** 模式：内容/ ├── 共享/ │ └── influxdb3/ │ └── 管理/ │ └──databases.md # 实际内容在这里 ├── influxdb3/ │ ├── 核心/ │ │ └── 管理/ │ │ └──databases.md # 仅 Frontmatter，有来源： │ └── 企业/ │ └── 管理/ │ └──databases.md # 仅 Frontmatter，有来源： **Frontmatter 文件示例：** --- 书名：数据库管理来源：/content/shared/influxdb3/admin/databases.md --- ### 关键：接触源文件 **当您编辑共享内容文件时，Hugo 不会自动重建引用它的页面。** 您必须触摸 frontmatter 文件才能触发重建： # 手动方法触摸内容/influxdb3/core/admin/databases.md 触摸内容/influxdb3/enterprise/admin/databases.md ### 自动（推荐） **使用`docs edit`** \ - 它会自动处理这个问题： # 该命令将： # 1.找到共享源文件 # 2. 查找引用它的所有 frontmatter 文件 # 3. 打开所有文件进行编辑 # 4.您编辑共享文件 # 5. Hugo 看到 frontmatter 文件的更改并重建文档编辑/influxdb3/core/admin/databases/ ### 程序化检测如果您需要在代码中处理这个问题： // 检查文件是否是源文件（仅限 frontmatter）从 'fs' 导入 { readFileSync }；从“灰质”导入物质；函数 isSharedContent(文件路径) { const content = readFileSync(filePath, 'utf8'); const { 数据，内容：正文 } = 物质（内容）； // 如果有来源：frontmatter 和最少/无正文内容返回 data.source && body.trim().length < 50; } 函数 getSharedSource(文件路径) { const content = readFileSync(filePath, 'utf8'); const { 数据 } = 物质（内容）；返回数据源； // 例如，“/content/shared/influxdb3/admin/databases.md” } ### 为什么这很重要 **无法触及源文件意味着：** * Hugo 不会重建页面 * 您的更改不会出现在测试/预览中 * 测试将会失败，因为内容没有改变 * 发布的网站不会反映您的编辑 ### 检查路径差异并添加 `alt_links` 创建或编辑共享内容时，请检查产品之间的 URL 路径是否不同。如果存在，请将“alt_links”frontmatter 添加到每个产品文件中以交叉引用等效页面。有关语法和示例，请参阅 [DOCS-FRONTMATTER.md]()。 ### 检查产品资源术语是否交叉引用产品资源术语通常出现在“代码占位符键”短代码文本和项目符号文本中。产品资源术语示例： *“数据库令牌” *“数据库名称” ## 第 2 部分：测试工作流程进行内容更改后，运行测试来验证： ### 1\. Hugo 构建测试（必需） # 验证 Hugo 可以构建站点纱线雨果——安静 # 查找类似以下的错误： # - 模板错误 # - 缺少部分内容 # - 无效的 frontmatter # - 损坏的简码 ### 2\.链接验证（推荐） # 测试文档中的所有链接纱线测试：链接 # 这会检查： # - 内部链接（相对路径） # - 交叉引用 # - 锚链接 ### 3\.代码块测试（对于带有示例的页面） # 测试文档中的所有代码示例纱线测试：代码块：全部 # 测试标记为的代码块： # - 可测试：true # - 验证语法 # - 可以执行示例（适用于支持的语言） ### 4\. E2E测试（针对特定页面）使用 **cypress-e2e-testing** 技能进行全面的页面测试： # 测试具体内容文件节点 cypress/support/run-e2e-specs.js content/influxdb3/core/admin/databases/_index.md # 测试API参考页（首先需要yarn build:api-docs）节点 cypress/support/run-e2e-specs.js \ --spec“cypress/e2e/content/api-reference.cy.js”\ 内容/influxdb3/core/reference/api/_index.md **重要先决条件：** * API 测试：首先运行 `yarn build:api-docs` * Markdown 验证：首先运行 `yarnhugo --quiet &&yarn build:md` 请参阅 **cypress-e2e-testing** 技能了解详细的测试工作流程。 ### 5\.样式 Linting（预提交） Vale 风格的 linting 通过预提交挂钩自动运行，但您可以手动运行它： # Lint 特定文件 .ci/vale/vale.sh --config=.vale.ini 内容/influxdb3/core/path/to/file.md # 具有最低警报级别的 Lint .ci/vale/vale.sh --config=.vale.ini --minAlertLevel=警告内容/路径/ # 同步 Vale 包（.vale.ini 更改后） .ci/vale/vale.sh 同步 **常见问题：** * `admin` 标记 → 在散文中使用“管理员”，或者在代码上下文中 * 持续时间文字 (`30d`) → 这些是有效的 InfluxDB 语法 * 标记技术术语 → 添加到 `.ci/vale/styles/InfluxDataDocs/Terms/ignore.txt` 请参阅 **vale-linting** 技能了解完整的 Vale 工作流程。 ### 6\.视觉预览（可选） # 启动Hugo开发服务器纱线雨果服务器 # 访问http://localhost:1313 # 在浏览器中预览您的更改 ## 第 3 部分：Vale 风格 Linting Vale 检查文档中是否存在风格指南违规、拼写错误和品牌一致性。 **要编写 Vale 规则和理解正则表达式模式**，请参阅 **vale-rule-config** 技能。 ### 奔跑谷 # 基本 linting（所有 Markdown 文件） .ci/vale/vale.sh 内容/**/*.md # Lint 特定产品 .ci/vale/vale.sh 内容/influxdb3/core/**/*.md # 具有特定的配置和警报级别 .ci/vale/vale.sh \ --config=content/influxdb/cloud-dedicated/.vale.ini \ --minAlertLevel=错误 \ 内容/influxdb/云专用/写入数据/**/*.md ### 了解 Vale 警报淡水河谷报告了三个警报级别： * **错误**（红色）：严重问题 - 品牌违规、违反风格规则、被拒绝的条款 * **警告**（黄色）：风格指南建议 - 应该修复 * **建议**（蓝色）：可选改进 - 考虑修复 ### 修复常见的 Vale 问题 **拼写/词汇错误：** # 如果 Vale 标记了一个合法术语，请将其添加到词汇表中 echo“YourTerm”>>.ci/vale/styles/config/vocabularies/InfluxDataDocs/accept.txt **风格违规：** Vale 将建议正确的形式。例如： content/file.md:25:1：使用“InfluxDB 3”而不是“InfluxDB v3” 只需进行建议的更改即可。 **误报：** 如果 Vale 错误地标记了某些内容： 1. 检查它是否是应该出现在词汇表中的新技术术语 2.看看规则是否需要细化（查阅**vale-rule-config**技能） 3. 如有必要，添加内联注释以禁用特定规则：本段包含 Vale 可能标记的技术术语。 ### 何时运行 Vale * **提交之前** ：预提交挂钩自动运行 Vale * **内容更改后**：手动运行以尽早发现问题 * **在 CI/CD** ：自动处理拉取请求 ## 第 4 部分：使用文档 MCP 服务器进行事实检查 **InfluxDB 文档 MCP 服务器**允许您直接从 AI 助手搜索 InfluxDB 文档（此存储库中管理的渲染“内容”）和相关 InfluxData 参考（源代码 README、社区论坛和一些第三方工具文档）。 ### 何时使用文档 MCP 服务器文档 MCP 服务器中内容的主要来源是来自此存储库的完全呈现的“公共” HTML。当此处的信息不确定、需要加深对 InfluxData 产品和集成的理解或识别文档中的内容差距时，请使用文档 MCP 服务器。 **用于：** * 验证索赔的技术准确性 * 检查当前API语法 * 确认跨产品的功能可用性 * 理解复杂的产品行为 * 查找相关文档和代码示例 * 识别和分析文档中的内容差距 **请勿用于：** * 基本风格/语法检查（使用 Vale） * 链接验证（使用`yarn test:links`） * 测试代码示例（使用`yarn test:codeblocks`） ### 设置文档 MCP 服务器是托管的，无需本地安装。将服务器 URL 添加到 AI 助手的 MCP 配置中。 **MCP 服务器网址：** https://influxdb-docs.mcp.kapa.ai **Claude 桌面配置**（设置 > 开发人员）： { “mcp服务器”：{ “influxdb-docs”：{ “url”：“https://influxdb-docs.mcp.kapa.ai” } } } 对于其他 AI 助手，请参阅 [InfluxDB 文档 MCP 服务器指南]() 并验证特定 AI 助手的 MCP 配置选项和语法。 **速率限制**（每个 Google OAuth 用户）： * 每小时 40 个请求 * 每天 200 个请求 ### 可用工具 MCP 服务器公开了语义搜索工具： search_influxdb_knowledge_sources **它的作用：** * 搜索给定查询的所有 InfluxDB 文档 * 按相关性降序返回相关块 * 每个块包含 `source_url` 和 Markdown `content` **查询示例：** * “如何在 InfluxDB 3 Core 中创建数据库？” * “InfluxDB 3 Core 和企业集群有什么区别？” *“显示按时间范围过滤的 InfluxQL SELECT 语法” ### 示例工作流程：编辑期间的事实检查 ## 场景：编辑数据库管理文档 1. 声明草案：“InfluxDB 3 支持每个实例最多 10,000 个数据库” 2. 请AI助手使用MCP服务器进行验证： “InfluxDB 3 Core 和 Enterprise 中的数据库限制是什么？” 3. MCP 响应返回具有实际限制的文档块 4. 用准确的信息更新草稿 5. 如果需要，请在文档中引用 source_url ### 最佳实践 **做：** * 提出具体、有针对性的问题 * 验证有关功能、限制、语法的声明 * 交叉检查答案与提供的源 URL * 用于理解复杂的交互 **不要：** * 完全依赖 MCP，而不查看源文档 * 用于主观风格决策 * 期望实时产品行为（它搜索文档，而不是实时系统） * 用作测试的替代品（始终测试代码示例） ## 第 5 部分：完整的示例工作流程 ### 示例 1：创建新的多产品文档 # 第 1 步：根据草稿创建内容文档创建数据库-tutorial.md --产品 influxdb3-core,influxdb3-enterprise # CLI 脚手架文件： # - 内容/共享/influxdb3/guides/database-tutorial.md # - content/influxdb3/core/guides/database-tutorial.md (frontmatter) # - content/influxdb3/enterprise/guides/database-tutorial.md (frontmatter) # 第 2 步：验证技术准确性 # 让你的AI助手（配置了MCP）验证声明： #“验证 InfluxDB 3 的数据库创建语法” # 第 3 步：测试 Hugo 构建纱线雨果——安静 # 步骤 4：运行 E2E 测试节点 cypress/support/run-e2e-specs.js \ 内容/influxdb3/core/guides/database-tutorial.md # 第 5 步：验证链接纱线测试：链接 # 步骤 6：测试代码示例（如果教程有代码块）纱线测试：代码块：全部 ### 示例 2：编辑共享内容 # 第1步：查找并编辑内容文档编辑https://docs.influxdata.com/influxdb3/core/reference/sql/ # CLI 自动： # - 查找 content/shared/influxdb3/reference/sql/_index.md # - 查找引用它的所有 frontmatter 文件： # * 内容/influxdb3/core/reference/sql/_index.md # * 内容/influxdb3/enterprise/reference/sql/_index.md # * 内容/influxdb3/cloud-dedicated/reference/sql/_index.md # - 打开所有文件（保存时将触及源文件） # 第 2 步：编辑共享源文件 # 第 3 步：使用 MCP 进行事实核查变更 # 询问你的 AI 助手：“在 InfluxDB 3 中验证 SQL WHERE 子句语法” # 第 4 步：测试构建纱线雨果——安静 # 步骤 5：测试受影响的页面节点 cypress/support/run-e2e-specs.js \ 内容/influxdb3/core/reference/sql/_index.md \ 内容/influxdb3/enterprise/reference/sql/_index.md # 步骤 6：验证 SQL 参考中的链接纱线测试：链接 ### 示例 3：无需 CLI 的快速修复 # 第 1 步：直接修复拼写错误（你知道该文件） # 编辑内容/influxdb3/core/get-started/_index.md # 第 2 步：测试 Hugo 构建纱线雨果——安静 # 第 3 步：快速目视检查纱线雨果服务器 # 访问http://localhost:1313/influxdb3/core/get-started/ # 完成！（无需对拼写错误修复进行全面测试） ## 第 6 部分：故障排除 ### Hugo 构建失败 # 检查详细错误纱线雨果 # 常见问题： # - 无效的 frontmatter YAML # - 缺少结束短代码标签 # - 损坏的部分引用 # - 模板语法无效 ### 编辑共享内容后测试失败 **问题：** 编辑共享文件，但测试显示旧内容 **解决方案：** 手动触摸源文件 # 查找引用共享文件的页面 grep -r“来源：/content/shared/path/to/file.md”内容/ # 触摸每一个触摸内容/influxdb3/core/path/to/file.md 触摸内容/influxdb3/enterprise/path/to/file.md # 或者使用文档编辑（它会自动执行此操作） ### MCP 服务器没有响应托管的 MCP 服务器（“https://influxdb-docs.mcp.kapa.ai”）需要： 1. **Google OAuth 身份验证** \- 首次使用时，使用 Google 登录 2. **速率限制** \- 每个用户每小时 40 个请求，每天 200 个请求 **故障排除步骤：** * 验证您的AI助手是否正确配置了MCP服务器URL * 检查您是否超出了速率限制（等待一个小时或直到第二天） * 尝试通过清除 OAuth 会话来重新进行身份验证 * 确保您的网络允许连接到“*.kapa.ai” ### Cypress 测试失败全面调试请参见 **cypress-e2e-testing** 技巧： # 查看 Hugo 服务器日志猫 /tmp/hugo_server.log |尾部-50 # 交互运行测试纱柏开 # 检查API内容是否生成（用于API测试） ls内容/influxdb3/core/api/ # 如果为空：yarn build:api-docs ## 第 7 部分：快速参考任务|命令 ---|--- 创建新内容 | `文档创建 Draft.md --products <键或路径>` 按网址编辑 | `文档编辑 https://docs.influxdata.com/...` 列出文件而不进行编辑 | `文档编辑 --list` 将占位符添加到代码 | `docs 占位符 file.md` 或 `docs 占位符 file.md --dry` 审计文件| `文档审核 --products influxdb3_core` 或 `文档审核 --products /influxdb3/core` 生成发行说明 | `文档发行说明 v3.1.0 v3.2.0 --产品 influxdb3_core` 建立 Hugo 网站 | `纱线雨果——安静` 运行淡水河谷 linting | `.ci/vale/vale.sh --config=.vale.ini 内容/路径/` 测试链接| `纱线测试：链接` 测试代码块 | `纱线测试：代码块：全部` 测试特定页面 | `纱线测试：e2e内容/路径/文件.md` 与 MCP 进行事实核查 |使用已配置的“search_influxdb_knowledge_sources”工具询问 AI 助手本地预览 | `yarn Hugo 服务器`（访问 localhost:1313）生成 API 文档 | `yarn build:api-docs`（API 参考测试之前） **注意：** `--products` 接受产品密钥 (`influxdb3_core`) 和内容路径 (`/influxdb3/core`)。 ## 相关技能 * **docs-cli-workflow** \- 何时使用 CLI 与直接编辑（决策指导） * **vale-rule-config** \- 编写 Vale 规则并理解正则表达式模式（针对 CI/质量工程师） * **cypress-e2e-testing** \- 详细的 Cypress 测试执行和调试 * **hugo-template-dev** \- Hugo 模板语法和开发 * **vale-linting** \- Vale 风格的 linting 配置和调试 ## 清单：在声明内容完整之前 * 使用适当的方法（CLI 或直接）创建/编辑的内容 * 如果共享内容：触及源文件（或使用“文档编辑”） * 如果共享内容：检查路径差异，如果路径不同则添加 `alt_links` * 技术准确性已验证（如果需要，可进行 MCP 事实检查） * Hugo 构建没有错误（`yarn humo --quiet`） * Vale 风格的 linting 传递 (`.ci/vale/vale.sh --config=.vale.ini content/path/`) * 链接已验证（`yarn test:links`） * 测试过的代码示例（如果适用） * 受影响页面的端到端测试通过 * 视觉预览确认更改看起来正确 * 更新相关文档（如果需要）

内容编辑

包含技能