Skip to main content

Electron 文档

· 9 min read
jlord

本周，我们将 Electron 的文档发布到 electronjs.org 上。你可以访问 /docs/latest 获取最新的文档集。我们也会保留旧版本的文档，以便你可以访问 /docs/vX.XX.X 获取与你当前使用的版本相关的文档。

¥This week we've given Electron's documentation a home on electronjs.org. You can visit /docs/latest for the latest set of docs. We'll keep versions of older docs, too, so you're able to visit /docs/vX.XX.X for the docs that correlate to the version you're using.

你可以访问 /docs 查看可用的版本，或访问 /docs/all 查看同一页面上的最新版本文档（非常适合 cmd 和 f 搜索）。

¥You can visit /docs to see what versions are available or /docs/all to see the latest version of docs all on one page (nice for cmd + f searches).

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

¥If you'd like to contribute to the docs content, you can do so in the Electron repository, where the docs are fetched from. We fetch them for each minor release and add them to the Electron site repository, which is made with Jekyll.

如果你想了解更多关于我们如何将文档从一个仓库拉取到另一个仓库的信息，请继续阅读下文。否则，尽情享受 docs 吧！

¥If you're interested in learning more about how we pull the docs from one repository to another continue reading below. Otherwise, enjoy the docs!

技术细节​

¥The Technical Bits

我们将原封不动地保存 Electron 核心代码库中的文档。这意味着 electron/electron 将始终拥有最新版本的文档。当 Electron 发布新版本时，我们会将其复制到 Electron 网站代码库 electron/electronjs.org 上。

¥We're preserving the documentation within the Electron core repository as is. This means that electron/electron will always have the latest version of the docs. When new versions of Electron are released, we duplicate them over on the Electron website repository, electron/electronjs.org.

script/docs​

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

¥To fetch the docs we run a script with a command line interface of script/docs vX.XX.X with or without the --latest option (depending on if the version you're importing is the latest version). Our script for fetching docs uses a few interesting Node modules:

测试 帮助我们了解所有细节是否按预期完成。

¥Tests help us know that all the bits and pieces landed as expected.

Jekyll​

Electron 网站是一个 Jekyll 网站，我们利用 集合 功能编写文档，其结构如下：

¥The Electron website is a Jekyll site and we make use of the Collections feature for the docs with a structure like this:

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

前言​

¥Front matter

为了使 Jekyll 能够渲染每个页面，至少需要空白的前端内容。我们在流出 /docs 目录时，会检查文件是否为 README.md 文件（在这种情况下，它会收到一个前置配置），或者是否是任何其他带有 markdown 扩展名的文件（在这种情况下，它会收到略有不同的前置配置）。

¥For Jekyll to render each page it needs at least empty front matter. We're going to make use of front matter on all of our pages so while we're streaming out the /docs directory we check to see if a file is the README.md file (in which case it receives one front matter configuration) or if it is any other file with a markdown extension (in which case it receives slightly different front matter).

每个页面都包含以下一组前置变量：

¥Each page receives this set of front matter variables:

---
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/。

¥The README.md gets an additional permalink so that has a URL has a common root of index.html rather than an awkward /readme/.

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

配置和重定向​

¥Config and Redirects

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

¥In the site's _config.yml file a variable latest_version is set every time the --latest flag is used when fetching docs. We also add a list of all the versions that have been added to the site as well as the permalink we'd like for the entire docs collection.

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），而无需专门输入最新版本号（尽管你也可以这样做）。

¥The file latest.md in our site root is empty except for this front matter which allows users to see the index (aka README) of the latest version of docs by visiting this URL, electron.atom.io/docs/latest, rather than using the latest version number specifically (though you can do that, too).

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

布局​

¥Layouts

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

¥In the docs.html layout template we use conditionals to either show or hide information in the header and breadcrumb.

{% 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/

¥To create a page showing the versions that are available we just loop through the list in our config on a file, versions.md, in the site's root. Also we give this page a permalink: /docs/

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

希望你喜欢这些技术知识！如果你想了解更多关于使用 Jekyll 构建文档网站的信息，请查看 GitHub 文档团队如何发布 GitHub Jekyll 文档。

¥Hope you enjoyed these technical bits! If you're interested in more information on using Jekyll for documentation sites, checkout how GitHub's docs team publishes GitHub's docs on Jekyll.