做出更大贡献
如果您有更详细的评论或想要提供新内容？那么您需要了解更多信息才能提供此类反馈。
您需要为文档设置本地环境，在本地进行编辑或创建新内容，然后通过针对 GitHub 上 CumulusNetworks/docs 存储库的拉取请求提交所有内容。
开始之前
安装 Hugo
第一步是安装 Hugo
根据您的操作系统选择相关的 extended 软件包
- hugo_extended_0.82.0_Linux-64bit.deb
- hugo_extended_0.82.0_Linux-64bit.tar.gz
- hugo_extended_0.82.0_macOS-64bit.tar.gz
- hugo_extended_0.82.0_Windows-64bit.zip
您必须使用 **extended** 版本的 Hugo 以支持我们对 SCSS 样式表的使用。
解压缩并从下载的文件中安装 Hugo。
验证 Hugo 是否已安装并正在运行。
在终端窗口中，运行
hugo version<computer>:<username>$ hugo version hugo v0.82.0-9D960784+extended linux/amd64 BuildDate=2021-03-21T17:28:04Z VendorInfo=gohugoio
克隆文档存储库
下一步是获取 Cumulus Networks 文档存储库的本地副本
创建一个目录，用于存储文档文件。
确保 Branch 位于 *stage* 分支，然后单击 **Clone or download**。
复制 HTTPS URL。
返回终端窗口中的目录并键入
git clone。粘贴 URL，然后按 **Enter**。
<computer>:<cndocs-repo> <username>$ git clone https://github.com/CumulusNetworks/docs.git
克隆完成后，您的目录应该包含所有源文件的副本。
运行本地服务器
最后的设置步骤是验证您可以使用 Hugo 查看文档存储库的本地副本
在终端窗口中，导航到
docs子目录。通过运行
hugo server --baseURL localhost:1313启动 hugo 服务器。您应该看到类似于以下的输出
<computer>:docs <username>$ hugo server Building sites... | EN -------------------+------- Pages | 769 Paginator pages | 0 Non-page files | 2003 Static files | 1925 Processed images | 0 Aliases | 0 Sitemaps | 1 Cleaned | 0 Built in 6294 ms Watching for changes in /Users/<username>/<cndocs-repo>/docs/{content,data,static,themes} Watching for config changes in /Users/<username>/<cndocs-repo>docs/config.toml Environment: "development" Serving pages from memory Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender Web Server is available at //:1313/ (bind address 127.0.0.1) Press Ctrl+C to stop在 Web 浏览器的地址栏中，输入 https://:1313。
当您对源 Markdown 文件进行更改并保存后，更新将在此处显示。
如果页面似乎没有更新，您可能需要停止 Hugo 服务器（按 Ctrl+c）并使用
hugo server --baseURL localhost:1313 --gc重新启动它，以在不使用缓存数据的情况下重建站点。
您现在可以编辑文档或创建新主题。请参阅 添加新内容。
使用 Vale 遵循内部风格
文档使用 Vale 作为代码检查工具，以保持写作风格一致。可以将其视为您在命令行调用的 AI 编辑器。
安装 Vale
首先，安装 Vale。在终端中运行以下命令
$ brew install vale
> choco install vale
$ docker pull jdkato/vale
运行 Vale
在运行 Vale 之前，从 stage 分支拉取最新版本，然后确保您的本地检出包含 `/utils/.vale` 文件夹。
从本地检出的根目录运行 Vale
$ vale --glob='!*{foss,rn}.md' --config utils/.vale/.vale.ini content/cumulus-linux-43
上面的命令使用以下参数和选项
- `--glob` 正则表达式指示 Vale 忽略 `foss.md` 和 `rn.md` 文件；Vale 不检查发行说明或 Cumulus Linux 开源软件许可页面。
- `--config utils/.vale/vale.ini` 告诉 Vale 在哪里找到其配置文件。
- `content/cumulus-linux-43` 是 Vale 将要检查的文件夹。Vale 会递归遍历其下的每个文件夹，因此如果您在顶层 `content` 文件夹上运行它，它将检查每个版本和产品的每个页面。
Vale 返回类似于以下示例的输出
pete$ vale --glob='!*{foss,rn}.md' --config utils/.vale/.vale.ini content/cumulus-netq-40
...
content/cumulus-netq-40/Manage-Configuration/Provision-Network-and-Devices/Switch-Lifecycle-Management/CL-Upgrade-LCM.md
219:104 error 'Mellanox' should reference NVIDIA.Branding
NVIDIA Networking or NVIDIA
Spectrum
content/cumulus-netq-40/Get-Started/NetQ-Basics/NetQ-Components.md
35:60 warning 'bare metal' is the house NVIDIA.WordStyles
style of 'bare-metal'
99:9 warning '-' should use title NVIDIA.HeadingTitles
caps-style capitalization.
content/cumulus-netq-40/Validate-Operations/_index.md
120:328 warning Possible future tense ?? NVIDIA.FutureTense
...
✖ 1 error, 408 warnings and 0 suggestions in 131 files.
pete$
Vale 输出分解如下
- 存在问题的文件名和路径。
- 问题在 Markdown 文件中的位置。例如，35:60 表示第 35 行，光标位置 60。
- 问题的严重程度，为 *error*、*warning* 或 *suggestion* 之一。
- 错误消息本身。
- 引用规则的 Vale 配置文件。例如，*NVIDIA.WordStyles* 是 `utils/.vale/NVIDIA` 目录中的 WordStyles.yml 文件。
忽略错误
有时，Vale 可能会将某些内容标记为错误，但实际上是误报。如果单词选择或拼写是有充分理由违反规则的，您可以禁用对该文本的 Vale 检查。例如，NVIDIA Vale 样式指南规定标题中不应有任何标点符号，但这不适用于版本号，如以下示例所示
## For Servers Running Ubuntu 16.04 or 18.04
Run the following command to view the NetQ Agent version.
Vale 在检查该标题时返回以下错误
21:33 warning '.' should use title NVIDIA.HeadingTitles
caps-style capitalization.
要避免错误，您可以在源文件中禁用对该标题的 Vale 检查。将整个段落包装在 <!-- vale off --> 和 <!-- vale on --> 标签中
<!-- vale off -->
## For Servers Running Ubuntu 16.04 or 18.04
<!-- vale on -->
Run the following command to view the NetQ Agent version.
`<!-- vale on -->` 标签必须单独占一行才能重新启用 Vale 检查；否则，Vale 将忽略文件的其余部分。
Vale 目前存在一个错误，它无法正确忽略标题中的连字符 (-)。如果您编写了带有连字符的标题并看到此错误，请禁用 Vale 并添加注释，以便我们稍后可以找到它。例如
<!-- vale off -->
<!-- vale.ai Issue #253 -->
### Any-source Multicast Routing (ASM)
<!-- vale on -->
扩展检查
欢迎随时建议修改 `.vale` 文件夹中的任何内容，或提交您自己的拉取请求。
Hugo 故障排除
大量更改
如果 Hugo 当前正在运行并且进行了大量更改，例如更改分支，Hugo 可能并不总是检测到更改。停止并重新启动 Hugo 以查看新更改。
Hugo pipe failed 错误
启动 Hugo 时，它可能会失败并产生类似于以下的追溯
Start building sites …
| EN
-------------------+-------
Pages | 1736
Paginator pages | 0
Non-page files | 6722
Static files | 1685
Processed images | 0
Aliases | 0
Sitemaps | 1
Cleaned | 0
Built in 18957 ms
Watching for changes in /git/docs/{content,static,themes}
Watching for config changes in /git/docs/config.yml
fatal error: pipe failed
这是由操作系统对打开文件数量的限制引起的。验证和调整此限制的方法取决于所使用的操作系统和版本。
Mac OSX 10.4 Mojave 及更高版本
要调整最大文件限制，您必须同时更改内核设置和会话 ulimits。
sudo sysctl -w kern.maxfiles=65536
ulimit -n 65536 65536
`ulimit` 调整仅在终端窗口的生命周期内有效。如果窗口关闭或打开新窗口，则必须再次运行 `ulimit` 命令。
稀疏检出
可以仅检出文档存储库的一部分，以便仅处理您希望贡献的部分。Git 将此部分检出称为稀疏检出。
稀疏检出可加快 Hugo 构建时间，限制本地磁盘空间的使用量，并且可以是 Hugo `pipe failed` 错误消息的有效解决方法。
要创建稀疏检出
为存储库创建目标目录
mkdir docs进入新目录并使用 Git 初始化它
cd docs git init将文档存储库添加为 Git 远程仓库
git remote add -f origin git@github.com:CumulusNetworks/docs.git将此目录配置为稀疏检出
git config core.sparseCheckout true配置 Git 以检出强制性的文档文件
echo "utils/" >> .git/info/sparse-checkout echo "config.toml" >> .git/info/sparse-checkout echo "build_trigger.txt" >> .git/info/sparse-checkout echo "themes/" >> .git/info/sparse-checkout echo ".vale" >> .git/info/sparse-checkout echo "config.yml" >> .git/info/sparse-checkout echo "static/mibs" >> .git/info/sparse-checkout将您希望修改的内容添加到 Git 稀疏检出中。这包括 `/content` 目录中的文件以及 `/static/images` 目录中的任何相关图像。例如，要对 知识库 文章进行贡献或修改，请同时添加 `/content/knowledge-base` 和 `/static/images/knowledge-base` 目录。
echo "content/knowledge-base/` >> .git/info/sparse-checkout echo "static/images/knowledge-base/` >> .git/info/sparse-checkout检出适当的分支
git checkout stage调整 Hugo 配置以忽略链接检查。
如果您计划在本地运行 Hugo，由于 Hugo `ref` shortcode 验证链接的方式，它将导致 Hugo 因稀疏检出而在运行时失败。必须在本地更改 Hugo 配置，使其仅记录警告并允许 Hugo 启动
echo "\nrefLinksErrorLevel: WARNING" >> config.yml配置 Git 以忽略 `config.yml` 文件，以防止意外提交此更改
git update-index --assume-unchanged config.yml运行 Hugo。您可以安全地忽略 `REF_NOT_FOUND` 警告。
hugo server --baseURL localhost:1313
所有其他 git 操作（包括 `git commit`、`git push` 和 `git checkout`）均正常工作。