# 创建本地环境

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

## GitHub Docs 网站结构简介

该网站 GitHub Docs 最初是 Ruby on Rails Web 应用程序。 一段时间后，它被转换为由 [Jekyll](https://jekyllrb.com/) 提供支持的静态站点。 几年后，它迁移到另一个 Ruby 静态站点生成器 [Nanoc](https://nanoc.app/)。

如今，它是由 Express 提供支持的动态 Node.js Web 服务器，它使用中间件来支持适当的 HTTP 重定向、语言标头检测和动态内容生成，以支持各种风格的 GitHub产品文档，如免费、专业和团队和 GitHub Enterprise Server。

多年来，此站点的工具发生了变化，但原始 Jekyll 站点的许多经过验证的可靠创作约定都得到了保留。

* 内容以 Markdown 文件编写。 这些内容位于 `content` 目录中。
* 内容可以使用 Liquid 模板化语言。 请参阅“[在 GitHub Docs 中使用 Markdown 和 Liquid](/zh/enterprise-cloud@latest/contributing/writing-for-github-docs/using-markdown-and-liquid-in-github-docs)”。
* `data`目录中的文件可通过`{% data %}`标记提供给模板。
* Markdown 文件可以包含[前辅文](https://jekyllrb.com/docs/front-matter)。
* 支持 [`redirect_from`](https://github.com/jekyll/jekyll-redirect-from) Jekyll 插件行为。

## 设置本地环境

可以在一些初始设置后克隆 GitHub Docs 存储库并在计算机上本地运行应用程序。

### 安装 Node.js

该网站 GitHub Docs 由 Node.js提供支持。 它在 macOS、Windows 和 Linux 环境中运行。

若要运行站点，需要 Node.js。 若要安装 Node.js， [请从 nodejs.org 下载“LTS”安装程序](https://nodejs.org)。若要检查所需的节点版本，可以在 `package.json` 存储库中看到 GitHub Docs 该文件。 Node 版本列在 `engine` 字段中，类似于以下示例，该示例指示可以使用 Node 主版本 16 或 Node 主版本 18。

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

如果使用 `nodenv`，请参阅 [`nodenv` 文档](https://github.com/nodenv/nodenv#readme)，获取有关切换 Node.js 版本的说明。

### 启动本地 GitHub Docs 服务器

安装了 Node.js（它包括常用的 `npm` 包管理器）后，打开终端并运行以下命令。

```shell
git clone https://github.com/github/docs
cd docs
npm ci
npm start
```

现在，你应该有一个正在运行的服务器。 若要访问本地环境，请在浏览器中访问 [localhost:4000](http://localhost:4000)。

准备好停止本地服务器时，请在终端窗口中键入 <kbd>Ctrl</kbd>+<kbd>C</kbd>。

> \[!NOTE] 每次拉取分支的最新版本时，通常只需要运行 `npm ci` 和 `npm run build`。
> \*
> `npm ci` 执行依赖项的干净安装，而不更新 `package-lock.json` 文件。
> \*
> `npm run build` 创建静态资产，如 JavaScript 和 CSS 文件。

若要详细了解如何调试和排查应用程序问题 GitHub Docs ，请参阅 github/docs 存储库中的 [环境故障排除](/zh/enterprise-cloud@latest/contributing/setting-up-your-environment-to-work-on-github-docs/troubleshooting-your-environment) 。

### 启用不同的语言

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

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

> \[!NOTE]
> 在提交更改之前，应将 `package.json` 文件还原到其原始状态。

支持的语言代码在 [`src/languages/lib/languages.ts`](https://github.com/github/docs/blob/main/src/languages/lib/languages.ts) 中定义。

## 使用 GitHub Codespaces

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

有关使用代码空间处理 GitHub 文档的详细信息，请参阅 [在 codespace 中编辑 GitHub 文档](/zh/enterprise-cloud@latest/contributing/setting-up-your-environment-to-work-on-github-docs/working-on-github-docs-in-a-codespace)。

## 其他阅读材料

* [创建可重用内容](/zh/enterprise-cloud@latest/contributing/writing-for-github-docs/creating-reusable-content)
* [组件](https://github.com/github/docs/blob/main/src/frame/components/README.md)
* [Data](https://github.com/github/docs/blob/main/data/README.md)
* [测试](https://github.com/github/docs/blob/main/src/tests/README.md)