创建本地环境

关于 GitHub Docs 站点结构

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

如今，它是由 Express 提供支持的动态 Node.js Web 服务器，使用中间件支持正确的 HTTP 重定向、语言标头检测和动态内容生成，以支持各种类型的 GitHub 的产品文档，如免费、专业和团队版以及 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 仓库中的对环境进行故障排除。

启用不同的语言

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

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

注意

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

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

使用 GitHub Codespaces

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

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

本文内容