跳到主要內容

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，其命令列介面為 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

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 和 Redirects​

在網站的 _config.yml 檔案中，每次在取得文件時使用 --latest 標誌時，都會設定變數 latest_version。我們還新增了已新增到網站的所有版本清單，以及我們希望整個文件集合使用的 permalink。

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 }}
---

Layouts​

在 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 上循環遍歷配置中的清單。此外，我們還為此頁面提供一個 permalink：/docs/

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

希望您喜歡這些技術細節！如果您有興趣了解更多關於將 Jekyll 用於文件網站的資訊，請查看 GitHub 的文件團隊如何發布 GitHub 在 Jekyll 上的文件。