创建本地环境

关于 GitHub Docs 站点结构

GitHub Docs 站点最初是一个 Ruby on Rails Web 应用程序。一段时间后，它被转换为由 Jekyll 提供支持的静态站点。几年后，它迁移到另一个 Ruby 静态站点生成器 Nanoc。

如今，它是由 Express 提供支持的动态 Node.js Web 服务器，使用中间件支持正确的 HTTP 重定向、语言标头检测和动态内容生成，以支持各种类型的 GitHub 的产品文档，如 GitHub.com 和 GitHub Enterprise Server。

多年来，此站点的工具发生了变化，但原始 Jekyll 站点的许多经过验证的可靠创作约定都得到了保留。

内容编写在位于 content 目录中的 Markdown 文件中。
data 目录中的文件可通过 {% data %} 标记用于模板。
Markdown 文件可以包含前辅文。
支持 redirect_from Jekyll 插件行为。

设置本地环境

经过一些初始设置后，可以克隆 GitHub Docs 存储库，并在计算机上本地运行应用程序。

安装 Node.js

GitHub Docs 站点由 Node.js 提供支持。它在 macOS、Windows 和 Linux 环境中运行。

若要运行站点，需要 Node.js。若要安装 Node.js，请从 nodejs.org 下载“LTS”安装程序。若要检查所需的 Node 版本，可以在 GitHub Docs 存储库中查看 package.json 文件。 Node 版本列在 engine 字段中，类似于以下示例，该示例指示可以使用 Node 主版本 16 或 Node 主版本 18。

"engines": {
    "node": "^16 || ^18"
}

如果使用 nodenv，请参阅 nodenv 文档，获取有关切换 Node.js 版本的说明。

启动本地 GitHub Docs 服务器

安装了 Node.js（它包括常用的 npm 包管理器）后，打开终端并运行以下命令。

git clone https://github.com/github/docs
cd docs
npm ci
npm start

现在，你应该有一个正在运行的服务器。若要访问本地预览环境，请在浏览器中访问 localhost:4000。

准备好停止本地服务器时，请在终端窗口中键入 Ctrl+C。

注意：每次拉取分支的最新版本时，通常只需运行 npm ci 和 npm run build。

npm ci 执行依赖项的干净安装，而不更新 package-lock.json 文件。
npm run build 创建静态资产，如 JavaScript 和 CSS 文件。

要详细了解 GitHub Docs 应用程序的调试和故障排除，请参阅 github/docs 存储库中的“对环境进行故障排除”。

使用浏览器快捷方式

GitHub Docs 存储库中的 src/bookmarklets 目录包含有助于查看 GitHub 文档的浏览器快捷方式。有关详细信息，请参阅目录的 README。

启用不同的语言

默认情况下，本地服务器不会在启用所有受支持的语言的情况下运行。如果需要使用特定语言运行本地服务器，可以临时编辑 package.json 中的 start 脚本并更新 ENABLED_LANGUAGES 变量。

例如，若要在英语之外启用日语和葡萄牙语，可以在 start 脚本中编辑 package.json 并设置 ENABLED_LANGUAGES='en,ja,pt'。然后，重启服务器，使更改生效。

注意：在提交更改之前，应将 package.json 文件还原到其原始状态。

支持的语言代码在 src/languages/lib/languages.js 中定义。

使用 GitHub Codespaces

作为在本地运行 GitHub Docs 的替代方法，可以使用 GitHub Codespaces。通过 GitHub Codespaces，可直接从浏览器编辑、预览和测试更改。

有关使用 codespace 处理 GitHub 文档的详细信息，请参阅“在 codespace 中处理 GitHub Docs”。