add dark mode support

additional mkdocs plugins fix sponsor images add changeset update docs with embedded interfaces update schema with proper markdown file links update snapshot
electron-userland · Sep 17, 2024 · 83f90dd · 83f90dd
1 parent d2ea966
commit 83f90dd
Show file tree

Hide file tree

Showing 20 changed files with 128 additions and 128 deletions.
diff --git a/.changeset/red-beers-press.md b/.changeset/red-beers-press.md
@@ -0,0 +1,16 @@
+---
+"app-builder-lib": patch
+"builder-util": patch
+"builder-util-runtime": patch
+"dmg-builder": patch
+"electron-builder": patch
+"electron-builder-squirrel-windows": patch
+"electron-forge-maker-appimage": patch
+"electron-forge-maker-nsis": patch
+"electron-forge-maker-nsis-web": patch
+"electron-forge-maker-snap": patch
+"electron-publish": patch
+"electron-updater": patch
+---
+
+chore: migrating to typedoc and updating/improving type+interface definitions
diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@ Always looking for community contributions! 👀 Setting up a [dev environment](
       <td>
          <a href="https://workflowy.com">
             <div>
-               <img src="https://workflowy.com/media/i/icon-28x28.png" alt="WorkFlowy" title="WorkFlowy" height="50" align="middle"/>
+               <img src="https://workflowy.com/media/i/icon-28x28.png" alt="WorkFlowy" title="WorkFlowy" style="height: 50px;" height="50"/>
             </div>
             Notes, Tasks, Projects.<br>All in a Single Place.
          </a>
@@ -24,7 +24,7 @@ Always looking for community contributions! 👀 Setting up a [dev environment](
          <br>
          <a href="https://tidepool.org">
             <div>
-               <img src="https://www.electron.build/sponsor-logos/Tidepool_Logo_Light.svg" alt="Tidepool" title="Tidepool" height="75" align="middle"/>
+               <img src="https://www.electron.build/sponsor-logos/Tidepool_Logo_Light.svg" alt="Tidepool" title="Tidepool" style="height: 75px;" height="75" />
             </div>
             Your gateway to understanding your diabetes data
          </a>
@@ -34,7 +34,7 @@ Always looking for community contributions! 👀 Setting up a [dev environment](
          <br>
          <a href="https://keygen.sh/?via=electron-builder">
             <div>
-               <img src="https://keygen.sh/images/logo-pill.png" alt="Keygen" title="Keygen" height="75" align="middle"/>
+               <img src="https://keygen.sh/images/logo-pill.png" alt="Keygen" title="Keygen" style="height: 75px;" height="75" />
             </div>
             An open, source-available software licensing and distribution API
          </a>
@@ -46,7 +46,7 @@ Always looking for community contributions! 👀 Setting up a [dev environment](
          <br>
          <a href="https://www.todesktop.com/electron?utm_source=electron-builder">
             <div>
-               <img src="https://www.todesktop.com/new-logo/todesktop-logo.png" alt="ToDesktop" title="ToDesktop" height="75" align="middle"/>
+               <img src="https://www.todesktop.com/new-logo/todesktop-logo.png" alt="ToDesktop" title="ToDesktop" style="height: 75px;" height="75" />
             </div>
             ToDesktop: An all-in-one platform for building and releasing Electron apps
          </a>
@@ -56,7 +56,7 @@ Always looking for community contributions! 👀 Setting up a [dev environment](
          <br>
          <a href="https://www.dashcam.io/?ref=electron_builder">
             <div>
-               <img src="https://user-images.githubusercontent.com/318295/226675216-ab6aad0c-526c-4a45-a0a8-3906ac614b8b.png" alt="Dashcam" title="Dashcam" height="75" align="middle"/>
+               <img src="https://user-images.githubusercontent.com/318295/226675216-ab6aad0c-526c-4a45-a0a8-3906ac614b8b.png" alt="Dashcam" title="Dashcam" style="height: 75px;" height="75" />
             </div>
             Dashcam: Capture the steps to reproduce any bug with video crash reports for Electron.
          </a>
@@ -91,11 +91,11 @@ See the full documentation on [electron.build](https://www.electron.build).
 * [Proton Native](https://www.electron.build/configuration/configuration/#proton-native) support.
 * Downloads all required tools files on demand automatically (e.g. to code sign windows application, to make AppX), no need to setup.
 
-| Question | Answer |
-|----------|-------|
-| “I want to configure electron-builder” | [See options](https://electron.build/configuration/configuration) |
-| “I found a bug or I have a question” | [Open an issue](https://github.com/electron-userland/electron-builder/issues/new) |
-| “I want to support development” | [Donate](https://www.electron.build/donate) |
+| Question                               | Answer                                                                            |
+| -------------------------------------- | --------------------------------------------------------------------------------- |
+| “I want to configure electron-builder” | [See options](https://electron.build/configuration/configuration)                 |
+| “I found a bug or I have a question”   | [Open an issue](https://github.com/electron-userland/electron-builder/issues/new) |
+| “I want to support development”        | [Donate](https://www.electron.build/donate)                                       |
 
 ## Installation
 [Yarn](http://yarnpkg.com/) is [strongly](https://github.com/electron-userland/electron-builder/issues/1147#issuecomment-276284477) recommended instead of npm.

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -4,14 +4,41 @@ use_directory_urls: false
 extra_css:
   - stylesheets/autowidth.css
 theme:
-  feature:
-    tabs: true
   name: material
-#  logo:
-#    icon: 'build'
+  features:
+    - content.action.edit
+    - content.action.view
+    - content.code.annotate
+    - content.code.copy
+    - content.code.select
+    - content.tooltips
+    - header.autohide
+    - navigation.expand
+    - navigation.sections
+    # - search.highlight
+    # - search.share
+    # - search.suggest
+    - toc.follow
   palette:
-    primary: 'blue'
-    accent: 'blue'
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: blue
+      accent: blue
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/weather-night
+        name: Switch to system preference
+  font:
+    text: Roboto
+    code: Roboto Mono
 
 repo_name: electron-userland/electron-builder
 repo_url: 'https://github.com/electron-userland/electron-builder'
@@ -37,6 +64,9 @@ markdown_extensions:
       permalink: true
 
 plugins:
+  - search
+  # - minify:
+  #     minify_html: true
   - include-markdown:
       # encoding: ascii
       # preserve_includer_indent: true

diff --git a/packages/app-builder-lib/scheme.json b/packages/app-builder-lib/scheme.json
@@ -1061,14 +1061,14 @@
               "type": "string"
             }
           ],
-          "description": "The [glob patterns](./file-patterns.md)."
+          "description": "The [glob patterns](./file-patterns.md). Defaults to \"**\\/*\""
         },
         "from": {
-          "description": "The source path relative to the project directory.",
+          "description": "The source path relative to and defaults to:\n\n - the [app directory](configuration.md#MetadataDirectories-app) for `files`,\n - the project directory for `extraResources` and `extraFiles`.\nIf you don't use two-package.json structure and don't set custom app directory, app directory equals to project directory.",
           "type": "string"
         },
         "to": {
-          "description": "The destination path relative to the app's content directory for `extraFiles` and the app's resource directory for `extraResources`.",
+          "description": "The destination path relative to and defaults to:\n\n - the asar archive root for `files`,\n - the app's content directory for `extraFiles`,\n - the app's resource directory for `extraResources`.",
           "type": "string"
         }
       },

diff --git a/packages/app-builder-lib/src/options/PlatformSpecificBuildOptions.ts b/packages/app-builder-lib/src/options/PlatformSpecificBuildOptions.ts
@@ -3,15 +3,23 @@ import { FileAssociation } from "./FileAssociation"
 
 export interface FileSet {
   /**
-   * The source path relative to the project directory.
+   * The source path relative to and defaults to:
+   *
+   *  - the [app directory](configuration.md#MetadataDirectories-app) for `files`,
+   *  - the project directory for `extraResources` and `extraFiles`.
+   * If you don't use two-package.json structure and don't set custom app directory, app directory equals to project directory.
    */
   from?: string
   /**
-   * The destination path relative to the app's content directory for `extraFiles` and the app's resource directory for `extraResources`.
+   * The destination path relative to and defaults to:
+   *
+   *  - the asar archive root for `files`,
+   *  - the app's content directory for `extraFiles`,
+   *  - the app's resource directory for `extraResources`.
    */
   to?: string
   /**
-   * The [glob patterns](./file-patterns.md).
+   * The [glob patterns](./file-patterns.md). Defaults to "**\/*"
    */
   filter?: Array<string> | string
 }
@@ -74,7 +82,7 @@ export interface PlatformSpecificBuildOptions extends TargetSpecificOptions {
    */
   readonly asarUnpack?: Array<string> | string | null
 
-  /** @private */
+  /*  - @private */
   readonly icon?: string | null
 
   /**
@@ -126,10 +134,10 @@ export interface PlatformSpecificBuildOptions extends TargetSpecificOptions {
 
   readonly target?: Array<string | TargetConfiguration> | string | TargetConfiguration | null
 
-  /** @private */
+  /*  - @private */
   cscLink?: string | null
 
-  /** @private */
+  /*  - @private */
   cscKeyPassword?: string | null
 
   readonly defaultArch?: string

diff --git a/pages/api/electron-builder.md b/pages/api/electron-builder.md
@@ -1,4 +1,11 @@
 Developer API only. See [Configuration](../configuration.md) for user documentation.
 
+# Electron-Builder (main entry point)
 {% include "../electron-builder/globals.md" %}
 
+# App-Builder-Lib
+{% include "../app-builder-lib/globals.md" %}
+
+# Electron-Updater
+{% include "../electron-updater/globals.md" %}
+
diff --git a/pages/appx.md b/pages/appx.md
@@ -2,10 +2,6 @@ The top-level [appx](configuration.md#Configuration-appx) key contains set of op
 
 All options are optional. All required for AppX configuration is inferred and computed automatically.
 
-# Configuration
-
-{% include "./app-builder-lib.Interface.AppXOptions.md" %}
-
 ## AppX Package Code Signing
 
 * If the AppX package is meant for enterprise or self-made distribution (manually install the app without using the Store for testing or for enterprise distribution), it must be [signed](../code-signing.md).
@@ -53,3 +49,7 @@ The only solution for now — using [Parallels Desktop for Mac](http://www.paral
 #### How do install AppX without trusted certificate?
 
 If you use self-signed certificate, you need to add it to "Trusted People". See [Install the certificate](https://stackoverflow.com/a/24372483/1910191).
+
+# Configuration
+
+{% include "./app-builder-lib.Interface.AppXOptions.md" %}
diff --git a/pages/contents.md b/pages/contents.md
@@ -24,7 +24,6 @@ Defaults to:
 
 Development dependencies are never copied in any case. You don't need to ignore it explicitly. Hidden files are not ignored by default, but all files that should be ignored, are ignored by default.
 
-
 Default pattern `**/*` **is not added to your custom** if some of your patterns is not ignore (i.e. not starts with `!`). `package.json` and `**/node_modules/**/*` (only production dependencies will be copied) is added to your custom in any case. All default ignores are added in any case — you don't need to repeat it if you configure own patterns.
 
 May be specified in the platform options (e.g. in the [mac](mac.md)).
@@ -43,32 +42,6 @@ You may also specify custom source and destination directories by using `FileSet
 
 You can use [file macros](../file-patterns.md#file-macros) in the `from` and `to` fields as well. `from` and `to` can be files and you can use this to [rename](https://github.com/electron-userland/electron-builder/issues/1119) a file while packaging.
 
-### `FileSet.from`
-
-`String`
-
-The source path relative to and defaults to:
-
-* the [app directory](configuration.md#MetadataDirectories-app) for `files`,
-* the project directory for `extraResources` and `extraFiles`.
-
-If you don't use two-package.json structure and don't set custom app directory, app directory equals to project directory.
-
-### `FileSet.to`
-
-`String`
-
-The destination path relative to and defaults to:
-* the asar archive root for `files`,
-* the app's content directory for `extraFiles`,
-* the app's resource directory for `extraResources`.
-
-### `FileSet.filter`
-
-`Array<String> | String`
-
-The [glob patterns](../file-patterns.md). Defaults to `**/*`.
-
 ## extraResources
 
 `Array<String | FileSet> | String | FileSet`
@@ -81,4 +54,8 @@ File patterns (and support for `from` and `to` fields) the same as for [files](#
 
 `Array<String | FileSet> | String | FileSet`
 
-The same as [extraResources](#extraresources) but copy into the app's content directory (`Contents` for MacOS, root directory for Linux and Windows).
+The same as [extraResources](#extraresources) but copy into the app's content directory (`Contents` for MacOS, root directory for Linux and Windows).
+
+# FileSet Configuration
+
+{% include "./app-builder-lib.Interface.FileSet.md" %}
diff --git a/pages/dmg.md b/pages/dmg.md
@@ -1,9 +1,5 @@
 The top-level [dmg](configuration.md#Configuration-dmg) key contains set of options instructing electron-builder on how it should build [DMG](https://en.wikipedia.org/wiki/Apple_Disk_Image).
 
-# Configuration
-
-{% include "./app-builder-lib.Interface.DmgOptions.md" %}
-
 ## DMG License
 
 To add license to DMG, create file `license_LANG_CODE.txt` in the build resources. Multiple license files in different languages are supported — use lang postfix (e.g. `_de`, `_ru`)). For example, create files `license_de.txt` and `license_en.txt` in the build resources.
@@ -21,3 +17,7 @@ The contain file should have the following format:
   "description": "Here is my own description"
 }
 ```
+
+# Configuration
+
+{% include "./app-builder-lib.Interface.DmgOptions.md" %}
diff --git a/pages/extra.js b/pages/extra.js
@@ -1,6 +1,6 @@
 "use strict"
 
-loadNavPane()
+// loadNavPane()
 
 function loadNavPane() {
   const isMobile = window.matchMedia("only screen and (max-width: 760px)").matches

diff --git a/pages/flatpak.md b/pages/flatpak.md
@@ -8,16 +8,13 @@ The top-level [flatpak](configuration.md#Configuration-flatpak) key contains a s
 !!! info "Build dependencies"
     The `flatpak` and `flatpak-builder` packages need to be installed in order to build Flatpak bundles.
 
-# Configuration
-
-{% include "./app-builder-lib.Interface.FlatpakOptions.md" %}
-
-
----
-
 ## Troubleshooting
 
 If the Flatpak build process fails with an error message like "flatpak failed with status code X", setting the `DEBUG="@malept/flatpak-bundler"` environment variable should provide more context about the error.
 
 !!! example "Enable Flatpak build debug logging"
     `env DEBUG="@malept/flatpak-bundler" electron-builder build --linux flatpak`
+
+# Configuration
+
+{% include "./app-builder-lib.Interface.FlatpakOptions.md" %}
diff --git a/pages/linux.md b/pages/linux.md
@@ -13,7 +13,6 @@ The top-level [deb](configuration.md#Configuration-deb) key contains set of opti
 All [LinuxTargetSpecificOptions](linux.md#linuxtargetspecificoptions-apk-freebsd-pacman-p5p-and-rpm-options) can be also specified in the `deb` to customize Debian package.
 
 # `LinuxTargetSpecificOptions` APK, FreeBSD, Pacman, P5P and RPM Options
-<a name="LinuxTargetSpecificOptions"></a>
 
 The top-level `apk`, `freebsd`, `pacman`, `p5p` and `rpm` keys contains set of options instructing electron-builder on how it should build corresponding Linux target.
 

diff --git a/pages/msi-wrapped.md b/pages/msi-wrapped.md
@@ -1,17 +1,3 @@
-<ul>
-<li><code id="MsiWrappedOptions-wrappedInstallerArgs">wrappedInstallerArgs</code> String | “undefined” - Extra arguments to provide to the wrapped installer (ie: /S for silent install)</li>
-<li><code id="MsiWrappedOptions-impersonate">impersonate</code> = <code>false</code> Boolean - Determines if the wrapped installer should be executed with impersonation</li>
-<li><code id="MsiWrappedOptions-upgradeCode">upgradeCode</code> String | “undefined” - The <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa372375(v=vs.85).aspx">upgrade code</a>. Optional, by default generated using app id.</li>
-<li><code id="MsiWrappedOptions-warningsAsErrors">warningsAsErrors</code> = <code>true</code> Boolean - If <code>warningsAsErrors</code> is <code>true</code> (default): treat warnings as errors. If <code>warningsAsErrors</code> is <code>false</code>: allow warnings.</li>
-<li><code id="MsiWrappedOptions-additionalWixArgs">additionalWixArgs</code> Array&lt;String&gt; | “undefined” - Any additional arguments to be passed to the WiX installer compiler, such as <code>[&quot;-ext&quot;, &quot;WixUtilExtension&quot;]</code></li>
-<li><code id="MsiWrappedOptions-oneClick">oneClick</code> Boolean</li>
-<li><code id="MsiWrappedOptions-perMachine">perMachine</code> = <code>false</code> Boolean - Whether to install per all users (per-machine).</li>
-<li><code id="MsiWrappedOptions-runAfterFinish">runAfterFinish</code> = <code>true</code> Boolean - Whether to run the installed application after finish. For assisted installer corresponding checkbox will be removed.</li>
-</ul>
-<hr>
-<ul>
-<li><code id="MsiWrappedOptions-createDesktopShortcut">createDesktopShortcut</code> = <code>true</code> Boolean | “always” - Whether to create desktop shortcut. Set to <code>always</code> if to recreate also on reinstall (even if removed by user).</li>
-<li><code id="MsiWrappedOptions-createStartMenuShortcut">createStartMenuShortcut</code> = <code>true</code> Boolean - Whether to create start menu shortcut.</li>
-<li><code id="MsiWrappedOptions-menuCategory">menuCategory</code> = <code>false</code> Boolean | String - Whether to create submenu for start menu shortcut and program files directory. If <code>true</code>, company name will be used. Or string value.</li>
-<li><code id="MsiWrappedOptions-shortcutName">shortcutName</code> String | “undefined” - The name that will be used for all shortcuts. Defaults to the application name.</li>
-</ul>
+# Configuration
+
+{% include "./app-builder-lib.Interface.MsiWrappedOptions.md" %}
diff --git a/pages/msi.md b/pages/msi.md
@@ -1,16 +1,3 @@
-<ul>
-<li><code id="MsiOptions-oneClick">oneClick</code> = <code>true</code> Boolean - One-click installation.</li>
-<li><code id="MsiOptions-upgradeCode">upgradeCode</code> String | “undefined” - The <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa372375(v=vs.85).aspx">upgrade code</a>. Optional, by default generated using app id.</li>
-<li><code id="MsiOptions-warningsAsErrors">warningsAsErrors</code> = <code>true</code> Boolean - If <code>warningsAsErrors</code> is <code>true</code> (default): treat warnings as errors. If <code>warningsAsErrors</code> is <code>false</code>: allow warnings.</li>
-<li><code id="MsiOptions-additionalWixArgs">additionalWixArgs</code> Array&lt;String&gt; | “undefined” - Any additional arguments to be passed to the WiX installer compiler, such as <code>[&quot;-ext&quot;, &quot;WixUtilExtension&quot;]</code></li>
-<li><code id="MsiOptions-additionalLightArgs">additionalLightArgs</code> Array&lt;String&gt; | “undefined” - Any additional arguments to be passed to the light.ext, such as <code>[&quot;-cultures:ja-jp&quot;]</code></li>
-<li><code id="MsiOptions-perMachine">perMachine</code> = <code>false</code> Boolean - Whether to install per all users (per-machine).</li>
-<li><code id="MsiOptions-runAfterFinish">runAfterFinish</code> = <code>true</code> Boolean - Whether to run the installed application after finish. For assisted installer corresponding checkbox will be removed.</li>
-</ul>
-<hr>
-<ul>
-<li><code id="MsiOptions-createDesktopShortcut">createDesktopShortcut</code> = <code>true</code> Boolean | “always” - Whether to create desktop shortcut. Set to <code>always</code> if to recreate also on reinstall (even if removed by user).</li>
-<li><code id="MsiOptions-createStartMenuShortcut">createStartMenuShortcut</code> = <code>true</code> Boolean - Whether to create start menu shortcut.</li>
-<li><code id="MsiOptions-menuCategory">menuCategory</code> = <code>false</code> Boolean | String - Whether to create submenu for start menu shortcut and program files directory. If <code>true</code>, company name will be used. Or string value.</li>
-<li><code id="MsiOptions-shortcutName">shortcutName</code> String | “undefined” - The name that will be used for all shortcuts. Defaults to the application name.</li>
-</ul>
+# Configuration
+
+{% include "./app-builder-lib.Interface.MsiOptions.md" %}