跳转到主要内容

Electron 文档

·阅读 4 分钟
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 网站，我们使用 集合 功能来处理文档，其结构如下

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 的文档团队如何使用 Jekyll 发布 GitHub 的文档。