跳到主要内容

Electron 文档

·阅读时长 5 分钟
jlord
jlord

本周，我们将 Electron 的文档主页设在 electronjs.org。你可以访问 /docs/latest 以获取最新文档。我们也会保留旧版文档，因此你可以访问 /docs/vX.XX.X 以获取与你正在使用的版本对应的文档。

你可以访问 /docs 查看可用版本，或者访问 /docs/all 在一个页面上查看最新版所有文档 (方便进行 cmd + f 搜索)。

如果你想为文档内容做贡献，可以在 Electron 仓库 中进行，文档就是从那里获取的。我们为每个小版本发布获取文档，并将其添加到使用 Jekyll 构建的 Electron 网站仓库。

如果你有兴趣了解我们如何将文档从一个仓库拉取到另一个仓库，请继续阅读下文。否则，尽情享用 文档 吧！

技术细节​

我们正在 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

前置数据​

为了让 Jekyll 渲染每个页面，它至少需要空的前置数据。我们将在所有页面上使用前置数据，因此在流式输出 /docs 目录时，我们会检查文件是否为 README.md 文件 (在这种情况下它会收到一种前置数据配置)，或者是否是任何其他带有 Markdown 扩展名的文件 (在这种情况下它会收到略微不同的前置数据)。

每个页面都接收这组前置数据变量：

---
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 文件除了这段前置数据外是空的，它允许用户通过访问此 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 文档团队如何通过 Jekyll 发布 GitHub 的文档。