Electron 文件

2015 年 6 月 4 日 ·4 分鐘閱讀

本週，我們將 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 模組

nugget 用於取得發布的 tarball並將其儲存至暫時目錄。
gunzip-maybe 用於解壓縮 tarball。
tar-fs 用於從 tarball 串流傳輸 /docs 目錄，以及篩選和處理檔案（藉助 through2），以便它們能與我們的 Jekyll 網站順利運作（下面將詳細說明）。

測試可協助我們瞭解所有位元和片段是否如預期般落地。

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，因此 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 的文件。

技術細節​

script/docs​

Jekyll​

前端資料​

設定和重新導向​

版面配置​