メインコンテンツへスキップ

Electronドキュメント

·4分で読めます
jlord
jlord

今週、Electronのドキュメントのホームをelectronjs.orgに設けました。最新のドキュメントについては/docs/latestにアクセスできます。古いドキュメントのバージョンも保持しているため、使用しているバージョンに対応するドキュメントについては/docs/vX.XX.Xにアクセスできます。

利用可能なバージョンを確認するには/docsにアクセスするか、最新バージョンのドキュメントを1ページで表示するには/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ファイルであるかどうか（その場合は1つのフロントマター構成を受け取る）、またはマークダウン拡張子を持つその他のファイルであるかどうか（その場合はわずかに異なるフロントマターを受け取る）を確認します。

各ページには、このフロントマター変数のセットが与えられます。

---
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には、URLがぎこちない/readme/ではなく、一般的なルートのindex.htmlになるように、追加のpermalinkが与えられます。

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 ファイルは、このフロントマターを除いて空です。このフロントマターにより、ユーザーは特定の最新バージョン番号を使用する代わりに、この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 のドキュメントチームが GitHub のドキュメントを Jekyll で公開している方法を確認してください。