Aller au contenu principal

Documentation d'Electron

· 4 mins de lecture
jlord
jlord

Cette semaine, nous avons hébergé la documentation d'Electron sur electronjs.org. Vous pouvez visiter /docs/latest pour la dernière série de documents. 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.

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

Si vous souhaitez contribuer au contenu du répertoire docs, vous pouvez le faire en accédant au dépôt Electron, où sont récupéré les documentation. Nous les récupérons pour chaque version mineure et les ajoutons au dépôt du site Electron, qui est produit à l'aide de Jekyll.

Si vous souhaiter en savoir plus sur la façon dont nous extrayons les documents d'un dépôt vers un autre, continuez à lire ci-dessous. Sinon, profitez des docs!

The Technical Bits​

We're preserving the documentation within the Electron core repository as is. Cela signifie que electron/electron aura toujours la dernière version des documents. When new versions of Electron are released, we duplicate them over on the Electron website repository, electron/electronjs.org.

script/docs​

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:

Tests help us know that all the bits and pieces landed as expected.

Jekyll​

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​

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

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​

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

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​

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

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

Hope you enjoyed these technical bits! Si vous désirez en savoir plus sur l'utilisation de Jekyll pour les sites de documentation, allez jeter un oeil sur comment l'équipe de docs de GitHub publie la documentation de GitHub sur Jekyll.