为文档做贡献

我们欢迎对我们的文档仓库 dvc.org 提交任何贡献。贡献可以是文档内容的更新，或（较少见）对我们用于运行网站的 JS 引擎所做的更改。

对于小幅度修改，您可以使用 在 GitHub 上编辑 按钮打开源代码页面。点击编辑按钮（铅笔图标）直接编辑文件，然后从页面底部选择 提交更改。

项目结构

要为文档做贡献，请关注以下相关位置：

内容 (content/docs/)：存放 Markdown 文件。一个文件对应文档中的一页。
图片 (static/img/)：在此添加新图片（.png、.svg 等）。在 Markdown 文件中通过如下语法引用：![](/img/<filename>.gif)。
导航栏 (content/docs/sidebar.json)：编辑此文件可添加或修改导航侧边栏中的条目。

将相应更改合并到 main 分支即可更新文档并重新部署网站。

提交更改

请在问题跟踪器中查找或新建一个问题，以便告知我们您正在处理此项工作。
请遵循下方的风格指南格式化源代码。我们强烈建议按照下文说明设置好开发环境，它可以帮助您自动格式化文档和 JS 代码。
将更改推送到您自己的 dvc.org 仓库，并向主仓库提交 Pull Request（PR）。

我们将尽快审核您的 PR。感谢您的贡献！

开发环境

我们强烈建议在本地运行该 Web 应用程序，以在提交前检查文档更改效果；当需要修改网站引擎本身时，这一点尤为必要。源代码和内容文件也需正确格式化和校验，完整的本地设置（如下所述）可确保这一点。

请确保已安装较新的 LTS 版本 Node.js（>=18.0.0，<=20.x），并安装 Yarn：

在 Windows 系统中，您可能需要先安装 Visual Studio Build Tools 和 [Windows

SDK]。

$ npm install -g yarn

克隆该项目到本地后，进入项目目录并使用 Yarn 安装依赖项：

$ yarn

通过以下命令在本地启动服务器：

$ yarn develop

这将在默认端口 8000 启动服务器。访问 http://localhost:8000/ 并跳转至目标页面。此操作还会启用 pre-commit Git 钩子，在每次提交时自动格式化和校验您的代码及文档文件。

所有命令

这些 Node 脚本定义在文档仓库的 package.json 文件中。

构建并运行项目：

yarn develop - 启动支持热重载的开发服务器。
yarn build - 在 public 目录下构建静态资源。
yarn start - 在 public 目录上运行生产级静态服务器。

所有以下测试、格式化和代码检查操作都会在每次提交时通过 Husky 和 lint-staged 自动执行，同时在 GitHub Actions 中通过提交 PR 触发时也会进行验证。

如果修改了源代码文件，请运行测试：

yarn test - 运行测试。

我们使用 Prettier 来格式化源代码。以下是为方便起见提供的一组封装命令：

yarn format-all - 对所有文件运行 prettier --write，查找格式问题并自动修复尽可能多的问题。
yarn format-check-all - 对所有文件运行 prettier --check，如果发现任何问题则以错误退出。这对持续集成（CI）特别有用。
yarn format-staged - 是 lint-staged 的别名，将在你本地 Git 仓库中已暂存的所有文件上运行所有适用的检查工具。
yarn format <file> - 对特定文件运行 prettier。

我们使用检查工具（例如 ESLint）来检查源代码风格并检测各种错误：

yarn lint - 对所有兼容的源代码文件运行 eslint：js、jsx、ts、tsx、json。
yarn lint-fix - 使用 eslint --fix 自动修复尽可能多的问题。
yarn lint-ts - 使用 tsc 尝试编译项目，确保所有 TypeScript 类型都正确无误。
yarn lint-css - 使用 stylelint 检查 .css 文件，其覆盖范围超过仅使用 prettier 的效果。

要在一个命令中使用上述所有工具的“修复”版本，请使用 yarn fix-all。

请注意，你可以始终直接使用格式化工具或检查工具（例如 yarn eslint <file> 或 yarn prettier --check <file>）。

环境变量

某些环境变量是将本项目部署到生产环境所必需的，其他变量可用于调试项目。请检查生产系统设置，查看生产与部署系统所依赖的所有变量。

一些可用的变量：

GA_ID – Google Analytics 统计代码的 ID。
ANALYZE - 布尔值属性，用于运行 webpack-analyzer。
SENTRY_DSN - 用于错误追踪的 Sentry URL。

文档风格指南（JavaScript 和 Markdown）

以下部分规则会在 yarn 运行时通过安装的 Git 预提交钩子自动应用（参见开发环境）。

不允许存在尾随空格。
文本内容应在 80 个字符宽度内正确格式化。

💡 我们建议使用带有 Rewrap 插件的 Visual Studio Code 来帮助完成此任务。
你可以在此处查看我们的格式化工具（Prettier）的配置 here。你也可以手动运行格式化命令。（通过 yarn prettier ... 可实现 Prettier 的高级用法）
Markdown：使用 dvc <command>，文档引擎将自动创建指向该命令的链接。（无需显式使用 []() 创建链接。）
Markdown：使用 dvc.api.<api_method>() 或 dvc.api，文档引擎将自动创建指向该 API 方法的链接。（无需显式使用 []() 创建链接。）
Markdown：项目符号列表不应过长（最多 5-7 项，理想情况下）。
Markdown：每个项目符号中的文本也不应过长（最多三句话）。完整的句子项目应以大写字母开头，并以句号 . 结尾。否则，可以全部使用小写，且无需结尾标点。如果项目包含多个段落，可用空行分隔，但不建议这样做：请尽量保持条目简短。
Markdown：代码块中的语法高亮应使用 usage、dvc、dvctable、yaml 或 diff 这些自定义语言。
- usage 用于展示每个命令参考文档中的 dvc --help 输出结果。
- dvc 可用于展示终端会话中命令及其输出的示例。
- dvctable 用于创建带有颜色、加粗或斜体样式的表格单元格。（你可以在我们的“快速入门”部分看到一个示例。）
- yaml 用于展示 DVC 文件或其他 YAML 内容的示例。
- diff 主要用于展示 git diff 输出的示例。

查看任意命令参考文档的 .md 源代码可获得更直观的理解，例如本文件。

通用语言规范

我们力求在文档中使用轻松有趣的语气。同时避免使用权威性语言，例如“显然，事情就是这样发生的，当然……”等表达方式，尽管这些说法本意良好，但可能会让读者望而生畏。

只要表述准确，我们更倾向于使用通俗易懂的人性化语言，而非专业术语。例如：避免使用 Git 中的术语如 修订版本（revision） 或 引用（reference），而改用更基础的词汇如 提交（commit） 或 版本（version）。

命令参考包含了我们最技术性的文档，其中使用了较多的专业术语，但即便如此，我们也通过可展开的章节来呈现复杂的实现细节。

先用简单明了的语言写出核心内容，再通过后续补充说明、边界情况或其他精确信息进行完善。

我们使用粗体来强调重点，使用斜体表示特殊术语。

我们也会适度使用“表情符号”来提高某些提示的可见性。主要如下：

📖 用于链接到其他相关文档的备注
⚠️ 关于高级 DVC 使用的重要警告或免责声明
💡 实用的提示和建议，通常与外部工具和集成相关

目前还在零星使用的其他表情符号包括：⚡ ✅ 🙏 🐛 ⭐ ⚙️ ℹ️（以及其他）。