GITBOOK-188: Standardize documentation for Makers

SUMMARY.md

@@ -29,7 +29,7 @@
   * [Snapcraft](config/makers/snapcraft.md)
   * [Squirrel.Windows](config/makers/squirrel.windows.md)
   * [WiX MSI](config/makers/wix-msi.md)
-  * [Zip](config/makers/zip.md)
+  * [ZIP](config/makers/zip.md)
 * [Publishers](config/publishers/README.md)
   * [Bitbucket](config/publishers/bitbucket.md)
   * [Electron Release Server](config/publishers/electron-release-server.md)

config/makers/appx.md

@@ -1,25 +1,46 @@
 ---
 description: >-
-  Create a package for the Windows Store for your Electron app, using Electron
+  Create a package for the Microsoft Store for your Electron app, using Electron
   Forge.
 ---
 
 # AppX
 
-The AppX target builds `.appx` packages which are designed to target the Windows Store.  You can only build the AppX target on Windows machines with the Windows 10 SDK installed.  Check the [`electron-windows-store` docs](https://github.com/felixrieseberg/electron-windows-store#readme) for more information on platform requirements.
+The AppX target builds `.appx` packages which are designed to target the [Microsoft Store](https://apps.microsoft.com/home).
 
-Configuration options are documented in [`MakerAppXConfig`](https://js.electronforge.io/interfaces/_electron_forge_maker_appx.MakerAppXConfig.html).
+### Requirements
+
+You can only build the AppX target on Windows 10 or 11 machines with the [Windows SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/) installed. Check the [`electron-windows-store` docs](https://github.com/electron-userland/electron-windows-store) for more information on platform requirements.
+
+### Installation
+
+```bash
+npm install --save-dev @electron-forge/maker-appx
+```
 
 ### Usage
 
+To use `@electron-forge/maker-appx`, add it to the `makers` array in your [Forge configuration](../configuration.md):
+
+{% code title="forge.config.js" %}
 ```javascript
-{
-  name: '@electron-forge/maker-appx',
-  config: {
-    publisher: 'CN=developmentca',
-    devCert: 'C:\\devcert.pfx',
-    certPass: 'abcd'
-  }
+module.exports = {
+  makers: [
+    {
+      name: '@electron-forge/maker-appx',
+      config: {
+        publisher: 'CN=developmentca',
+        devCert: 'C:\\devcert.pfx',
+        certPass: 'abcd'
+      }
+    }
+  ]
 }
 ```
+{% endcode %}
+
+Configuration options are documented in [`MakerAppXConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_maker\_appx.MakerAppXConfig.html).
+
+### Debugging
 
+For advanced debug logging for this maker, add the `DEBUG=electron-windows-store*` environment variable.

config/makers/deb.md

@@ -6,21 +6,42 @@ description: >-
 
 # deb
 
-The deb target builds [`.deb` packages](https://en.wikipedia.org/wiki/Deb_%28file_format%29), which are the standard package format for Debian-based Linux distributions such as Ubuntu.  You can only build the deb target on Linux or macOS machines with the `fakeroot` and `dpkg` packages installed.
+The deb target builds [`.deb` packages](https://www.debian.org/doc/manuals/debian-faq/pkg-basics.en.html), which are the standard package format for Debian-based Linux distributions such as [Ubuntu](https://ubuntu.com/).
 
-Configuration options are documented in [`MakerDebConfig`](https://js.electronforge.io/interfaces/_electron_forge_maker_deb.MakerDebConfig.html).
+### Requirements
+
+You can only build the deb target on Linux or macOS machines with the [`fakeroot`](https://wiki.debian.org/FakeRoot) and [`dpkg`](https://wiki.debian.org/dpkg) packages installed.
+
+### Installation
+
+```bash
+npm install --save-dev @electron-forge/maker-deb
+```
 
 ### Usage
 
+To use `@electron-forge/maker-deb`, add it to the `makers` array in your [Forge configuration](../configuration.md):
+
+{% code title="forge.config.js" %}
 ```javascript
-{
-  name: '@electron-forge/maker-deb',
-  config: {
-    options: {
-      maintainer: 'Joe Bloggs',
-      homepage: 'https://example.com'
+module.exports = {
+  makers: [
+    {
+      name: '@electron-forge/maker-deb',
+      config: {
+        options: {
+          maintainer: 'Joe Bloggs',
+          homepage: 'https://example.com'
+        }
+      }
     }
-  }
+  ]
 }
 ```
+{% endcode %}
+
+Configuration options are documented in [`MakerDebConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_maker\_deb.MakerDebConfig.html).
+
+### Debugging
 
+For advanced debug logging for this maker, add the `DEBUG=electron-installer-deb*` environment variable.

config/makers/dmg.md

@@ -4,25 +4,40 @@ description: Generate a DMG with Electron Forge to distribute your Electron app
 
 # DMG
 
-The DMG target builds `.dmg` files, which are the standard format for sharing macOS apps.  The DMG acts like a zip file, but provides an easy way for users to take the app and put it in the `/Applications` directory.
+The DMG target builds Apple Disk Image (`.dmg`) files, which are the standard format for sharing macOS apps. The DMG acts like a ZIP file, but provides an easy way for users to take the app and put it in the `/Applications` directory.
+
+### Requirements
 
-{% hint style="warning" %}
 You can only build the DMG target on macOS machines.
-{% endhint %}
 
-Configuration options are documented in [`MakerDMGConfig`](https://js.electronforge.io/interfaces/_electron_forge_maker_dmg.MakerDMGConfig.html).
+### Installation
+
+```sh
+npm install --save-dev @electron-forge/maker-dmg
+```
 
 ### Usage
 
+To use `@electron-forge/maker-dmg`, add it to the `makers` array in your [Forge configuration](../configuration.md):
+
+{% code title="forge.config.js" %}
 ```javascript
-{
-  name: '@electron-forge/maker-dmg',
-  config: {
-    background: './assets/dmg-background.png',
-    format: 'ULFO'
-  }
+module.exports = {
+  makers: [
+    {
+      name: '@electron-forge/maker-dmg',
+      config: {
+        background: './assets/dmg-background.png',
+        format: 'ULFO'
+      }
+    }
+  ]
 }
 ```
+{% endcode %}
 
+Configuration options are documented in [`MakerDMGConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_maker\_dmg.MakerDMGConfig.html).
 
+### Debugging
 
+For advanced debug logging for this maker, add the `DEBUG=electron-installer-dmg*` environment variable.

config/makers/flatpak.md

@@ -4,23 +4,40 @@ description: Create a Flatpak app for your Electron app using Electron Forge.
 
 # Flatpak
 
-The Flatpak target builds [`.flatpak` files](http://flatpak.org/), which is a packaging format for Linux distributions that allows for sandboxed installation of applications in isolation from the rest of their system. In contrast, typical deb or RPM installation methods are not sandboxed.
+The Flatpak target builds [`.flatpak` files](http://flatpak.org/), which is a packaging format for Linux distributions that allows for sandboxed installation of applications in isolation from the rest of their system. In contrast, typical [deb.md](deb.md "mention") or [rpm.md](rpm.md "mention") installation methods are not sandboxed.
 
-You can only build the Flatpak target if you have `flatpak`, `flatpak-builder`, and `eu-strip` _\(usually part of the `elfutils` package\)_ installed on your system.
+### Requirements
 
-Configuration options are documented in [`MakerFlatpakConfig`](https://js.electronforge.io/classes/_electron_forge_maker_flatpak.MakerFlatpak-1.html#config).
+You can only build the Flatpak target if you have [`flatpak`](https://docs.flatpak.org/en/latest/flatpak-command-reference.html#flatpak), [`flatpak-builder`](https://docs.flatpak.org/en/latest/flatpak-builder-command-reference.html#flatpak-builder), and `eu-strip` _(usually part of the_ [_`elfutils`_](https://sourceware.org/elfutils/) _package)_ installed on your system.
+
+### Installation
+
+```sh
+npm install --save-dev @electron-forge/maker-flatpak
+```
 
 ### Usage
 
+To use `@electron-forge/maker-flatpak`, add it to the `makers` array in your [Forge configuration](../configuration.md):
+
 ```javascript
-{
-  name: '@electron-forge/maker-flatpak',
-  config: {
-    options: {
-      categories: ['Video'],
-      mimeType: ['video/h264']
+module.exports = {
+  makers: [
+    {
+      name: '@electron-forge/maker-flatpak',
+      config: {
+        options: {
+          categories: ['Video'],
+          mimeType: ['video/h264']
+        }
+      }
     }
-  }
+  ]
 }
 ```
 
+Configuration options are documented in [`MakerFlatpakConfig`](https://js.electronforge.io/classes/\_electron\_forge\_maker\_flatpak.MakerFlatpak-1.html#config).
+
+### Debugging
+
+For advanced debug logging for this maker, add the `DEBUG=electron-installer-flatpak*` environment variable.

config/makers/pkg.md

@@ -15,30 +15,39 @@ The flat installer package format is sparsely documented by Apple. If you want t
 * [Flat Package Format - The missing documentation](http://s.sudre.free.fr/Stuff/Ivanhoe/FLAT.html) (Stéphane Sudre)
 * [The Flat Package - Examining a newer package format](https://preserve.mactech.com/articles/mactech/Vol.26/26.02/TheFlatPackage/index.html) (MacTech)
 
-## Usage
+### Requirements
 
-{% hint style="warning" %}
 You can only build the pkg target on macOS machines while targeting the `darwin` or `mas` platforms.
-{% endhint %}
 
-To use `@electron-forge/maker-pkg`, add it to the `makers` array in your Forge configuration.
+### Installation
 
-<pre class="language-javascript" data-title="forge.config.js"><code class="lang-javascript">module.exports = {
+```bash
+npm install --save-dev @electron-forge/maker-pkg
+```
+
+### Usage
+
+To use `@electron-forge/maker-pkg`, add it to the `makers` array in your [Forge configuration](../configuration.md):
+
+{% code title="forge.config.js" %}
+```javascript
+module.exports = {
   makers: [
-<strong>    {
-</strong><strong>      name: '@electron-forge/maker-pkg',
-</strong><strong>      config: {
-</strong><strong>        keychain: 'my-secret-ci-keychain'
-</strong><strong>        // other configuration options
-</strong><strong>      }
-</strong><strong>    }
-</strong>  ]
+    {
+      name: '@electron-forge/maker-pkg',
+      config: {
+        keychain: 'my-secret-ci-keychain'
+        // other configuration options
+      }
+    }
+  ]
 };
-</code></pre>
+```
+{% endcode %}
 
 All configuration options are optional, and options are documented in the API docs for [`MakerPkgConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_maker\_pkg.MakerPKGConfig.html).
 
-### Installation scripts
+### Adding installation scripts
 
 With the pkg maker, you can add either a `preinstall` or `postinstall` bash script that runs before and after your app is installed, respectively.
 
@@ -75,8 +84,8 @@ module.exports = {
 
 </code></pre>
 
-## Debugging
+### Debugging
 
 All logs for your flat package installer can be found in macOS installation logs, which are stored in `/var/log/install.log`. They are also accessible within the [Console.app](https://support.apple.com/en-ca/guide/console/welcome/mac) utility.
 
-For advanced debug logging for this maker, add the `DEBUG=electron-osx-sign` environment variable.
+For advanced debug logging for this maker, add the `DEBUG=electron-osx-sign*` environment variable.

config/makers/rpm.md

@@ -6,9 +6,9 @@ description: >-
 
 # RPM
 
-The RPM target builds `.rpm` files, which is the standard package format for Red Hat-based Linux distributions such as Fedora and Red Hat Enterprise Linux (RHEL).
+The RPM target builds `.rpm` files, which is the standard package format for Red Hat-based Linux distributions such as [Fedora](https://fedoraproject.org/) and [Red Hat Enterprise Linux](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux) (RHEL).
 
-## Requirements
+### Requirements
 
 You can only build the RPM target on Linux machines with the `rpm` or `rpm-build` packages installed.
 
@@ -24,17 +24,35 @@ While on Debian or Ubuntu you'll need to do this:
 sudo apt-get install rpm
 ```
 
-## Usage
+### Installation
 
-Configuration options are documented in [`MakerRpmConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_maker\_rpm.MakerRpmConfig.html).
+```shell
+npm install --save-dev @electron-forge/maker-rpm
+```
+
+### Usage
+
+To use `@electron-forge/maker-rpm`, add it to the `makers` array in your [Forge configuration](../configuration.md):
 
+{% code title="forge.config.js" %}
 ```javascript
-{
-  name: '@electron-forge/maker-rpm',
-  config: {
-    options: {
-      homepage: 'http://example.com'
+module.exports = {
+  makers: [
+    {
+      name: '@electron-forge/maker-rpm',
+      config: {
+        options: {
+          homepage: 'http://example.com'
+        }
+      }
     }
-  }
+  ]
 }
 ```
+{% endcode %}
+
+Configuration options are documented in [`MakerRpmConfig`](https://js.electronforge.io/interfaces/\_electron\_forge\_maker\_rpm.MakerRpmConfig.html).
+
+### Debugging
+
+For advanced debug logging for this maker, add the `DEBUG=electron-installer-redhat*` environment variable.

config/makers/snapcraft.md

@@ -4,25 +4,44 @@ description: Create a Snap package for your Electron app using Electron Forge.
 
 # Snapcraft
 
-The Snapcraft target builds `.snap` files, which is the packaging format created and sponsored by Canonical, the company behind Ubuntu. It is a sandboxed package format that lets users of various Linux distributions install your application in an isolated environment on their machine.
+The [Snapcraft](https://snapcraft.io/) target builds `.snap` files, which is the packaging format created and sponsored by Canonical, the company behind Ubuntu. It is a sandboxed package format that lets users of various Linux distributions install your application in an isolated environment on their machine.
+
+### Requirements
 
 You can only build the Snapcraft target on Linux systems with the [`snapcraft`](https://snapcraft.io/) package installed.
 
-Configuration options are documented in [`MakerSnapConfig`](https://js.electronforge.io/modules/_electron_forge_maker_snap.html#MakerSnapConfig).
+### Installation
+
+```bash
+npm install --save-dev @electron-forge/maker-snap
+```
+
+### Usage
 
-## Usage
+To use `@electron-forge/maker-snap`, add it to the `makers` array in your [Forge configuration](../configuration.md):
 
+{% code title="forge.config.js" %}
 ```javascript
-{
-  name: '@electron-forge/maker-snap',
-  config: {
-    features: {
-      audio: true,
-      mpris: 'com.example.mpris',
-      webgl: true
-    },
-    summary: 'Pretty Awesome'
-  }
+module.exports = {
+  makers: [
+    {
+      name: '@electron-forge/maker-snap',
+      config: {
+        features: {
+          audio: true,
+          mpris: 'com.example.mpris',
+          webgl: true
+        },
+        summary: 'Pretty Awesome'
+      }
+    }
+  ]
 }
 ```
+{% endcode %}
+
+Configuration options are documented in [`MakerSnapConfig`](https://js.electronforge.io/modules/\_electron\_forge\_maker\_snap.html#MakerSnapConfig).
+
+### Debugging
 
+For advanced debug logging for this maker, add the `DEBUG=electron-installer-snap*` environment variable.