创建本地环境

关于 GitHub 文档站点结构

GitHub 文档站点最初是一个 Ruby on Rails Web 应用程序。随后它被转换为由 Jekyll 驱动的静态站点。再过几年后，它迁移到 Nanoc，另一个 Ruby 静态站点生成器。

如今，它是一个由 Express 提供动力的动态 Node.js Web 服务器，使用中间件来支持正确的 HTTP 重定向、语言头检测，以及动态内容生成，以支持 GitHub 各种产品文档的不同版本，如 Free、Pro、Team 和 GitHub Enterprise Server。

多年来该站点的工具链已多次更换，但原始 Jekyll 站点的许多经久不衰的创作约定仍被保留。

内容以 Markdown 文件编写，位于 content 目录下。

data 目录中的文件可通过 {% data %} 标签在模板中使用。
Markdown 文件可以包含 frontmatter。
支持 redirect_from Jekyll 插件的行为。

设置本地环境

您可以克隆 GitHub 文档仓库，并在进行一些初始设置后在本地计算机上运行该应用程序。

安装 Node.js

GitHub 文档站点由 Node.js 提供动力。它可在 macOS、Windows 和 Linux 环境中运行。

要运行站点，您需要 Node.js。要安装 Node.js，请从 nodejs.org 下载 “LTS” 安装程序。要查看所需的 Node 版本，请参阅 GitHub 文档仓库中的 package.json 文件。Node 版本列在 engine 字段中，例如下面的示例表明您可以使用 Node 主版本 16 或 Node 主版本 18。

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

如果您使用 nodenv，请参阅 nodenv 文档，了解切换 Node.js 版本的说明。

启动本地 GitHub 文档服务器

安装好 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 文档应用程序的问题，请参阅 github/docs 仓库中的排查您的环境。

启用不同语言

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

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

注意

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

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

使用 GitHub Codespaces

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

关于在 codespace 中处理 GitHub 文档的更多信息，请参阅在 codespace 中工作 GitHub 文档。

本文内容