贡献文档

本文档站是基于 Pylon 官方英文文档 的第三方中文翻译/改编文档站。我们致力于为中文社区提供更易理解的 Pylon 文档。

欢迎各位贡献者帮助我们改进这个文档站！

第0步：前置条件

开始之前，请确认你的环境已经准备好以下工具：

Git

克隆仓库和提交代码都离不开 Git。

你可以用 Git 命令行，也可以用 GitHub Desktop 这类图形界面工具（推荐新手使用）。

GitHub 账号

Fork 仓库和创建 PR 都需要 GitHub 账号。

还没有的话可以免费注册一个。

Node.js 和包管理器

本项目基于现代前端框架构建，需要 Node.js 环境。

在终端里检查一下是否已安装：

node --version
# 应该显示 v18 或更高版本

pnpm --version

yarn --version

npm --version

第1步：Fork 仓库

打开本仓库的 GitHub 页面，点击右上角的 Fork 按钮，创建你自己的副本。

第2步：克隆你的 fork

把 fork 到手上的仓库克隆到本地，才能预览和编辑。

用命令行的话，去你的 fork 页面点绿色的 Code 按钮，复制 HTTPS 地址：

然后运行：

git clone <REPLACE_URL_HERE>

第3步：安装依赖

仓库到手了，接下来安装依赖包。

在项目根目录下执行：

pnpm install

yarn install

npm install

这会安装项目所需的所有依赖包。

第4步：开始修改

现在可以编辑文档了！

文档用 Markdown 编写（.mdx 格式，支持 JSX 组件）。语法不熟的话可以看 Mastering Markdown。

4.1 了解目录结构

文档存放在 content/docs/ 目录下（具体路径可能因项目配置而异）：

content/
└── docs/
    └── documentation/
        ├── contributing/    # 贡献指南
        ├── installation/    # 安装指南
        ├── getting-started/ # 入门教程
        └── ...              # 其他章节

每个章节都有独立的目录，该章节用到的图片放在同目录下的 img/ 文件夹中。

4.2 创建新页面

按以下步骤操作：

1. 进入对应的子目录
2. 新建一个 .mdx 或 .md 文件，取个有意义的名字

命名规则：

• 文件名以 .md 或 .mdx 结尾
• 全部小写
• 用连字符 - 代替空格
• 不用特殊字符
• 示例：installing-addons.mdx、custom-recipes.mdx

然后：

1. 用 Markdown 语法写内容
2. 在文件头部添加 frontmatter（标题、描述等元数据）
3. 保存文件
4. 预览效果（见第5步）

4.3 编辑现有页面

1. 用编辑器打开要改的 .mdx 或 .md 文件
2. 改内容
3. 保存
4. 预览（见第5步）

4.4 添加图片

命名规范

• 全部小写
• 用连字符 - 代替空格
• 取个描述性的名字
• 优先用 PNG 格式
• 示例：github-fork.webp、custom-item-example.webp

存放位置

图片放在 markdown 文件同一级目录下的 img/ 文件夹中。

没有 img/ 文件夹的话先新建一个。

在页面中引用

![图片说明](img/your-image-name.webp)

4.5 翻译/改进现有翻译

如果你发现官方英文文档有更新但中文文档还没同步，或者现有的翻译不够准确/通顺，欢迎：

1. 参考官方英文文档的内容
2. 对应修改中文翻译
3. 确保技术术语翻译一致
4. 必要时添加译者注说明

第5步：预览效果

提交之前建议先在本地预览一下，确认显示正常。

在项目根目录下运行：

pnpm dev

yarn dev

npm run dev

这会启动一个本地开发服务器。浏览器打开终端提示的地址（通常是 http://localhost:3000）就能看到带了你修改的文档站点。

保存文件后页面会自动热更新。

第6步：提交并推送

改好了就可以提交并推送到你的 fork 了。

在项目目录下执行：

git add .
git commit -m "描述你改了什么的提交信息"
git push

第7步：创建 PR

推送到 GitHub 之后，就可以开 PR 提交你的修改了。

1. 打开你在 GitHub 上的 fork 仓库
2. 点 Pull requests 标签页
3. 点绿色的 New pull request 按钮
4. 选择目标分支为 main（或主分支）
5. 填好标题和描述
6. 点 Create pull request

搞定！之后维护者会审查你的改动。没问题的话就会被合并。

第8步：更新 PR

PR 提交之后如果还需要改（比如 reviewer 提了修改意见），操作很简单：

重复第4步到第6步就行，PR 会自动同步你的新改动，直到被合并或关闭。

贡献类型

我们可以接受以下类型的贡献：

• 📝 翻译改进：修正翻译错误、优化表达、统一术语
• ✏️ 内容更新：跟随官方文档更新保持同步
• 🔧 错误修复：修复文档中的事实性错误或过时信息
• 💡 示例补充：添加更多实用示例或截图
• 🎨 排版美化：改善文档的可读性和结构

行为准则

请遵守以下原则：

• 尊重他人：友善沟通，建设性反馈
• 注重质量：确保贡献的内容准确、有用
• 保持一致：遵循现有的文档风格和格式规范
• 及时响应：PR 审查意见后尽快处理

感谢你对 Pylon 中文文档的贡献！🎉