跳转到主内容

Electron 文档

· 阅读时间:约 5 分钟

本周我们把 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

前页附属资料​

为了使 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 设置,这样它的根目录会是index.html 而不是奇怪的 /readme/。

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

配置和重定向​

每当获取文件时使用了--latest参数,网站的 _config.yml文件都会设置一个 latest_version变量。同时,我们维护着一个包含所有加入版本的列表,还有整个文档集合的永久链接。

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

在我们网站的根目录下,latest.md 文件是空的,只有一段元数据,它允许用户通过以下地址访问最新版本的文档的首页(也就是README的内容) electron.atom.io/docs/latest。这样的设置不需要使用最新的版本号来导航(尽管你也可以使用版本号)。

---
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's docs on Jekyll。