electron / website

:electron: The Electron website

electronjs.org

This repository contains the code for the Electron website. It is built using Docusaurus, a modern static website generator.

Installation

The website currently builds using Node.js 16. If you're using nvm, you can set the correct version of Node.js with nvm use.

To get started with a local version of the website, install dependencies with yarn. To get the website running in dev mode, run yarn start. To get a production build of the website, run yarn build.

yarn
yarn start

How to modify the documentation

English docs

For English documentation, the documentation is mirrored from the electron/electron repo. Changes are picked automatically by the electron/electron-website-updater webhook as soon as they are made in the latest stable release branch.

For example, if the latest Electron stable release is v22.0.3, then any documentation changes in the 22-x-y branch in electron/electron will be mirrored into the main branch of this repository.

Translations

This project uses Crowdin to manage localizations. For more information on contributing to translations, see the i18n.md document.

How to add a new blog post

To add a new blog post, you need to create a new Markdown file under the /blog folder. Supported frontmatter options are listed in the Docusaurus Blog docs.

Local development

If you want to modify Electron's documentation locally and preview how it looks on the website, you can tell the pre-build script to pull the docs from your local Electron repo.

yarn pre-build ../relative/path/to/local/electron/repo
yarn start

Search indexing

The search functionality on electronjs.org is powered by Algolia DocSearch. DocSearch is a program run by Algolia that offers free documentation search for open source projects.

If you are a maintainer with an @electronjs.org email, please message @erickzhao to be added to the Algolia project.

Repository content organization

This repository contains the code for two related things:

• The code to generate the contents of https://electronjs.org
• create-electron-documentation package

The content of this repository is organized as follows:

└─ root
    |
    ├─ .github/workflows → The definitions for the GitHub actions
    |
    |- blog -> Source files for electronjs.org/blog
    |
    ├─ create-electron-documentation → Code for the npm package
    |        of the same name. Read the readme in the folder
    |        for more information.
    |
    |- docs -> Mirrored docs from electron/electron
    |
    ├─ scripts → The code for the package.json tasks and GitHub
    |        actions
    |
    ├─ src → Docusaurus code
    |
    ├─ static → Docusaurus static assets

website's Issues

Use same content structure as upstream

While the new website groups the content in the folder structure to make more sense of it, it causes some problems:

• Moving content around will break the navigation and force us to maintain a redirect service to make sure links continue working
• It is also challenging to create links from the old docs to the new one to drive more traffic

The folder structure is relatively simple:

• API --> All the information about Electron's APIs
• Development --> Useful documents for contributing back to Electron, but not very relevant to the average developer of Electron applications
• Tutorial --> Everything else

By keeping the same folder structure and taking advantage of sidebars.js we can take fix the 2 issues above.
We should do this sooner rather than later while there is still little traffic to the new website.

Algolia search sometimes not indexing API modules

Handle when documents are deleted

Currently we are not taking into consideration when a document is deleted as it is still part of the sidebars and the build fails.

Loading the fiddle failed: Not Found

Most of the "Open in Fiddle" buttons open links that result in a "Loading the fiddle failed: Not Found" error in Electron Fiddle.

Here is an example of a link that doesn't work:
https://www.electronjs.org/docs/v14-x-y/tutorial/represented-file

This link works:
https://www.electronjs.org/docs/latest/tutorial/examples

It looks a workaround is to replace v14-x-y with latest in the URL.

Electron Fiddle 0.26.0 (12.0.14)
macOS 11.6 (20G165)

Right sidebar formatting makes really hard to quickly glance for methods

New documentation makes right-sidebar formatting unusable:

1. Unnecessary code style for method names.
2. Arguments added to the list of methods. JS does not support method overloading - this is not needed.
3. They don't fit on small screens.

Suggestins:

• Remove code formatting use default link style.
• Remove method arguments.
• Remove common prefix, e.g. webFrame.setZoomFactor() vs setZoomFactor.
  Here is an example of new doc and old doc:
  

Make `/docs/latest/` point to introduction page

CSS missing

If you visit the new page at https://www.electronjs.org/docs/latest/ the following error appears in the console:

GET https://www.electronjs.org/assets/css/styles.3a521351.css net :: ERR_ABORTED 404 (Not Found)

The page is displayed without CSS.

Add License

Probably for another PR, but I realize that we have no License specified for this project.

Originally posted by @erickzhao in #23 (comment)

De-activate docs only mode

The current site uses docusaurus' docs only mode.
Because we plan on adding sections outside docs (like the blog), we need to disable this feature.

Missing api history

Old version of the docs supported API history by appending /history to the URL.

For example, from /api/desktop-capturer you could do /api/desktop-capturer/history to get the history of changes of that module.

Are there any plans to implement these pages in the new docs?

Apps section

We need to make the content of https://www.electronjs.org/apps available in Docusaurus.

In the current site the pages are generated dynamically based on data stored on a (quite large) JSON file. Instead of generating those pages dynamically we could create a static page for each one, maybe as part of the (pre)build step so we don't have to send MB of JSON over the wire.

algolia search throws uncaught error on beta site

• load https://www.electronjs.org/docs/latest/
• click in the algolia textfield in upper-right corner to give focus
  • modal DocSearch dialog pops up
• type ipcRenderer into the .docsearch_input ('Search docs') input field
  • result: the DocSearch dialog has a spinning activity icon that never ends & gives no results

Network traffic while typing ipcRenderer gives all 404s:

Uncaught (in promise)
{name: "ApiError", message: "Index beta-electronjs does not exist", status: 404, transporterStackTrace: Array(1)}

Review logic to add new docs to sidebars

By default we add to an Api category but there are some scenarios we can do better, for example when the file is under api/structures.

Fiddle embeds: Add ability to change default editor tab

Right now, the Fiddle embed transformer displays the main.js tab by default. However, it might be more relevant to a different editor (for example, renderer.js) depending on where the relevant code lives.

Make colours more contrasting in Dark Mode

Enable blog

The blog needs to be migrated over from the old site to here as well. Docusaurus' has a blog plugin that we should be capable of leveraging.

The biggest problems when @erickzhao was investigating this previously were:

• Some markup not being allowed by Docusaurus (like img or br tags with no /)
• It does not support multiple authors (posts with multiple authors will be "signed" at the end)

Remove highlighting from `Examples` in navbar

At the moment, "Docs" and "Examples" are both highlighted when viewing any page under the "docs" sidebar.

Add styling for API tags

In our markdown documentation, we tag APIs using _emphasis_ (e.g. deprecated, experimental, etc.) On the old website, we transform these elements into tags by adding custom styling. We should do the same here.

Prebuild command clashes with Prettier rules

Our prettier rules specify single-quotes, but running yarn prebuild will turn the JSON in sidebars.js into full double-quotes.

Internationalization

This is an outline of how we could handle the internationalization if the website based on our current experience in the main site and Docusaurus documentation.

Some considerations

• Each language is in its own folder under i18n/. In our case it will be 7 languages (Chinese Simplified, French, German, Japanese, Portuguese, Russian, and Spanish)
• We will have to add a code.json and navbar.json to each locale for translation so the navigation and other strings are translated.
• We might need to use explicit ids in headings to make sure relative links still work (not sure what the current status is)
• There is no automatic locale detection (its an static site). We could use some JavaScript or show the English site first and let the users pick their preferred one via the localeDropdown

How to?

I think the less disruptive way would be to:

• The English language keeps being updated as it is right now
• Make i18n pull the required files for translations (e.g.: navbar.json) electron/i18n#1982
• Pull the translations from crowding using the CLI periodically and move the files to the right place (at least until the changes happen upstream)
• Move /scripts/tasks/how-to-examples.md upstream. It will get translated but will not show up in the old docs so we should be OK.

The reason to use the Crowdin CLI instead of the i18n package is that this package is a massive JSON blob and only contains the HTML. We want the files and in the future we would like to stop maintaining it.

Community section

We need to make the content of https://www.electronjs.org/community available in Docusaurus.

It's a static page with no dynamic content. No need to match the style.

[☂] v1 tasks

Some tasks from the top of my head:

Pending:

• Figure out i18n integration (#64)
• Figure out docs versioning
• Review and update documentation style guide to match new website.
• Create new docs landing page (@molant, @erickzhao)
• Upstream everything we can to electron/electron
• Update styles to match a bit more the current live site (@erickzhao)
• Need to find a way to allow easy merges on electron/electron for the /docs folder ➡ Maybe use the CODEOWNERS plugin or similar?

Done:

• Add frontmatter to documentation, should be in electron/electron but maybe we can start doing it here (see #electron/electron#28303)? (@molant) (#3)
• Pull documentation from the right branch as pre-build step (@molant) (#3)
• Automatically generate the sidebar ➡ Haven't found any documentation about it or if it is enough with the right folder structure Looks like we need to generate it somehow or else docusaurus complains with: (@molant) (#3)

  Error: Bad sidebars file.
  These sidebar document ids do not exist:

• Add Fiddle integration in the docs (@erickzhao)
• Remove Blog link for now (#10)
• Deploy the website somewhere (@molant) ➡️ https://beta.electronjs.org/
• Reach out to docsearch see if we can have 2 indexes for the website (@molant) (#22) ➡ *Waiting for next crawl before merging
• Figure out how to enable fast docs development locally (@molant) (#4)
• List of examples sooner rather than later
• Automatically update/deploy periodically or when there's new content in electron/electron (#19 - @molant)
• Add an "Examples" link to the top nav ➡ Talk about fiddle in the landing page (@molant)
• search feature
• Update electronjs.org-new README
• Document and be clear about acceptance criteria for submissions.
• START HERE URL
• Discord Channel #TBD

Expand `api/structure` descriptions in `/api` docs

Governance section

We need to make the content of https://www.electronjs.org/governance available in Docusaurus.

It's a static page with no dynamic content. No need to match the style.

Additional palm sign ($) throwing error during installation.

I used the COPY BUTTON in code section to copy the installation command, it copied
$ npm install --save-dev electron

since the terminal already have the palm sign ($) so it is throwing error that $ is not a command it would be better if it the copied text excludes the sign.

thank you.

Organize footer content

add tooltips for common terms

I came across this: https://www.youtube.com/watch?v=LbC4WZoyinI&t=5s which adds common terms in little tooltips using docusaurus and mdx. Code is here, would be cool to add to our docs!

Add banner to old Electron website

Homepage

We need to make the content of https://www.electronjs.org/ available in Docusaurus.

We should take this opportunity to rethink what we want to say in the homepage as it is not clear what the CTAs are for the user.

Figure out how to enable fast docs development locally

One of the problems with the current way we have docs is that it's really complicated to see how any changes to the documentation look like in the website:

1. Docs are in electron/electron
2. The contents of electron/i18n get updated periodically and pushed to crowdin
3. When new translations are available, a new package electron-i18n is published
4. The website electron/electronjs.org then picks that the package has been updated and when the change is merged it gets finally deployed

While we still want the documentation to live in electron/electron, we want contributors to have an easy way to see how the docs would look like in the website.

Ref #2

Support multi-author blog posts

Following #92, blogs now support the multi-author format. We should either:

• Do pre-processing to transform the GitHub username format from the old website into one that the Docusaurus plugin accepts.
• Swizzle blog theme components so that the frontmatter automatically accepts our current format. (Note: swizzling during the beta phase is discouraged according to the docs because breaking changes might happen).

Match inline code color scheme to old website

See http://web.archive.org/web/20210401163700/https://www.electronjs.org/docs/api/app

broken image links in new docs

https://www.electronjs.org/docs/latest/tutorial/performance/#how has broken image links to "../images/performance-heap-prof.png" and "../images/performance-cpu-prof.png"

Some other image links do work, e.g. in https://www.electronjs.org/docs/latest/tutorial/electron-versioning/#version-1x

Add 404 page

Transform platform notices in API docs into badges

In https://github.com/electron/electronjs.org, we parse through the raw API docs to add badges to the headings. These badges add a bit of extra info about each API (platform, deprecation, and experimental status).

https://github.com/electron/electronjs.org/blob/224c921864f99179944b4bf11f57d242462a2972/scripts/docs-api-labels.js#L26-L48

These should also be added to the new website. Probably during the site generation step by manually using the Infima badge styles: https://infima.dev/docs/components/badge/

Doesn't switch by default to dark mode according to System theme

Describe the Bug

The electronjs.org website doesn't automatically open in Dark mode if my system is in Dark Mode when opening the website for the first time.
But the website does switch to dark mode if my system changes to dark mode while the website is open though which is the right behaviour.

A Demo

The following demo uses Incognito windows to simulate first-time visit behaviour.

electron.mp4

Possible Solution

I went through the Docusaurus documentation and saw that adding a parameter respectPrefersColorScheme: true made the website appear by default in Dark mode

Reference: https://docusaurus.io/docs/api/themes/configuration

Properly escape tags in documentation

Docusuarus has some problems when there's content like:

The tag

This does not happen if it is in a code block. Another alternative is to "escape" it like this:

The tag

But that /> renders and it does not look OK.

Need to find a way to solve this.

---

You can see them, need to figure out how to do this properly but might take a bit of time.
OK if I file a separate issue and address later?

Originally posted by @molant in #3 (comment)

Sidebar creation should append new content instead of recreating from scratch

The current approach to create sidebars.js is to create it from scratch every time prebuild is called.
While this has the benefit of making sure all the new content gets added, the problem is that it is very difficult to get the right order for the articles programmatically.

After talking with @erickzhao, the approach we've decided is to:

• Manually organize the content of sidebars.js
• Automatically add any new content at the end of the right category if they are not already in sidebars.js
• Run the sidebars.js generation before deploy

This will avoid edge cases where there might be a gap between approving a PR, merging it in main, and new content added to electron/electron in the meantime.

Upgrade to Docusaurus v2.0.0-beta

Ref https://docusaurus.io/blog/2021/05/12/announcing-docusaurus-two-beta

Docs don't get updated when there is a new major version

It looks like we are not receiving the payload as v14 was released yesterday and the latest notification is from 5 days ago:

Need to figure out if electron-updater is not getting the right payload or it is not sending it.

Automatically update/deploy periodically or when there're doc changes upstream

Problem

We need a way to automatically ingest changes in the documentation into the website.
There are 2 scenarios @erickzhao and I have identified:

• New documentation: A new PR should be opened with sidebars.js reflecting the new file. Human intervention is expected to approve the PR and/or update the file to the right locations. Alternatively, we could add default categories and improve the logic to move files around to automate this even more and auto-merge.
• Changes to existing docs: There are no real changes in the code of the repo but a new deployment should be triggered.

Proposed solution

The idea is to add a push webhook event from electron/electron to a new endpoint. This endpoint will check if:

• The changes are in the stable branch
• Modify the /docs folder

If so, it will trigger a respository_dispatch event with the type doc_changes and the SHA of the commit as part of the payload.

The GitHub action will do the following for the doc_changes type:

1. Update the SHA to the new one (we will store it in package.json)
2. Run npm run build
3. Creates a commit chore: update ref to docs (🤖)
4. Checks if there are changes in the markdown:
   • No changes (just package.json is modified) ➡ Pushes the commit directly to main
   • More changes (i.e.: sidebars.js is modified as well) ➡ Pushes the commit to the branch chore/docs-updates (it gets created if it does not exist). Then checks if there is an open PR for that branch and if not it creates it. Human intervention is expected to merge this PR

The following diagram should help better visualize the above:

Questions?

How to force a deploy in Heroku?

Because we are changing the SHA in package.json there is no need to force a deploy, it will be automatically kicked by Heroku.

What happens when there's a new major release?

We could configure the webhook to receive also the release event. The fields to validate are:

{
  "action": "published",
  "release": {
    "draft": false
    },
    "prerelease": false
  }
}

And release.tag_name should be >= than the current available version on npm (there could be a 30second-2min delay between GitHub and npm releases). The reason is that there could be a minor release from a previous version.
Because the fiddle prebuilt steps requires the latest version available we should probably wait until it is available (and add a timeout of a few minutes).
Another problem is that the payload of release does not seem to have the commit SHA (at least in the example) so we will need a way to find it.

Migration TODO

Content

• Change Docusaurus website to use /docs/latest/ base URL
• Add Electron logo
• All other non-critical issues should be noted in the tracker
• Banner for electronjs.org to redirect
• Banner for electronjs.org-new to go back

Things to keep in mind

• How many people are going there?
• Once they’re there: are they staying there or going back?
• Re-run NPS survey on both beta.electronjs.org and electronjs.org

Not enough contrast in code blocks inside warning admonition

Dark mode:

Light mode (need to double check the numbers):

Also need to see if it's a problem in our color palette or upstream.

cc @erickzhao

Show more levels in the documentation page table of contents

I couldn't find a feedback link on the new docs...

The table of contents links in the new docs leave much to be desired. A quick comparison:

Old docs:

New docs:

As you can see, the new docs omit all the actual events, properties, and methods. There is no way to see what is available without scrolling through pages and pages of content. And since the headings and content run together, it is quite hard to scan the page and determine what is available.

Nested lists not properly shown on new docs site

e.g. https://www.electronjs.org/docs/latest/api/dialog/#dialogshowopendialogsyncbrowserwindow-options, the 'properties' list should be nested an extra level deep.

Releases section

We need to make the content of https://www.electronjs.org/releases/stable available in Docusaurus.

Some things to consider:

• I don't think URLs need to match (contrary to blog). They are not predictable at the moment because of pagination (one day the release x.y.z could be in page 1, the day after in page 2
• We should make it possible to link to each release individually
• There is also https://releases.electronjs.org, we should only have 1 place for releases and redirect to the right place where needed

Create documentation generator

To make it easier to create a new guide/document, we should have a generator that anyone can called like this:

npm create electron-document|guide|something name-of-the-doc

The idea is to invoke this script in e/e docs folder and it will automatically generate:

• A markdown file with the right frontmatter (it can pick the author, title, slug, category, etc.)
• Placeholders for the different common sections
• New files under docs/fiddle linked from markdown

If the user invokes this script under docs/how-to as npm create electron-doc the-title, it would create something similar to the following structure:

└── electron/electron
           ├─ docs
           |   ├─ fiddles
           |   |    ├─ the-title
           |   |    |     ├─ index.html
           |   |    |     ├─ main.js
           |   |    |     ├─ renderer.js
           |   |    |     └─ styles.css
           |   |    └─ ...
           |   |
           |   └─ how-to
           |       ├─ the-title.md
           |       └─ ...
           └─ ...

And the contents of the-title.md would be:

---
title: The Title
description: This is the title document
slug: the-title
hide_title: true
---

# The Title

## Overview

<!-- ✍ Overview of the document here -->

### Examples

<!-- ✍ Explanation of the code below -->

```fiddle docs/fiddles/features/the-title

some code here

(NOTE: can't figure out how to close the fiddle example codeblock above)

While this could be in a different repo, it probably makes sense to create it in this one to make sure they are close and gets updated easily if needed.

Versioned docs

The website only shows the latest stable documentation, but the reality is that developers are not always using the latest and brightest version. While it is possible to go to electron/electron and find the docs for a particular branch, we could make the process easier.

Docusaurus allows you to have versioned docs. That said, the process doesn't really fit our needs:

• We have to keep old doc versions in our repo and this will increase the build time and probably crash things as it happened with the localization
• I'm not even sure how that will work with localized content
• Even though it should be possible to change the version from Next to something else, I was not capable. Maybe it was because I only had one version
• We do want to "build and forget", meaning that the website should be a snapshot of whatever it was

My proposal is to leverage the fact we are using a storage solution now to publish the website and:

• Add a new dropdown item to docusaurus.config.js with the versions we want developers to have quick access. Even if we publish more versions and are available, I think we should only list the supported ones here.
• When there is a major release, before switching we build the latest one again (localized content and everything) but instead of publishing to latest we publish to vXX. This might require us to change docusaurus.config.js and sidebars.js.
• Publish to the storage
• Update docusaurus.config.js dropdown with the new version pointing to https://www.electronjs.org/vXX
• Continue the regular docs process

Questions

How do we handle minor release doc updates (e.g. 14.0.1 to 14.1.0) for a version that is not the latest one?

We could generate a build each time, publish under vX.Y.Z. In docusaurus.config.js we only list the latest version of each major so the list is not too long, but the content will still be available.

The biggest problem is with the localized content. Crowdin only handles the latest stable content and not all content is translated. On top of that, we do not keep the translations in this repo...

A few options (from most complicated to less complicated) to handle this scenario:

1. We start doing versioning on Crowdin. Not very straightforward. Also, the translations take some time so we will have also to find a way to get changes to previous versions and publish those as well and thus complicating the whole process
2. Use the latest version in Crowdin. While it should be mostly OK (at least when there are bumps in minors), there could be breaking changes in the APIs and thus report stuff that is not accurate).
3. We only build the EN locale for previous versions

My vote is with the last option, and if developers really demand versioned docs for previous versions, then we look at implement it (start small).

Revamp get started tutorial

A consistent feedback we have received from multiple places is that developers have a hard time finding information on our docs. Sometimes it is becacuse that documentation does not exist, others because it is not easily discoverable (how to search for what you don't know?).

The following is a WIP outline of the Quick start guide, so feedback is welcome:

• Introduction
  • Web concepts
  • nodejs installed
  • Process model
• Scaffolding
  • Debugging with VS Code --> Maybe add the configuration to the quick-start?
• Accessing Node.js APIs--> Talk about Context isolation and prerenderer and how to implement things.
  • Link again to process model or mention things?
  • Use process.versions as an example on how to implement, mention that node integration is to be avoided
  • Link to the security docs (Context isolation, Process sandboxing, Checklist)
• Deeper integration with the OS
  • Have a list of all the other stuff --> Manually for now, but will be good to get something populated automatically that uses the description and other stuff
• Application distribution
  • Link to all the other links under distribution (Code signing, Mac App Store Submission Guide, Windows Store Guide, Snapcraft Guide (Linux)
• Updating Applications
• Further reading: Go to Examples and look at the API, performance, fuses, etc.?

Add reviewers when a PR gets created

We should add reviewers automatically when a PR is created to make sure we don't miss the notifications.
#37 was opened yesterday and we just realized now it was opened (and were wondering why the website wasn't up to date).