创建本地环境

可以在计算机上本地运行 GitHub Docs 应用程序。

本文内容

关于 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”。

延伸阅读