创建本地环境

关于 GitHub Docs 网站结构

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

如今，它是一个由 Express 提供支持的动态 Node.js Web 服务器，使用中间件来支持正确的 HTTP 重定向、语言头检测和动态内容生成，以支持 GitHub 产品文档的各种版本，例如 GitHub.com 和 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 文档”。

本文内容