贡献指南

Docsy 是一个开源项目，我们喜欢获得补丁和贡献，使 Docsy 及其文档变得更好。

为 Docsy 做贡献

Docsy 主题本身就存在于https://github.com/google/docsy.

贡献者许可协议

对本项目的贡献必须附有贡献者许可协议。您（或您的雇主）保留您的贡献的版权；这只是 允许我们将您的贡献作为项目的一部分进行使用和重新分发。前 往https://cla.developers.google.com/ 以查看文件中的当前协议或签署新协议。

你通常只需要提交一次 CLA，所以如果你已经提交了一个（即使是针对不同的项目），你可 能不需要再提交了。

代码审查

所有提交的材料，包括项目成员提交的材料都需要审查。为此，我们使用 GitHub 拉取请求 。咨询GitHub 帮助有关使 用拉取请求的更多信息。

预览您的更改

由于 Docsy 是一个主题而不是一个网站，您不能直接提供主题来检查您的更改工作。而是 在 Docsy 示例网站的本地副本中使用您更新的本地主题（在’themes/Docsy’目录中复制或 进行更改）和preview从那里。或者，克 隆Docsy theme repo并在本网站的本地副本中测试 您的更改，如下所述below.

社区指导

该项目遵循谷歌的开源社区指南.

创建 issue

或者，如果你想在 Docsy 中看到一些东西（或者你发现了一些不符合你预期的东西），但 你不确定如何自己解决，请创建一个问题.

为这些文档做贡献

这个用户指南和我们的示例站点一样，是一个使用 Hugo 静态站点生成器的 Docsy 站点。 我们欢迎更新文档！

我们使用Netlify以管理网站的部署并提供文档更新的预览 。这里的说明假设您熟悉 GitHub 的基本工作流程。

使用 Netlify 快速入门

1.分叉Docsy repo在 GitHub 上：该网站的文件位 于“userguide”子目录中。 2.做出更改并发送拉取请求（PR）。 3.如果您还没有准备好进 行审查，请在 PR 名称中添加“WIP”，表示这是一项正在进行的工作。（不要将 Hugo 属性“draft=true”添加到页面首页，因为这会阻止下一点中描述的内容预览的自动部署。 ） 4.等待自动 PR 工作流进行一些检查。当它准备就绪时，您应该看到这样的评论 ：deploy/netlify–部署预览就绪 5.单击“部署预览就绪”右侧的详细信息，查看 您的更新预览。 6.继续更新你的文档并推送你的更改，直到你对内容满意为止。 7.当你准 备好进行审查时，在 PR 中添加注释，并删除任何“WIP”标记。

更新单个页面

如果您在使用文档时发现了想要更改的内容，Docsy 有一个快捷方式：

1.单击页面右上角的编辑此页面。 2.如果您还没有项目回购的最新分支，系统会提示 您获取一个-单击分支此存储库并提出更改或更新您的分支以获取要编辑的项目的 最新版本。叉子中相应的页面以编辑模式显示。 3.按 照Quick start with Netlify

在本地预览更改

如果您想在工作时运行自己的本地 Hugo 服务器来预览您的更改：

1.按照Getting started中的说明进行操作 2.分 叉Docsyrepo 到您自己的项目中，然后使用“git clone”创建本地副本：

git clone https://github.com/google/docsy.git

3.切换到“userguide”目录并运行以下 Hugo 命令来构建站点并启动 Hugo 服务器。请注意 ，您需要“themesDir”标志，因为站点文件位于主题存储库中。

cd userguide
hugo server --themesDir ../..

默认情况下，您的网站将在 http://localhost:1313/ .现在您在本地为您的网站提供服 务，Hugo 将关注内容的更改并自动刷新您的网站。

4.继续使用通常的 GitHub 工作流程来编辑文件、提交文件、将更改推送到您的 fork，并 创建一个 pull 请求。

使用 Docker 容器预览您的更改

Docsy 附带了“Dockerfile”和“docker compose”文件，可以使用 docker 在本地运行服务器 ，而无需安装任何其他依赖项。

• Using Docker:

  1.构建 Docker 容器：

   ```bash
   docker build -t docsy/user-guide .
   ```
  

  2.运行容器，将存储库装载为共享卷：

   ```bash
   docker run -it --user=$(id -u):$(id -g) -p 1313:1313 \
     -v $(pwd):/app/docsy -v /app/docsy/userguide/node_modules \
     docsy/user-guide
   ```
  

• Using Docker Compose:

  1. 构建 Docker 容器:

     docker-compose build
     

  2. 运行 Docker 容器:

     DOCSY_USER=$(id -u):$(id -g) docker-compose up
     

打开http://localhost:1313 在您的 web 浏览器中加载 docsy 用户指南。在大多数情 况下，docsy 会自动重新加载网站，以反映对文档或代码的任何更改。对 docsy 代码某些 部分的更改可能需要手动重新加载页面或重新启动容器。

按Ctrl+C可停止容器。 [docker]: https://docs.docker.com/get-docker/ [docker-compose]: https://docs.docker.com/compose/install/

创建 issue

如果您想在文档中看到一些内容，但不确定如何自己解决，请在[此存储库]中创建一个问题 (https://github.com/google/docsy). 您也可以通过单击页面右上角的创建问题按 钮来创建有关特定页面的问题。

用户指南格式

我们使用 [Prettier]（https://prettier.io） 来格式化 User 的 Markdown 源代码指导。要检查文档更改的格式，请使用以下命令：

npm run check:format

要自动修复格式问题，请运行“npm run fix：format”。

Prettier 目前不理解 Hugo 模板语言指令，所以你可能需要使用以下 ignore 指令将此类指令括起来：

<!-- prettier-ignore-start -->
{{< tabpane >}}
...
{{< /tabpane >}}
<!-- prettier-ignore-end -->

您可以使用这些 ignore 指令来包围您想要的任何 Markdown更漂亮，可以忽略。如果该区域是连续的文本块，则可以省略 end 指令，将 start 指令替换为 ‘prettier-ignore-start’。

创建问题

如果您想在文档中看到某些内容，但您不确定如何操作自行修复，请在[此存储库]（https://github.com/google/docsy）。您也可以创建议题通过单击右上角的“创建问题”按钮来了解特定页面 页面的手角。