GITBOOK-186: Disambiguate

config/configuration.md

@@ -91,44 +91,115 @@ module.exports = {
 {% endtabs %}
 
 {% hint style="success" %}
-All properties are optional
+All properties in your Forge configuration are optional. Initializing your project with one of the [Broken link](broken-reference "mention") will initialize some standard defaults.
 {% endhint %}
 
 ### Electron Packager config
 
-The top level property `packagerConfig` on the configuration object maps directly to the options sent to [`electron-packager`](https://github.com/electron/electron-packager) during the package step of Electron Forge's build process.
+The top level property `packagerConfig` on the configuration object maps directly to the options sent to [`@electron/packager`](https://github.com/electron/packager) during the [#package](../cli.md#package "mention") step of Electron Forge's build process
+
+This configuration allows you customize how `@electron/packager` bundles your Electron-based application source code into a packaged application ready for distribution.
+
+{% code title="forge.config.js" %}
+```javascript
+module.exports = {
+  packagerConfig: {
+    name: 'My Electron App',
+    asar: true,
+    osxSign: {},
+    appCategoryType: 'public.app-category.developer-tools'
+  }
+};
+```
+{% endcode %}
 
 The options you can put in this object are documented in the [Electron Packager API docs](https://electron.github.io/packager/main/interfaces/Options.html).
 
-{% hint style="warning" %}
-You can not override the `dir`, `arch`, `platform, out` or `electronVersion` options as they are set by Electron Forge internally.
+{% hint style="info" %}
+You can not override the `dir`, `arch`, `platform`, `out` or `electronVersion` options as they are set by Electron Forge internally.
+
+If you want to specify a platform/architecture combination for any build command (Package, Make, or Publish), you can specify `--arch` and `--platform` flags using the Forge CLI (e.g. `npm run make --arch=arm64`).
+
+See the [#build-commands](../cli.md#build-commands "mention") documentation for more details.
 {% endhint %}
 
 ### Electron Rebuild config
 
-The top level property `rebuildConfig` on the configuration object maps directly to the options sent to [`electron-rebuild`](https://github.com/electron/electron-rebuild) during both the package and start step of Electron Forge's build process.
+The top level property `rebuildConfig` on the configuration object maps directly to the options sent to [`@electron/rebuild`](https://github.com/electron/rebuild) during both the [#package](../cli.md#package "mention") and [#start](../cli.md#start "mention") commands in Electron Forge.
+
+This configuration allows you to customize how Electron Forge rebuilds your project's [native Node.js modules](https://www.electronjs.org/docs/latest/tutorial/using-native-node-modules) against the Node.js version bundled in your app's Electron version.
+
+{% code title="forge.config.js" %}
+```javascript
+module.exports = {
+  rebuildConfig: {
+    force: true
+  }
+};
+```
+{% endcode %}
 
 The options you can put in this object are documented in the [Electron Rebuild API docs](https://github.com/electron/electron-rebuild#how-can-i-integrate-this-into-grunt--gulp--whatever).
 
-{% hint style="warning" %}
-You can not override the `buildPath`, `arch`, or `electronVersion` options as they are set by Electron Forge internally
+{% hint style="info" %}
+The required `buildPath` and `electronVersion` options for `@electron/rebuild` are preconfigured by Forge. The optional `arch` option will also be overridden by Forge internally.
 {% endhint %}
 
 ### Makers
 
-The top level property `makers` on the configuration object is an array of maker configurations. Check out the [Makers](makers/) documentation for all possible makers and their config options.
+The top-level `makers`  property on the configuration object is an array of maker configurations. Each maker will generate a distributable artifact for your packaged application in the [#make](../cli.md#make "mention") step (e.g. [squirrel.windows.md](makers/squirrel.windows.md "mention") on Windows or [dmg.md](makers/dmg.md "mention") on macOS).
+
+Check out the [makers](makers/ "mention") documentation for all official makers and their config options, and the[writing-makers.md](../advanced/extending-electron-forge/writing-makers.md "mention") guide for implementing your own Make step build targets.
+
+{% code title="forge.config.js" %}
+```javascript
+module.exports = {
+  makers: [
+    {
+      name: "@electron-forge/maker-zip",
+      platforms: ["darwin"]
+    }
+  ]
+};
+```
+{% endcode %}
 
 ### Publishers
 
-The top level property `publishers` on the configuration object is an array of publisher configurations. Check out the [Publishers](publishers/) documentation for all possible publishers and their config options.
+The top level property `publishers` on the configuration object is an array of publisher configurations. Each publisher provides a publish target for your distributable (e.g. [github.md](publishers/github.md "mention") or [s3.md](publishers/s3.md "mention")).
+
+Check out the [publishers](publishers/ "mention") documentation for all official publishers and their config options, and the [writing-publishers.md](../advanced/extending-electron-forge/writing-publishers.md "mention") guide for implementing your own custom Publish targets.
+
+{% code title="forge.config.js" %}
+```javascript
+module.exports = {
+  publishers: [
+    {
+      name: '@electron-forge/publisher-github',
+      config: {
+        repository: {
+          owner: 'electron',
+          name: 'fiddle'
+        },
+        draft: true,
+        prerelease: false,
+        generateReleaseNotes: true
+      }
+    }
+  ]
+};
+```
+{% endcode %}
 
 ### Plugins
 
-The top level property `plugins` on the configuration object is an array of plugin configurations. Check out the [Plugins](plugins/) documentation for all possible plugins and their config options.
+The top level property `plugins` on the configuration object is an array of plugin configurations. Electron Forge plugins can hook into any point in its lifecycle and provide additional functionality (e.g. the [webpack.md](plugins/webpack.md "mention") will integrate webpack bundling into the build lifecycle, and the [electronegativity.md](plugins/electronegativity.md "mention") will identify security anti-patterns in your app).
+
+Check out the [plugins](plugins/ "mention") documentation for all possible plugins and their config options, and the [writing-plugins.md](../advanced/extending-electron-forge/writing-plugins.md "mention") guide for implementing your own custom Forge plugins.
 
 ### Hooks
 
-The top level property `hooks` on the configuration object is an object containing hooks that can be used to insert custom logic during the build lifecycle.
+The top level property `hooks` on the configuration object is an object containing hooks that can be used to insert custom logic during the [build-lifecycle.md](../core-concepts/build-lifecycle.md "mention").
 
 Check out the [hooks.md](hooks.md "mention") documentation for all possible hooks and their config options.
 
@@ -149,4 +220,4 @@ module.exports = {
 ```
 {% endcode %}
 
-In this example the `appBundleId` option passed to Electron Packager will be selected based on the `buildIdentifer` based on whether you are building for `prod` or `beta`. This allows you to make shared configs incredibly easily as only the values that change need to be wrapped with this function.
+In this example the `appBundleId` option passed to Electron Packager will be selected based on the `buildIdentifier` based on whether you are building for `prod` or `beta`. This allows you to make shared configs incredibly easily as only the values that change need to be wrapped with this function.