Skip to main content

Electron 文档

· 8 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.

如果你想了解更多关于我们如何将文档从一个仓库拉到另一个仓库的信息，请继续阅读下面的内容。否则，请享用这些文档！

🌐 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 的 脚本，可以选择使用或不使用 --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:

测试 帮助我们确认所有零部件都按预期到位。

Jekyll​

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

🌐 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 渲染每个页面，它至少需要空的 front matter。我们打算在所有页面上使用 front matter，所以在我们浏览 /docs 目录时，会检查文件是否是 README.md 文件（如果是，它会接收到一种 front matter 配置），或者是否是任何其他扩展名为 Markdown 的文件（如果是，它会接收到稍微不同的 front matter）。

🌐 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 除了这段前置内容外是空的，这段前置内容允许用户通过访问这个网址 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 的文档团队是如何在 Jekyll 上发布 GitHub 的文档 的。

🌐 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.