跳转到主要内容

Electron 文档

·阅读时长 5 分钟
jlord
jlord

本周，我们为 Electron 的文档找到了新的家：electronjs.org。您可以在/docs/latest 访问最新文档。我们也将保留旧版本的文档，以便您能访问/docs/vX.XX.X 来查看与您正在使用的版本相对应的文档。

您可以访问/docs 查看可用的版本，或访问/docs/all 在一页中查看最新版本的所有文档（方便使用 cmd + f 搜索）。

如果您想为文档内容做出贡献，可以在 Electron 仓库 中进行，文档就从这里获取。我们在每个次要版本发布时都会获取它们，并添加到 Electron 网站仓库 中，该仓库是用 Jekyll 构建的。

如果您有兴趣了解更多关于我们如何将文档从一个仓库拉取到另一个仓库的信息，请继续阅读下面的内容。否则，请尽情享用 文档！

技术细节​

我们在 Electron 核心仓库中保留了原有的文档。这意味着 electron/electron 将始终拥有最新版本的文档。当新的 Electron 版本发布时，我们会将它们复制到 Electron 网站仓库 electron/electronjs.org。

script/docs​

为了获取文档，我们运行一个 脚本，使用命令行接口 script/docs vX.XX.X，根据导入的版本是否为最新版本，加上或不加上 --latest 选项。我们用于 获取文档的脚本 使用了一些有趣的 Node 模块。

测试 帮助我们了解所有组件是否按预期落地。

Jekyll​

Electron 网站是一个 Jekyll 站点，我们为文档使用 Collections 功能，结构如下：

electron.atom.io
└── _docs
    ├── latest
    ├── v0.27.0
    ├── v0.26.0
    ├── so on
    └── so forth

Front matter​

为了让 Jekyll 渲染每个页面，它至少需要空的 front matter。我们将在所有页面上使用 front matter。因此，在流式传输 /docs 目录时，我们会检查文件是否是 README.md 文件（如果是，则为其配置一个 front matter），或者是否是其他具有 markdown 扩展名的文件（如果是，则为其配置略有不同的 front matter）。

每个页面都接收这组 front matter 变量：

---
version: v0.27.0
category: Tutorial
title: 'Quick Start'
source_url: 'https://github.com/electron/electron/blob/master/docs/tutorial/quick-start.md'
---

README.md 文件会额外获得一个 permalink，这样它的 URL 根目录就是 index.html，而不是一个不方便的 /readme/。

permalink: /docs/v0.27.0/index.html

配置和重定向​

在站点的 _config.yml 文件中，每次使用 --latest 标志获取文档时，都会设置一个 latest_version 变量。我们还会添加一个站点已添加的所有版本的列表，以及我们希望为整个文档集合设置的永久链接。

latest_version: v0.27.0
available_versions:
  - v0.27.0
collections:
  docs: { output: true, permalink: '/docs/:path/' }

站点根目录下的 latest.md 文件除了这个 front matter 外是空的。这使得用户可以通过访问 URL electron.atom.io/docs/latest 来查看最新版本文档的索引（即 README），而无需指定最新的版本号（当然，您也可以这样做）。

---
permalink: /docs/latest/
redirect_to: /docs/{{ site.data.releases[0].version }}
---

布局​

在 docs.html 布局模板中，我们使用条件语句来显示或隐藏标题和面包屑中的信息。

{% raw %} {% if page.category != 'ignore' %}
<h6 class="docs-breadcrumb">
  {{ page.version }} / {{ page.category }} {% if page.title != 'README' %} / {{
  page.title }} {% endif %}
</h6>
{% endif %} {% endraw %}

为了创建一个显示可用版本的页面，我们只需要遍历站点根目录 versions.md 文件中的配置列表。此外，我们为该页面设置了永久链接：/docs/。

{% raw %} {% for version in site.available_versions %} - [{{ version
}}](/docs/{{ version }}) {% endfor %} {% endraw %}

希望您喜欢这些技术细节！如果您对使用 Jekyll 构建文档站点感兴趣，可以查看 GitHub 的文档团队如何使用 GitHub 文档。