# Contributing to FluxDown

感谢你有意为 FluxDown 做贡献！/ Thank you for your interest in contributing to FluxDown!

## 开发流程 / Development Workflow

1. Fork 本仓库并从 `main` 创建分支，PR 也提交到 `main`（`main` 是开发分支；`stable` 是稳定分支，只由维护者从 `main` 合并前进，请勿直接对其提 PR）。
   Fork the repository and branch off `main`, then target `main` with your PR (`main` is the development branch; `stable` is the stable branch that maintainers advance from `main` — do not open PRs against it).
2. 遵循仓库根目录 `AGENTS.md` 中的代码风格与规范（Rust: `cargo fmt --check && cargo clippy -- -D warnings`；Dart: `flutter analyze`）。
   Follow the code style and conventions in `AGENTS.md` at the repository root (Rust: `cargo fmt --check && cargo clippy -- -D warnings`; Dart: `flutter analyze`).
3. 提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/)（Release Notes 由 git-cliff 自动生成）。
   Write commit messages following [Conventional Commits](https://www.conventionalcommits.org/) — release notes are generated by git-cliff.
4. 提交 PR 前确保相关 crate 的测试通过（例如 `cargo test -p fluxdown_engine`）。
   Make sure the tests for the affected crates pass before opening a PR (e.g. `cargo test -p fluxdown_engine`).

## 反馈问题 / Reporting Issues

请通过 [GitHub Issues](https://github.com/zerx-lab/FluxDown/issues) 或官网 [反馈页面](https://fluxdown.zerx.dev/feedback) 提交问题。
Please report problems via [GitHub Issues](https://github.com/zerx-lab/FluxDown/issues) or the [feedback page](https://fluxdown.zerx.dev/feedback) on the official site.

## 文档贡献 / Documentation Contributions

FluxDown 官网文档（<https://fluxdown.zerx.dev/docs/>）与源码同仓库维护，欢迎通过 Pull Request 贡献或翻译。
The FluxDown documentation site (<https://fluxdown.zerx.dev/docs/>) is maintained in this repository — contributions and translations via Pull Request are welcome.

### 快速编辑 / Quick Edit

每篇文档页面都有"编辑此页"链接，点击后直接跳转到 GitHub 网页编辑器（指向 `main` 分支，无写权限时会自动引导 Fork），改完直接提交 PR 即可，不需要本地克隆仓库。
Every documentation page has an "Edit this page" link that opens the GitHub web editor on the `main` branch (auto-forks if you lack write access) — edit and submit a PR, no local clone required.

### 目录结构 / Directory Layout

文档源文件位于 `website/src/content/docs/{en,zh}/`，按语言分目录，子目录与文件名一一对应：
Documentation source files live under `website/src/content/docs/{en,zh}/`, one directory per language, with matching subdirectory/filename structure across languages:

```text
website/src/content/docs/
├── en/
│   ├── getting-started/installation.md
│   └── ...
└── zh/
    ├── getting-started/installation.md
    └── ...
```

### Frontmatter 字段 / Frontmatter Fields

每篇文档文件头部为 YAML frontmatter：
Each file starts with a YAML frontmatter block:

| 字段 / Field | 必填 / Required | 说明 / Description |
| --- | --- | --- |
| `title` | 是 / Yes | 页面标题 / Page title |
| `description` | 否 / No | 用于 SEO meta description / Used for the SEO meta description |
| `section` | 是 / Yes | 所属分区（`getting-started`\|`protocols`\|`browser-extension`\|`headless-server`\|`api`\|`contributing`）/ One of the fixed section enum values |
| `order` | 否 / No | 侧边栏排序，数字越小越靠前，默认 999 / Sidebar ordering, lower sorts first, defaults to 999 |
| `sourceHash` | 否，仅 zh 译文 / No, zh translations only | 对应 en 原文内容的哈希，用于检测译文是否过期，详见下文"翻译流程" / Hash of the corresponding en source content, used to detect stale translations — see "Translation Workflow" below |

### 翻译流程 / Translation Workflow

1. 在 `zh/` 下创建与 `en/` 对应路径同名的文件（每篇英文页面的"新建翻译"深链会自动引导到正确目录）。
   Create a file under `zh/` at the same relative path as its `en/` counterpart (the "New translation" deep link on each English page opens the correct target directory automatically).
2. 翻译完成后，在 `website/` 目录下运行 `npm run docs:hash <zh 文件相对路径>`，自动写入 frontmatter 中的 `sourceHash` 字段。
   After translating, run `npm run docs:hash <path to the zh file>` from the `website/` directory to write the `sourceHash` frontmatter field automatically.
3. 无法本地运行脚本也没关系（例如仅使用网页编辑器）：在 PR 描述中说明留空，并勾选 "Allow edits from maintainers"，维护者会在合并前后补上。
   Can't run the script locally (e.g. web-editor-only contributions)? That's fine — note it in the PR description and enable "Allow edits from maintainers"; a maintainer will fill it in around merge time.
4. 之后 en 原文更新导致 `sourceHash` 不再匹配时，zh 页面会自动显示"译文可能已过期"提示，但页面仍正常展示，不影响访问。
   When the en source later changes and `sourceHash` no longer matches, the zh page automatically shows a "translation may be outdated" banner — the page still renders normally.

### 审核规则 / Review Rules

- 每个 PR 只改动一篇文档页面，便于审核；夹带的无关改动会被要求拆分。
  Each PR should touch exactly one documentation page to keep review focused; unrelated changes will be asked to be split out.
- 至少 1 位维护者 review 通过后才会合并，**不设自动合并**。
  At least one maintainer review is required before merge — **PRs are never auto-merged**.
- 中英文允许异步更新：zh 译文落后于 en 原文是正常状态（缺失译文会展示英文原文 + 未翻译提示，不会 404）。
  Chinese and English content may update asynchronously — it's normal for zh translations to lag behind en (a missing translation falls back to the English content with an "untranslated" banner instead of a 404).
- 首次贡献者触发的 Actions 工作流需要维护者手动批准后才会运行。
  Workflow runs triggered by first-time contributors require manual maintainer approval before they run.

提交 PR 时可选择 "docs" 模板（`.github/PULL_REQUEST_TEMPLATE/docs.md`），源码仓库地址：<https://github.com/zerx-lab/FluxDown>。
When opening a PR you can pick the "docs" template (`.github/PULL_REQUEST_TEMPLATE/docs.md`). Source repository: <https://github.com/zerx-lab/FluxDown>.