创建本地环境

关于 GitHub Docs 站点结构

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

如今，它是一个由 Express 提供支持的动态 Node.js 网络服务器，使用中间件来支持正确的 HTTP 重定向、语言标头检测和动态内容生成，以支持 GitHub 产品文档的各种版本，例如免费版、专业版和团队版以及 GitHub Enterprise Server。

该站点的工具多年来一直在变化，但原始 Jekyll 站点的许多行之有效的创作约定都得到了保留。

内容以 Markdown 文件编写，这些文件位于 `content` 目录中。

`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` 变量。

例如，要除了英语之外还要启用日语和葡萄牙语，您可以编辑 `package.json` 并将 `start` 脚本中的 `ENABLED_LANGUAGES` 设置为 `'en,ja,pt'`。然后重新启动服务器以使更改生效。

注意

在提交更改之前，您应该将 `package.json` 文件恢复到其原始状态。

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

使用 GitHub Codespaces

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

有关使用 codespace 处理 GitHub 文档的更多信息，请参阅“在 Codespace 中处理 GitHub 文档”。

本文内容