From 64542fa44d0556530756e5b8ad325bc31ccca6a7 Mon Sep 17 00:00:00 2001 From: xijing21 Date: Wed, 15 Jul 2026 16:59:42 +0800 Subject: [PATCH] docs: add documentation style guide and linting infrastructure Signed-off-by: xijing21 --- .github/workflows/markdown-lint.yml | 27 ++ .markdownlint-cli2.yaml | 109 +++++ CONTRIBUTING.md | 102 +++++ CONTRIBUTING.zh.md | 101 +++++ DOCUMENTATION_LINTING.zh.md | 246 +++++++++++ DOCUMENTATION_STYLEGUIDE.zh.md | 629 ++++++++++++++++++++++++++++ README.md | 27 ++ 7 files changed, 1241 insertions(+) create mode 100644 .github/workflows/markdown-lint.yml create mode 100644 .markdownlint-cli2.yaml create mode 100644 CONTRIBUTING.md create mode 100644 CONTRIBUTING.zh.md create mode 100644 DOCUMENTATION_LINTING.zh.md create mode 100644 DOCUMENTATION_STYLEGUIDE.zh.md create mode 100644 README.md diff --git a/.github/workflows/markdown-lint.yml b/.github/workflows/markdown-lint.yml new file mode 100644 index 000000000..d5360b2dd --- /dev/null +++ b/.github/workflows/markdown-lint.yml @@ -0,0 +1,27 @@ +name: Markdown Lint + +on: + push: + branches: + - restructure-zh + pull_request: + branches: + - restructure-zh + paths: + - 'docs/**/*.md' + - 'docs/**/*.mdx' + +jobs: + markdownlint: + runs-on: ubuntu-24.04 + timeout-minutes: 5 + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Run markdownlint-cli2 + uses: DavidAnson/markdownlint-cli2-action@v23 + with: + globs: 'docs/**/*.{md,mdx}' + fix: false \ No newline at end of file diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 000000000..dc849157b --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,109 @@ +# .markdownlint-cli2.yaml +# RuyiSDK 文档 markdownlint-cli2 配置 + +# 扫描范围 +globs: + - "docs/**/*.md" + - "docs/**/*.mdx" + +# 忽略目录 +ignores: + - "node_modules/" + - "build/" + - ".docusaurus/" + - "versioned_docs/" + - "versioned_sidebars/" + +# 显示扫描的文件列表 +showFound: true + +# 禁用进度显示（CI 环境下可设为 true） +noProgress: false + +# 规则配置 +config: + # ---- 基础规则 ---- + # 启用所有默认规则 + default: true + + # ---- 规则覆盖（与规范对齐） ---- + # MD004/ul-style：无序列表统一使用短横 + MD004: + style: "dash" + + # MD013/line-length：关闭行长度限制（文档链接常超长） + MD013: false + + # MD033/no-inline-html：允许内联 HTML（Docusaurus 需要
、 等标签） + MD033: false + + # MD034/no-bare-urls：允许裸 URL（部分场景需要） + MD034: false + + # MD041/first-line-heading：关闭"首行为一级标题"要求（有 Front Matter） + MD041: false + + # MD024/no-duplicate-heading：允许不同章节有相同标题 + MD024: + siblings_only: true + + # MD046/code-block-style：强制围栏式代码块（规范 5.1.1） + MD046: + style: "fenced" + + # MD048/code-fence-style：强制使用反引号代码围栏 + MD048: + style: "backtick" + + # MD049/emphasis-style：强调符号统一为星号 + MD049: + style: "asterisk" + + # MD050/strong-style：粗体符号统一为星号 + MD050: + style: "asterisk" + + # MD007/ul-indent：无序列表缩进 2 空格 + MD007: + indent: 2 + + # MD012/no-multiple-blanks：最大连续空行数 2 + MD012: + maximum: 2 + + # MD055/table-pipe-style：表格管道符首尾都有（规范 5.2.2） + MD055: + style: "leading_and_trailing" + + # MD060/table-column-style：表格 compact 风格（规范 5.2.1） + # 单元格内容与管道符之间恰好一个空格 + MD060: + style: "compact" + #aligned_delimiter: true + + # MD022/blanks-around-headings：标题前后必须有空行 + MD022: + lines_above: 1 + lines_below: 1 + + # MD031/blanks-around-fences：代码块前后必须有空行 + MD031: + list_items: true + + # MD032/blanks-around-lists：列表前后必须有空行 + MD032: true + + # MD037/no-space-in-emphasis：强调符号内不允许空格 + MD037: true + + # MD039/no-space-in-links：链接文本内不允许空格 + MD039: true + + # MD045/no-alt-text：图片必须有 alt 文本（规范 5.3.2） + MD045: true + + # MD051/link-fragments：锚点链接必须有效 + MD051: true + + # MD053/link-image-reference-definitions：禁止引用未使用的链接/图片定义 + MD053: false \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..fa965ce0f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,102 @@ +# Contributing to RuyiSDK + +Thank you for your interest in contributing to RuyiSDK! This document provides guidelines and explains the requirements for contributions to this project. + +Read in other languages: + +- [中文](./CONTRIBUTING.zh.md) + +## Code of Conduct + +Please be respectful and considerate of others when contributing to RuyiSDK. We aim to foster an open and welcoming environment for all contributors. + +Please follow [the RuyiSDK Code of Conduct](https://ruyisdk.org/en/code_of_conduct). + +## Developer's Certificate of Origin (DCO) + +We require that all contributions to RuyiSDK are covered under the [Developer's Certificate of Origin (DCO)](https://developercertificate.org/). The DCO is a lightweight way for contributors to certify that they wrote or otherwise have the right to submit the code they are contributing. + +### What is the DCO? + +The DCO is a declaration that you make when you sign-off a commit, simple +enough that the original text is fully reproduced below. + +```plaintext +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +### How to Sign-Off Commits + +You need to add a `Signed-off-by` line to each commit message, which certifies that you agree with the DCO: + +```plaintext +Signed-off-by: Your Name +``` + +You can add this automatically by using the `-s` or `--signoff` flag when committing: + +```bash +git commit -s -m "Your commit message" +``` + +Make sure that the name and email in the signature matches your Git configuration. You can set your Git name and email with: + +```bash +git config --global user.name "Your Name" +git config --global user.email "your.email@example.com" +``` + +### DCO enforcement in CI + +All pull requests go through an automated DCO check in our continuous integration (CI) pipeline. This check verifies that all commits in your pull request have a proper DCO sign-off. If any commits are missing the sign-off, the CI check will fail, and your pull request cannot be merged until the issue is fixed. + +## Pull Request Process + +1. Fork the repository and create your branch from the appropriate branch as described in the [README](./README.md). +2. Make your changes. Please ensure all documentation contributions follow these guidelines: + - [《RuyiSDK Documentation Style Guide》](./DOCUMENTATION_STYLEGUIDE.zh.md): Defines "how to write documentation". + - [《RuyiSDK Documentation Linting Guide》](./DOCUMENTATION_LINTING.zh.md): Defines "how to automate checks". +3. Add tests if applicable. It is recommended to complete a local preview and build verification to ensure there are no broken links or other errors. +4. Ensure your commits are signed-off with the DCO. +5. Submit a pull request to the main repository. **Please note that all commits in the PR must include a valid DCO signature**, otherwise the CI gate will block the merge. + +## Reporting Issues + +If you find a bug or have a feature request, please create an issue in [the issue tracker](https://github.com/ruyisdk/docs/issues). + +## License + +By contributing to RuyiSDK, you agree that your contributions will be licensed under the [Apache 2.0 License](./LICENSE). diff --git a/CONTRIBUTING.zh.md b/CONTRIBUTING.zh.md new file mode 100644 index 000000000..ea2074334 --- /dev/null +++ b/CONTRIBUTING.zh.md @@ -0,0 +1,101 @@ +# 为 RuyiSDK 做贡献 + +感谢您有兴趣为 RuyiSDK 做贡献！本文档提供了贡献指南，并解释了为本项目做贡献的要求。 + +阅读本文的其它语言版本： + +- [English](./CONTRIBUTING.md) + +## 行为准则 + +在为 RuyiSDK 做贡献时，请尊重并考虑他人。我们旨在为所有贡献者营造一个开放和友好的环境。 + +请您遵守[《RuyiSDK 社区行为准则》](https://ruyisdk.org/en/code_of_conduct)。 + +## 开发者原创声明（DCO） + +我们要求 RuyiSDK 的所有贡献都包含[开发者原创声明（DCO）](https://developercertificate.org/)。DCO 是一种轻量级方式，使贡献者可以证明他们编写或有权提交所贡献的代码。 + +### 什么是 DCO？ + +DCO 是您通过签署（sign-off）提交的方式而作出的声明。其全文非常简短，转载如下： + +```plaintext +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. +``` + +### 如何签署提交 + +您需要在每个提交的说明中添加一行 `Signed-off-by`，证明您同意 DCO： + +```plaintext +Signed-off-by: 您的姓名 +``` + +您可以通过在提交时使用 `-s` 或 `--signoff` 参数自动添加此行： + +```bash +git commit -s -m "您的提交说明" +``` + +确保签名中的姓名和电子邮件与您的 Git 配置匹配。您可以使用以下命令设置您的 Git 姓名和电子邮件： + +```bash +git config --global user.name "您的姓名" +git config --global user.email "your.email@example.com" +``` + +### CI 中的 DCO 验证 + +所有拉取请求（PR）都会在我们的持续集成 (CI) 流程中接受自动化 DCO 检查。此检查会验证您的拉取请求中的所有提交是否都有适当的 DCO 签名。如果任何提交缺少签名，CI 检查将失败，在解决问题之前，您的拉取请求将无法被合并。 + +## 拉取请求流程 + +1. 参考 [README](./README.md) 中的分支介绍，选择合适的分支派生仓库并创建您的分支。 +2. 进行更改。文档内容贡献请务必遵循以下规范： + - [《RuyiSDK 文档写作规范》](./DOCUMENTATION_STYLEGUIDE.zh.md)：定义"文档应该怎么写"。 + - [《RuyiSDK 文档规范检查方案》](./DOCUMENTATION_LINTING.zh.md)：定义"如何自动化检查"。 +3. 必要时添加测试。建议在本地完成预览与构建验证，确保无死链等错误。 +4. 确保您的提交已包含 DCO 签名。 +5. 向主仓库提交拉取请求。**请注意，PR 中的所有提交均需包含有效的 DCO 签名**，否则 CI 门禁将予以拦截。 + +## 报告问题 + +如果您发现错误或有功能请求，请在[工单系统](https://github.com/ruyisdk/docs/issues)中创建问题。 + +## 许可证 + +您同意您对 RuyiSDK 的贡献将遵循 [Apache 2.0 许可证](./LICENSE)。 diff --git a/DOCUMENTATION_LINTING.zh.md b/DOCUMENTATION_LINTING.zh.md new file mode 100644 index 000000000..55900dc38 --- /dev/null +++ b/DOCUMENTATION_LINTING.zh.md @@ -0,0 +1,246 @@ +# RuyiSDK 文档规范检查方案 + +- **版本：** v1.0 +- **适用项目：** RuyiSDK 文档（docs 仓库） +- **目标读者：** 开发者、PR Reviewer + +## 目录 + +1. [概述](#1-概述) +2. [本地开发环境配置](#2-本地开发环境配置) +3. [配置文件详解](#3-配置文件详解) +4. [本地使用方式](#4-本地使用方式) +5. [完整工作流总结](#5-完整工作流总结) +6. [PR CI 门禁](#6-pr-ci-门禁) +7. [常见问题与故障排查](#8-常见问题与故障排查) +8. [配套文件清单](#9-配套文件清单) + +## 1. 概述 + +本方案基于 `markdownlint-cli2` 工具链，为 RuyiSDK 文档提供从本地开发到 PR 合并的全流程质量保障。 + +### 1.1 整体架构 + +| 层次 | 工具 | 触发时机 | 目标 | +| :----------------- | :-------------------------------------------- | :------------- | :------------------- | +| **本地检查** | `markdownlint-cli2`（命令行/IDE 插件） | 编写文档时 | 即时发现格式问题 | +| **本地修复** | `markdownlint-cli2 --fix` | 提交前 | 自动修复可修复的问题 | +| **CI 门禁** | `markdownlint-cli2-action` (GitHub Actions) | PR 创建/更新时 | 阻断不合规 PR 合并 | + +### 1.2 与写作规范的对应关系 + +本方案是 [《RuyiSDK 文档写作规范》](./DOCUMENTATION_STYLEGUIDE.zh.md) 的技术落地。规范中定义的每一项格式要求，均在本方案中配置为对应的 lint 规则。贡献者应首先遵循写作规范，本方案提供自动化的检查和辅助。 + +## 2. 本地开发环境配置 + +### 2.1 安装 markdownlint-cli2 + +**全局安装（推荐）：** + +```bash +npm install -g markdownlint-cli2 +``` + +**项目本地安装（备选）：** + +```bash +npm install --save-dev markdownlint-cli2 +``` + +### 2.2 VS Code 集成（推荐） + +1. 安装扩展：`DavidAnson.vscode-markdownlint` +2. 安装后即可在编辑器中实时看到 lint 警告（波浪线标记），无需额外配置。 + +### 2.3 JetBrains IDE 集成（备选） + +1. 安装全局 `markdownlint-cli2`（见 2.1） +2. 配置 External Tool： + - Name: `MarkdownLint` + - Program: `markdownlint-cli2` + - Arguments: `--fix $FilePath$` +3. 可通过 Tools → External Tools 菜单运行，或配置快捷键触发。 + +### 2.4 配置 npm scripts + +在 `package.json` 中添加以下脚本： + +```json +{ + "scripts": { + "lint:md": "markdownlint-cli2 \"docs/**/*.{md,mdx}\"", + "lint:md:fix": "markdownlint-cli2 --fix \"docs/**/*.{md,mdx}\"" + } +} +``` + +使用方式： + +```bash +npm run lint:md # 检查 +npm run lint:md:fix # 检查并自动修复 +``` + +## 3. 配置文件详解 + +### 3.1 `.markdownlint-cli2.yaml` + +在项目根目录创建 `.markdownlint-cli2.yaml` 配置文件，用于控制 lint 规则和行为。 + +完整配置文件请直接查看仓库源文件：[`.markdownlint-cli2.yaml`](./.markdownlint-cli2.yaml) + +> **说明**： +> +> - 配置文件中包含详细的注释说明，每条规则均标注了对应的规范章节。查看源文件即可了解规则用途和配置意图。 +> - 当配置发生变更时，变更理由应在以下至少一处体现：配置文件注释、commit message、PR 描述。这有助于后续维护者理解变更背景，形成可追溯的决策记录。 +> - 建议参考此配置模板，自行调整后维护到仓库中。 + +### 3.2 规则裁剪原则 + +以下规则被关闭的原因： + +| 规则 | 关闭原因 | +| :---------------------- | :----------------------------------------------- | +| `MD013`（行长度） | 文档链接和代码示例常超长，强行限制不现实 | +| `MD033`（内联 HTML） | Docusaurus 需要 `
`、`` 等组件 | +| `MD034`（裸 URL） | 部分场景需要直接展示 URL | +| `MD041`（首行标题） | 文档以 Front Matter 开头，而非一级标题 | +| `MD053`（未使用引用） | 链接定义可能跨文件引用，无法准确判断 | + +`MD060` 的 `aligned_delimiter` 选项禁用原因： + +> 表格分隔行（`---`）与表头行管道符对齐检查虽然有利于源码可读性，但手动修复时需要对整张表格的每行进行管道符位置调整，操作繁琐且容易出错。因此仅在规范中保留"建议对齐"的文字说明，不做自动化检查。 + +## 4. 本地使用方式 + +### 4.1 检查所有文档 + +```bash +# 全局安装方式 +markdownlint-cli2 "docs/**/*.{md,mdx}" + +# 项目本地安装方式 +npx markdownlint-cli2 "docs/**/*.{md,mdx}" +``` + +### 4.2 检查并自动修复 + +```bash +markdownlint-cli2 --fix "docs/**/*.{md,mdx}" +``` + +**`--fix` 可修复的常见问题：** + +| 问题类型 | 说明 | +| :------------- | :----------------------- | +| 标题前后空行 | 自动为标题前后补充空行 | +| 代码块前后空行 | 自动为代码块前后补充空行 | +| 列表缩进 | 统一为 2 空格缩进 | +| 列表符号 | 统一为 `-` | +| 行尾空格 | 删除行尾多余空格 | +| 文件末尾换行 | 补充文件末尾换行 | + +### 4.3 检查单个文件 + +```bash +markdownlint-cli2 "docs/intro/quick-start.md" +markdownlint-cli2 --fix "docs/intro/quick-start.md" +``` + +### 4.4 建议提交前执行 + +```bash +# 1. 自动修复可修复的问题 +markdownlint-cli2 --fix "docs/**/*.{md,mdx}" + +# 2. 检查是否还有残留问题 +markdownlint-cli2 "docs/**/*.{md,mdx}" + +# 3. 如有残留问题，手动修复后重新检查 +# 4. 全部通过后提交 +``` + +## 5. 完整工作流总结 + +建议文档贡献者按照以下工作流进行本地检查和格式验证： + +```text +┌─────────────────────────────────────────────────────────────────────────┐ +│ 文档贡献者工作流 │ +├─────────────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ +│ │ 编写/修改文档 │───▶│ IDE 实时提示 │───▶│ 本地检查 │ │ +│ │ │ │ (波浪线警告) │ │ npm run lint:md │ │ +│ └──────────────┘ └──────────────┘ └──────┬───────────┘ │ +│ │ │ +│ ▼ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │ +│ │ PR 自动检查 │◀───│ 提交 PR │◀───│ 自动修复 │ │ +│ │ (CI 门禁) │ │ │ │ npm run lint:md:fix │ │ +│ └──────┬───────┘ └──────────────┘ └───────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌───────────────┐ │ +│ │ 检查通过 ✅ │ │ +│ │ PR 可合并 │ │ +│ └───────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────┘ +``` + +**关键节点说明：** + +| 节点 | 执行方式 | 说明 | +| :--------------------- | :---------------------- | :----------------------- | +| **IDE 实时提示** | VS Code 扩展自动完成 | 编写时即时发现格式问题 | +| **本地检查** | `npm run lint:md` | 提交前完整检查所有文档 | +| **自动修复** | `npm run lint:md:fix` | 自动修复可修复的格式问题 | +| **PR 自动检查** | CI 门禁自动触发 | 确保合并前所有格式合规 | + +## 6. PR CI 门禁 + +### 6.1 GitHub Actions 工作流 + +CI 门禁通过 GitHub Actions 实现，工作流配置文件位于仓库的 `.github/workflows/markdown-lint.yml`。 + +- 完整配置请查看源文件：[`.github/workflows/markdown-lint.yml`](./.github/workflows/markdown-lint.yml) + +> **说明**：当前 CI 门禁仅在 `restructure-zh` 分支上生效，其他分支暂不启用。如需在其他分支启用，请参考源文件中的分支配置。 + +### 6.2 门禁效果 + +| 状态 | 结果 | +| :----------------- | :--------------------------------------- | +| **检查通过** | ✅ PR 可正常合并 | +| **检查失败** | ❌ PR 被标记为 "Check Failure"，阻止合并 | + +**检查失败时的处理流程：** + +1. 查看 CI 日志，定位具体文件及问题行号 +2. 本地执行 `markdownlint-cli2 --fix "docs/路径/文件.md"` 自动修复 +3. 如无法自动修复，根据错误提示手动修改 +4. 本地再次检查通过后 `git push` 更新 PR + +## 7. 常见问题与故障排查 + +| 问题 | 原因 | 解决方法 | +| :--------------------------------------- | :--------------------------- | :-------------------------------------------------------- | +| `markdownlint-cli2: command not found` | 未全局安装 | 全局安装：`npm install -g markdownlint-cli2` | +| VS Code 扩展不生效 | 未安装扩展或未重启 VS Code | 安装 `DavidAnson.vscode-markdownlint` 并重启 | +| `--fix` 无法修复的问题 | 问题涉及内容语义判断 | 根据错误提示手动修改 | +| CI 检查失败但本地检查通过 | 配置文件未同步 | 确保 `.markdownlint-cli2.yaml` 已提交 | +| 中文表格检查误报 | `MD060` 对中文宽度判断不准 | 已关闭 `aligned_delimiter`，仅保留 `style: "compact"` | +| CI 超时 | 文档数量过多 | 联系仓库维护者切换到增量检查模式 | + +## 8. 配套文件清单 + +| 文件 | 位置 | 用途 | +| :-------------------------------------- | :--------------------- | :------------ | +| `.markdownlint-cli2.yaml` | 项目根目录 | Lint 规则配置 | +| `.github/workflows/markdown-lint.yml` | `.github/workflows/` | CI 门禁工作流 | +| `package.json`（scripts 部分） | 项目根目录 | 本地命令封装 | + +--- + +本方案随项目演进持续更新。修订请提交 PR 并在描述中说明变更动机。 diff --git a/DOCUMENTATION_STYLEGUIDE.zh.md b/DOCUMENTATION_STYLEGUIDE.zh.md new file mode 100644 index 000000000..cd239b7e5 --- /dev/null +++ b/DOCUMENTATION_STYLEGUIDE.zh.md @@ -0,0 +1,629 @@ +# RuyiSDK 文档写作规范 + +**版本：** v1.0 +**适用项目：** RuyiSDK 文档（docs 仓库） +**目标读者：** 所有文档贡献者 + +## 目录 + +1. [总体原则](#1-总体原则) +2. [文件与目录规范](#2-文件与目录规范) +3. [Markdown 通用语法规范](#3-markdown-通用语法规范) +4. [中文文案排版规范](#4-中文文案排版规范) +5. [核心内容元素规范](#5-核心内容元素规范) +6. [Docusaurus 专属规范](#6-docusaurus-专属规范) +7. [侧边栏管理](#7-侧边栏管理) +8. [提交前自查清单](#8-提交前自查清单) +9. [常见问题与避坑](#9-常见问题与避坑) +10. [参考文档](#10-参考文档) + +## 1. 总体原则 + +1. **文档即代码**：文档与代码同源，遵循相同的版本控制、审核与更新流程。 +2. **用户至上**：所有规范服务于提升用户的阅读体验和信息获取效率。 +3. **可维护性优先**：规范应确保文档长期可维护，新人能快速上手，老人能高效查阅。 +4. **内容优先，格式自动化**：书写时专注内容，排版问题后续通过工具辅助解决。关于自动化检查工具的使用方式，请参见 [《RuyiSDK 文档规范检查方案》](./DOCUMENTATION_LINTING.zh.md)。 +5. **本地预览**：大量或复杂修改提交前建议在主仓库（ruyisdk-website）执行 `pnpm run build` 验证无死链和构建错误。 + +## 2. 文件与目录规范 + +### 2.1 命名规则 + +- 文件夹和 Markdown 文件名**必须**使用**全小写英文字母**，单词之间用**连字符（`-`）**连接。 + +> **正确示例：** +> +> ```text +> getting-started.md +> api-reference/ +> ``` +> +> **错误示例：** +> +> ```text +> Getting_Started.md +> apiReference/ +> ``` + +- 图片文件名同样遵循此规则，**禁止包含空格**。 + +> **正确示例：** +> +> ```text +> architecture-diagram.png +> ``` +> +> **错误示例：** +> +> ```text +> architecture diagram.png +> ``` + +### 2.2 文档元数据 {#docusaurus-front-matter} + +每个 Markdown/MDX 文件头部**必须**包含 YAML 格式的 Front Matter。以下是字段说明： + +| 字段 | 是否必填 | 说明 | +| -------------------- | -------------- | -------------------------------------------------------------------------------- | +| `title` | **必填** | 页面标题，显示在浏览器 Tab 和页面顶部。应与正文一级标题保持一致。 | +| `sidebar_position` | **推荐** | 控制文档在侧边栏同一目录内的排序（数字越小越靠前）。同一目录内必须唯一。 | +| `description` | **推荐** | 页面摘要，用于 SEO 元描述。建议提供，有助于搜索引擎展示。 | +| `sidebar_label` | 可选 | 侧边栏显示的短名称，缺省时取 `title`。当 `title` 较长时使用。 | +| `id` | 可选 | 文档唯一标识，默认使用文件名（不含扩展名）。**除非有特殊需要，否则不填**。 | +| `slug` | 可选 | 自定义 URL 路径。**除非有特殊需要，否则不填**。 | + +> **示例：** +> +> ```yaml +> --- +> title: RuyiSDK 快速开始 +> sidebar_position: 1 +> description: 学习如何快速安装 RuyiSDK 并运行第一个示例项目。 +> --- +> ``` + +### 2.3 静态资源存放 + +图片存放遵循以下规则： + +- **文档专属图片**：存放在与当前文档同级的 `assets/` 子目录中，使用**相对路径**引用。 +- **站点全局图片**（如 Logo、首页横幅）：存放在主仓库 `/static/img/` 目录下，使用**绝对路径**引用。 +- **禁止**使用硬编码的绝对 URL 路径（如 `https://example.com/img/logo.png`）。 + +## 3. Markdown 通用语法规范 + +### 3.1 标题 + +- 每篇文档**必须**以**一级标题（`#`）**开头，作为文档主标题。**禁止**使用 `#` 以外的其他方式定义文档标题（如使用 `===` 或 `---` 下划线）。 +- 标题层级应递进有序，不得跳跃（例如 `##` 后直接跟 `####`）。 +- 标题前后**必须**保留一个空行。 +- 标题末尾不加标点符号。 + +**自定义锚点 ID（推荐）：** + +为避免自动生成的锚点 ID 不美观或因修改标题导致链接失效，推荐为标题设置自定义锚点 ID： + +- `.md` 文件：使用 `{#id}` 语法 + +> **示例：** +> +> ```markdown +> ### 高级配置 {#advanced-config} +> ``` + +- `.mdx` 文件：使用注释语法 + +> **示例：** +> +> ```markdown +> ### 高级配置 {/* #advanced-config */} +> ``` + +### 3.2 段落与空行 + +- 段落之间**必须**保留一个空行。 +- 列表项之间如果属于不同逻辑块，建议保留空行。 +- 行尾**禁止**有多余空格。 + +### 3.3 列表 + +- 无序列表统一使用 `-` 符号。 +- 有序列表使用 `1.` `2.` `3.`。 +- 同一文档内列表符号保持一致。 +- 列表项内的代码块、引用块需缩进 2 个空格对齐。 + +### 3.4 强调 + +- 使用 `**粗体**` 或 `_斜体_`。避免使用下划线 `_`（在中文语境下易与文字混淆）。 +- 粗体用于关键词或重要概念的首次出现。 +- 斜体用于术语解释或侧注，谨慎使用。 +- **禁止**整段加粗或整段斜体。 + +## 4. 中文文案排版规范 + +本规范参考中文技术文档通用排版准则，旨在提升中文文档的专业性与可读性。 + +### 4.1 空格使用 + +- **必须**在**中文与英文**、**中文与数字**、**数字与单位**之间增加一个半角空格。 + +> **示例：** +> +> ```markdown +> 在 Docusaurus 2 中，有超过 1000 个贡献者。 +> ``` + +- **必须**在**中文与行内代码（`` ` ``）**之间增加一个半角空格。 + +> **示例：** +> +> ```markdown +> 请运行 `pnpm start` 命令启动项目。 +> ``` + +- **例外**： + - 百分比（`90%`）和度数（`30°`）与数字之间**不加**空格。 + - 全角标点符号（如，。！“”）与其它字符之间**不加**空格。 + - 行内代码紧邻标点符号时，代码与标点之间**不加**空格。 + +> **示例：** +> +> ```markdown +> 使用 `pnpm build` 构建项目，构建成功后会输出 "Build completed" 提示，整体打包效率提升约 30%，在 25°C 的室温环境下测试通过。 +> ``` + +### 4.2 标点符号 + +- 中文内容**必须**使用**全角中文标点**（`，` `。` `！“”` `《》`）。 +- **禁止**在中文语境中使用半角英文标点（`,` `.` `!` `""`）。 +- 英文单词或句子内部，保留其原始的**半角标点**。 + +### 4.3 专有名词 + +- 对专有名词使用其**官方正确的大小写**。 + +> **正确示例：** +> +> ```markdown +> React、GitHub、TypeScript、JavaScript +> ``` +> +> **错误示例：** +> +> ```markdown +> react、github、Ts +> ``` + +## 5. 核心内容元素规范 + +### 5.1 代码块 + +#### 5.1.1 基本语法 + +- **必须**采用**围栏式（Fenced）风格**，使用三个反引号（` ``` `）包裹。 +- **必须**在开头的反引号后指定语言标识符，以确保正确的语法高亮。常用语言标识符（如 `bash`、`javascript`、`jsx`、`json`、`yaml` 等）可在编辑器中通过自动补全获取。 + +> **示例：** +> +> ````markdown +> ```javascript +> console.log('Hello World'); +> ``` +> ```` + +- 代码块前后**必须**保留空行。 + +#### 5.1.2 代码高亮 + +可使用 Prism 的"魔法注释"进行行高亮： + +> **示例：** +> +> ````markdown +> ```jsx +> // highlight-next-line +> const app = new App(); +> +> // highlight-start +> const config = { +> port: 3000, +> }; +> // highlight-end +> ``` +> ```` + +#### 5.1.3 本项目自定义扩展：`input` 属性 + +本项目支持在语言标识后添加 `input` 属性，用于命令行交互场景： + +- **属性说明**： + - `input="1"`：表示第 1 行是用户输入，渲染时行末显示【Copy】按钮。 + - 支持指定多行：`input="2,4,6"`、`input="1-10"` 或 `input="1,2,5-7"`。 + - 复制时自动去除行首的 `$` 或 `#` 前缀。 + +> **使用示例：** +> +> ````markdown +> import CodeBlock from '@site/src/components/Docs/CodeBlock'; +> +> ```bash input="1" +> $ ruyi --version +> ``` +> ```` + +#### 5.1.4 行内代码 + +- 用于提及文件名、函数名、变量、路径和 **HTML 标签**。 +- 书写 HTML 标签时，**必须**用反引号包裹（例如 `` `

` ``），以防被 MDX 引擎误解析为 React 组件。 + +> **示例：** +> +> ```markdown +> 请编辑 `docusaurus.config.js` 文件，使用 `` 组件切换不同操作系统。 +> ``` + +### 5.2 表格 + +#### 5.2.1 风格要求 + +- 表格**必须**采用 **`compact` 风格**，即单元格内容与管道符（`|`）之间**恰好保留一个空格**。 +- 表头分隔行（`---`）的管道符建议与表头行对齐，提升源码可读性。 + +> **示例：** +> +> ```markdown +> | 参数名 | 类型 | 说明 | +> | ------- | ------ | -------- | +> | name | string | 用户名称 | +> | age | number | 用户年龄 | +> ``` + +#### 5.2.2 管道符规范 + +- 表格每一行的**开头和结尾**都必须有管道符。 + +> **正确示例：** +> +> ```markdown +> | Cell 1 | Cell 2 | +> ``` + +#### 5.2.3 表格使用建议 + +表格**仅用于展示简短的结构化数据**（如参数列表、版本兼容性、配置项说明）。 + +当表格内容过于复杂时，建议考虑以下替代方案： + +> **替代方案示例：** +> +> ```markdown +> **配置参数说明：** +> +> - **`host`** (string)：服务器地址，必填。 +> - **`port`** (number)：服务器端口，可选，默认为 8080。 +> - **`timeout`** (number)：超时时间，单位毫秒，默认 30000。 +> ``` + +#### 5.2.4 表格内元素 + +- 表格单元格中提及代码或命令时，**必须**使用反引号包裹（例如 `` `git status` ``）。 +- 如需在单元格内换行，可使用 `
` 标签。 +- 表格前后**必须**保留空行。 + +### 5.3 图片 + +#### 5.3.1 格式要求 + +- **优先使用矢量图（SVG）或 WebP 格式**，以提升加载速度和显示效果。 +- 提交前应对大图进行压缩，避免文件体积过大影响页面加载速度。 + +#### 5.3.2 Alt 文本（强制） + +- 图片**必须**包含描述性的 `alt` 文本，有助于无障碍访问和 SEO。 + +> **正确示例：** +> +> ```markdown +> ![系统架构图，展示前端、后端和数据库三层结构] +> ``` +> +> **错误示例：** +> +> ```markdown +> ![图片] +> ![]() +> ``` + +#### 5.3.3 存放与引用 + +- **文档专属图片**：存放在与文档同级的 `assets/` 目录下，使用**相对路径**引用。 + +> **示例：** +> +> ```markdown +> ![架构图](./assets/architecture-diagram.png) +> ``` + +- **站点全局图片**：存放在主仓库 `/static/img/` 目录下，使用**绝对路径**引用。 + +> **技术说明：** +> +> Docusaurus 构建时会将 `static/` 目录的内容直接复制到输出根目录。因此 `static/img/logo.svg` 在构建后可通过 `/img/logo.svg` 访问。使用绝对路径可确保 Docusaurus 正确解析资源并自动适配 `baseUrl`。 +> +> **正确示例：** +> +> ```markdown +> ![Logo](/img/logo.svg) +> ``` +> +> **错误示例：** +> +> ```markdown +> ![Logo](/static/img/logo.svg) +> ![Logo](./static/img/logo.svg) +> ``` + +- **禁止**使用硬编码的绝对 URL 路径（如 `https://example.com/img/logo.png`）。 + +#### 5.3.4 主题化适配（明暗模式） + +当图片在明暗模式下需要不同显示时，使用 `ThemedImage` 组件（适用于 `.mdx` 文件）： + +> **示例：** +> +> ```jsx +> import ThemedImage from '@theme/ThemedImage'; +> import useBaseUrl from '@docusaurus/useBaseUrl'; +> +> alt="主题化图片说明" +> sources={{ +> light: useBaseUrl('/img/logo-light.svg'), +> dark: useBaseUrl('/img/logo-dark.svg'), +> }} +> /> +> ``` + +### 5.4 链接与交叉引用 + +#### 5.4.1 内部链接（同插件内）{#relative-paths} + +引用项目内其他 Markdown/MDX 文件时，**必须**使用**相对路径**，并**包含 `.md` 或 `.mdx` 扩展名**。 + +| 场景 | 写法 | 示例 | +| :----------------- | :------------------- | :------------------------------------------------------------- | +| **同级目录** | `文件名.md` | `[产品详情](product.md)` | +| **子目录** | `子目录/文件名.md` | `[API 参考](api/index.md)` 或 `[API 参考](./api/index.md)` | +| **上级目录** | `../文件名.md` | `[快速入门](../start/qemu.md)` | + +> **正确示例：** +> +> ```markdown +> [产品详情](product.md) +> [快速入门](../start/qemu.md) +> ``` +> +> **错误示例：** +> +> ```markdown +> [产品详情](../intro/product.md) +> [产品详情](/docs/intro/product) +> [产品详情](./product) +> ``` + +**禁止的写法：** + +- ❌ 绝对路径：`/docs/intro/product`（破坏版本化与 i18n） +- ❌ 省略扩展名：`./product`（GitHub 中不可点击） +- ❌ 引用不存在的文档（Docusaurus 构建会报 `broken links` 错误中断） + +**目标文档未创建时的处理：** + +使用纯文本占位，不写链接。 + +> **示例：** +> +> ```markdown +> - **我想快速体验** → 请阅读 快速入门（待补充） +> ``` + +#### 5.4.2 外部链接 + +使用完整的 `https://...` URL。 + +#### 5.4.3 章节锚点引用 + +- **同一文件内**： + +> **示例：** +> +> ```markdown +> [跳转到安装步骤](#installation-steps) +> ``` + +- **跨文件章节引用**（保留文件扩展名）： + +> **示例：** +> +> ```markdown +> [查看详细配置](./config.md#advanced-config) +> ``` + +- **推荐使用自定义锚点 ID**（见 [3.1 节](#31-标题)），防止因标题修改导致链接失效。 + +#### 5.4.4 跨插件引用 + +当引用**不在同一个插件**中的文档时（如从博客文章引用文档），**必须使用 URL 路径**。 + +> **示例：** +> +> ```markdown +> [文档](/docs/intro) +> ``` + +### 5.5 提示框（Admonitions）{#docusaurus-admonitions} + +Docusaurus 提供内置提示框语法，用于突出重要信息。**推荐使用此语法，禁止自绘样式**。 + +> **示例：** +> +> ```markdown +> :::note +> 这是一条常规注释或补充信息。 +> ::: +> +> :::tip +> 这是一个有用的技巧或最佳实践。 +> ::: +> +> :::info +> 这是一条补充信息。 +> ::: +> +> :::warning +> 这是一个需要注意的警告信息。 +> ::: +> +> :::danger +> 这是一个严重的风险或错误提醒。 +> ::: +> ``` + +**注意**：`:::` 起止指令前后**必须**保留空行。 + +## 6. Docusaurus 专属规范 + +### 6.1 Front Matter + +参见 [2.2 节](#docusaurus-front-matter)。 + +### 6.2 相对路径写法 + +参见 [5.4.1 节](#relative-paths)。 + +### 6.3 `.md` 与 `.mdx` 差异 + +| 场景 | `.md` 文件 | `.mdx` 文件 | +| --------------- | --------------------- | --------------------------- | +| 自定义锚点 ID | `### 标题 {#my-id}` | `### 标题 {/* #my-id */}` | +| 使用 React 组件 | ❌ 不支持 | ✅ 支持 | +| `import` 语句 | ❌ 不支持 | ✅ 支持 | + +**推荐**： + +- 纯文档内容使用 `.md`。 +- 需要交互组件或复杂布局时使用 `.mdx`。 + +### 6.4 提示框（Admonitions） + +参见 [5.5 节](#docusaurus-admonitions)。 + +## 7. 侧边栏管理 + +本项目采用 **`autogenerated` + `_category_.json` 混合方案**。 + +### 7.1 方案说明 + +- 目录结构自动生成侧边栏。 +- 目录间的排列顺序由目录下的 `_category_.json` 集中控制。 +- 目录内单篇文档的顺序由各文件的 `sidebar_position` 控制。 + +### 7.2 目录顺序控制：`_category_.json` + +在每个需要控制顺序的目录下新建 `_category_.json`： + +> **示例：** `docs/intro/_category_.json` +> +> ```json +> { +> "label": "产品介绍", +> "position": 1 +> } +> ``` + +- `label`：目录在侧边栏显示的名称。 +- `position`：决定该目录在父级侧边栏中的排列顺序（数字越小越靠前）。支持小数（如 `1.5`），便于在已有项之间插入新分类。 + +### 7.3 文档顺序控制：`sidebar_position` + +在文档的 Front Matter 中指定 `sidebar_position`： + +> **示例：** +> +> ```yaml +> --- +> title: RuyiSDK 快速开始 +> sidebar_position: 1 +> --- +> ``` + +- 同一目录内 `sidebar_position` 必须唯一。 +- 数字越小，文档在侧边栏中越靠前。 + +### 7.4 新增文档流程 + +1. 在目标目录下新建 `.md` 或 `.mdx` 文件。 +2. 添加规范的 Front Matter（至少包含 `title` 和 `sidebar_position`）。 +3. 如该目录尚无 `_category_.json`，新建并设置 `label` 与 `position`。 +4. 本地 `pnpm start` 验证侧边栏显示正确。 +5. 提交 PR。 + +## 8. 提交前自查清单 + +在提交 PR 前，请逐项确认： + +**文件与目录：** + +- [ ] 文件名是否为小写+连字符？ +- [ ] Front Matter 是否包含 `title` 和 `sidebar_position`？ +- [ ] 是否提供了 `description`（推荐）？ + +**内容与格式：** + +- [ ] 标题层级是否清晰有序（无跳级）？ +- [ ] 代码块是否指定了语言标识符？ +- [ ] 代码块是否使用了围栏式风格（`` ``` ``）？ +- [ ] 表格是否符合 `compact` 风格（管道符间恰好一个空格）？ +- [ ] 表格前后是否有空行？ +- [ ] 图片是否包含描述性 Alt 文本？ +- [ ] 图片是否存放在正确位置（`assets/` 或 `/static/img/`）？ + +**排版与语言：** + +- [ ] 中英文/数字之间是否添加了空格？ +- [ ] 中文内容是否使用了全角标点符号？ +- [ ] 专有名词大小写是否正确？ + +**链接：** + +- [ ] 内部链接是否为相对路径且包含 `.md`/`.mdx` 扩展名？ +- [ ] 是否存在指向未创建文档的死链？ + +**验证：** + +- [ ] 大量或复杂修改已执行 `pnpm run build`，确认无构建错误和死链？ + +> **自动化检查：** 本清单中的格式相关条目（表格风格、代码块、空行等）已纳入自动化检查，可运行 `markdownlint-cli2` 辅助验证。配置方式及使用说明详见 [《RuyiSDK 文档规范检查方案》](./DOCUMENTATION_LINTING.zh.md)。 + +## 9. 常见问题与避坑 + +| 问题 | 原因 | 解决方法 | +| ---------------------------------- | --------------------------------- | ---------------------------------------------------------- | +| Docusaurus 构建报 `broken links` | 链接目标文件不存在或路径错误 | 本地 `pnpm run build` 定位，改用正确相对路径或纯文本占位 | +| 表格在 GitHub 显示错位 | 中英文混排手动对齐不一致 | 使用 compact 风格，后续由格式化工具自动处理 | +| Admonition 渲染异常 | `:::` 前后无空行 | 在 `:::` 起止指令前后保留空行 | +| 图片在 GitHub 可见但构建后不可见 | 使用了相对路径指向 `static/` 外 | 全局图片用 `/img/xxx` 绝对路径指向 `static/img/` | +| 版本化文档链接失效 | 使用了 `/docs/...` 绝对路径 | 改用相对路径，版本化时会自动指向同版本 | +| 自定义锚点 ID 在 MDX 中报错 | 使用了 `{#id}` 旧语法 | MDX 文件使用 `{/* #id */}` 注释语法 | + +## 10. 参考文档 + +遇到本规范未涵盖的场景，请查阅以下官方文档： + +- [Docusaurus Markdown 特性](https://docusaurus.io/zh-CN/docs/markdown-features) +- [Docusaurus Admonitions](https://docusaurus.io/docs/markdown-features/admonitions) +- [Docusaurus 侧边栏（autogenerated）](https://docusaurus.io/zh-CN/docs/sidebar/autogenerated) +- [Docusaurus Front Matter 字段](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-frontmatter) +- [GitHub Markdown 基础语法](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) + +本规范随项目演进持续更新。修订请提交 PR 并在描述中说明变更动机。 diff --git a/README.md b/README.md new file mode 100644 index 000000000..f62beafc4 --- /dev/null +++ b/README.md @@ -0,0 +1,27 @@ +# RuyiSDK docs + +文档包括RuyiSDK的总体介绍和各个组成部分的介绍和使用方法。 + +## 关于docs仓库 + +仓库分支介绍： + +- `main` 分支：用于提交开发中文档。 +- `zh` 分支：该分支接收相对成熟的文档，文档内容会在 [RuyiSDK 官网的文档板块](https://ruyisdk.org/docs)展示。 +- `gh-pages` 分支：用于存放构建后的静态页面。 +- `restructure-zh` 分支：用于临时存放针对`zh` 分支进行重构的文档，由于涉及目录和文件名的重定义和规范化，计划重构完成后再合入`zh` 分支。 + +### 贡献文档 + +欢迎大家一起参与RuyiSDK文档贡献。贡献方法： + +1. fork 本仓库； +2. 参考分支定位切换到合适的分支； +3. 贡献文档，书写前请阅读 [《RuyiSDK 文档写作规范》](./DOCUMENTATION_STYLEGUIDE.zh.md)； +4. 提交修改并创建 pull request 将文档贡献提交到 docs 仓库，等待仓库管理员审核合入。 + +请阅读[《贡献者指南》](./CONTRIBUTING.zh.md) ([English version](./CONTRIBUTING.md)) 以获取完整的贡献流程、DCO 签名要求等信息。 + +## 预览 + +本仓库作为 `ruyisdk-website` 的 submodule，由主仓库统一构建。如需本地预览，参考[ruyisdk-website/README.md](https://github.com/ruyisdk/ruyisdk-website/tree/main#running-locally)。