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（Release Notes 由 git-cliff 自动生成）。 Write commit messages following Conventional Commits — 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 或官网 反馈页面 提交问题。 Please report problems via GitHub Issues or the feedback page 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:

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.