docs: add documentation style guide and linting infrastructure

.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

.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 需要 <details>、<Tabs> 等标签）
+  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

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 <your.email@example.com>
+```
+
+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).

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: 您的姓名 <your.email@example.com>
+```
+
+您可以通过在提交时使用 `-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)。