From caecc29315f738c30e62c9515bf8e452441c4e10 Mon Sep 17 00:00:00 2001 From: Mike Maietta Date: Tue, 17 Sep 2024 10:01:01 -0700 Subject: [PATCH] autowidth for better readability update relative links to new folder `pages` structure add additional readme intro fixing links --- README.md | 66 +++++- mkdocs.yml | 4 +- netlify-docs.sh | 3 +- package.json | 4 +- packages/app-builder-lib/scheme.json | 154 ++++++------- packages/app-builder-lib/src/configuration.ts | 2 +- packages/app-builder-lib/src/core.ts | 2 +- packages/app-builder-lib/src/errorMessages.ts | 2 +- .../src/options/AppXOptions.ts | 2 +- .../src/options/FileAssociation.ts | 2 +- .../options/PlatformSpecificBuildOptions.ts | 10 +- .../src/options/SnapOptions.ts | 2 +- .../src/options/linuxOptions.ts | 10 +- .../app-builder-lib/src/options/macOptions.ts | 8 +- .../app-builder-lib/src/options/pkgOptions.ts | 2 +- .../app-builder-lib/src/options/winOptions.ts | 10 +- .../src/publish/BitbucketPublisher.ts | 2 +- .../src/publish/KeygenPublisher.ts | 2 +- .../src/publish/PublishManager.ts | 2 +- .../src/publish/s3/spacesPublisher.ts | 8 +- .../app-builder-lib/src/targets/FpmTarget.ts | 2 +- .../src/targets/LinuxTargetHelper.ts | 2 +- .../src/targets/nsis/nsisOptions.ts | 18 +- .../app-builder-lib/src/util/config/config.ts | 4 +- .../src/publishOptions.ts | 6 +- .../builder-util-runtime/src/updateInfo.ts | 2 +- .../src/SquirrelWindowsTarget.ts | 4 +- .../electron-forge-maker-appimage/readme.md | 2 +- .../electron-forge-maker-nsis-web/readme.md | 2 +- packages/electron-forge-maker-nsis/readme.md | 2 +- packages/electron-forge-maker-snap/readme.md | 2 +- packages/electron-updater/src/AppUpdater.ts | 2 +- pages/api/electron-builder.md | 5 +- pages/appimage.md | 1 + pages/appx.md | 4 +- pages/auto-update.md | 6 +- pages/cli.md | 33 ++- pages/code-signing.md | 2 +- pages/configuration.md | 24 +- pages/contents.md | 4 +- pages/dmg.md | 4 +- pages/flatpak.md | 5 +- pages/icons.md | 6 +- pages/index.md | 167 -------------- pages/linux.md | 6 +- pages/mac.md | 8 +- pages/mas.md | 5 +- pages/nsis.md | 2 +- pages/pkg.md | 4 +- pages/publish.md | 41 ++-- pages/snap.md | 4 +- pages/squirrel-windows.md | 4 +- pages/stylesheets/autowidth.css | 14 ++ pages/tutorials/macos-kernel-extensions.md | 4 +- pages/tutorials/two-package-structure.md | 4 +- pages/win.md | 12 +- scripts/renderer/src/typedoc2html.ts | 207 +----------------- typedoc.config.js | 15 +- 58 files changed, 338 insertions(+), 598 deletions(-) delete mode 100644 pages/index.md create mode 100644 pages/stylesheets/autowidth.css diff --git a/README.md b/README.md index 0d01dc2ebab..6445ad5b586 100644 --- a/README.md +++ b/README.md @@ -129,9 +129,9 @@ will declare to use node-modules instead of PnP. [electron-webpack-quick-start](https://github.com/electron-userland/electron-webpack-quick-start) is a recommended way to create a new Electron application. See [Boilerplates](https://www.electron.build/#boilerplates). -1. Specify the standard fields in the application `package.json` — [name](https://electron.build/configuration/configuration#Metadata-name), `description`, `version` and [author](https://docs.npmjs.com/files/package.json#people-fields-author-contributors). +1. Specify the standard fields in the application `package.json` — [name](https://electron.build./configuration.md#Metadata-name), `description`, `version` and [author](https://docs.npmjs.com/files/package.json#people-fields-author-contributors). -2. Specify the [build](https://electron.build/configuration/configuration#build) configuration in the `package.json` as follows: +2. Specify the [build](https://electron.build./configuration.md#build) configuration in the `package.json` as follows: ```json "build": { "appId": "your.id", @@ -156,12 +156,70 @@ will declare to use node-modules instead of PnP. To ensure your native dependencies are always matched electron version, simply add script `"postinstall": "electron-builder install-app-deps"` to your `package.json`. -5. If you have native addons of your own that are part of the application (not as a dependency), set [nodeGypRebuild](https://www.electron.build/configuration/configuration#Configuration-nodeGypRebuild) to `true`. +5. If you have native addons of your own that are part of the application (not as a dependency), set [nodeGypRebuild](https://www.electron.build./configuration.md#Configuration-nodeGypRebuild) to `true`. -Please note that everything is packaged into an asar archive [by default](https://electron.build/configuration/configuration#Configuration-asar). +Please note that everything is packaged into an asar archive [by default](https://electron.build./configuration.md#Configuration-asar). For an app that will be shipped to production, you should sign your application. See [Where to buy code signing certificates](https://www.electron.build/code-signing#where-to-buy-code-signing-certificate). +## Programmatic Usage +See `node_modules/electron-builder/out/index.d.ts`. Typings for TypeScript are provided and also can be found [here](/api/electron-builder.md). + +Code snippit provided below is also shown "in action" [here](/api/programmatic-usage.md) as well. +```js +"use strict" + +const builder = require("electron-builder") +const Platform = builder.Platform + +// Promise is returned +builder.build({ + targets: Platform.MAC.createTarget(), + config: { + "//": "build options, see https://goo.gl/QQXmcV" + } +}) + .then(() => { + // handle result + }) + .catch((error) => { + // handle error + }) +``` + +## Boilerplates + +* [electron-webpack-quick-start](https://github.com/electron-userland/electron-webpack-quick-start) — A bare minimum project structure to get started developing with [electron-webpack](https://github.com/electron-userland/electron-webpack). Recommended. +* [electron-react-boilerplate](https://github.com/chentsulin/electron-react-boilerplate) A boilerplate for scalable cross-platform desktop apps. +* [electron-react-redux-boilerplate](https://github.com/jschr/electron-react-redux-boilerplate) A minimal boilerplate to get started with Electron, React and Redux. +* [electron-boilerplate](https://github.com/szwacz/electron-boilerplate) A minimalistic yet comprehensive boilerplate application. +* [Vue CLI 3 plugin for Electron](https://nklayman.github.io/vue-cli-plugin-electron-builder) A Vue CLI 3 plugin for Electron with no required configuration. +* [electron-vue-vite](https://github.com/caoxiemeihao/electron-vue-vite) A real simple Electron + Vue3 + Vite5 boilerplate. +* [vite-electron-builder](https://github.com/cawa-93/vite-electron-builder) Secure boilerplate for Electron app based on Vite. TypeScript + Vue/React/Angular/Svelte/Vanilla + +## Debug + +Set the `DEBUG` environment variable to debug what electron-builder is doing: +```bash +DEBUG=electron-builder +``` + +`FPM_DEBUG` env to add more details about building linux targets (except snap and appimage). + +`DEBUG_DMG=true` env var to add more debugging/verbosity from `hdiutil` (macOS). + +!!! tip "cmd" + On [Windows](https://github.com/visionmedia/debug#windows-command-prompt-notes) the environment variable is set using the set command. + ```bash + set DEBUG=electron-builder + ``` + +!!! tip "PowerShell" + PowerShell uses different syntax to set environment variables. + ```bash + $env:DEBUG=electron-builder + ``` + ## Donate We do this open source work in our free time. If you'd like us to invest more time on it, please [donate](https://www.electron.build/donate). diff --git a/mkdocs.yml b/mkdocs.yml index 4cb68adbd38..baca311d264 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,8 @@ site_name: electron-builder site_url: https://www.electron.build use_directory_urls: false +extra_css: + - stylesheets/autowidth.css theme: feature: tabs: true @@ -50,7 +52,7 @@ plugins: # recursive: true nav: - - Introduction: index.md + - Introduction: README.md - Command Line Interface (CLI): cli.md - Programmatic API: - API: api/electron-builder.md diff --git a/netlify-docs.sh b/netlify-docs.sh index 8c244fec0f8..c9a31ef585c 100644 --- a/netlify-docs.sh +++ b/netlify-docs.sh @@ -4,6 +4,5 @@ pipenv install echo "Installing deps" pnpm install echo "Building site docs" -pnpm compile -node scripts/renderer/out/typedoc2html.js +pnpm docs:build mkdocs build \ No newline at end of file diff --git a/package.json b/package.json index c5d66f90716..68dbaf55ed2 100644 --- a/package.json +++ b/package.json @@ -32,7 +32,9 @@ "ci:version": "pnpm i && pnpm changelog && changeset version && node scripts/update-package-version-export.js && pnpm compile && pnpm generate-all && git add .", "ci:publish": "pnpm i && pnpm compile && pnpm publish -r --tag next && changeset tag", "docs:prebuild": "docker build -t mkdocs-dockerfile -f mkdocs-dockerfile . ", - "docs:build": "node scripts/renderer/out/src/typedoc2html.js && docker run --rm -v ${PWD}:/docs -v ${PWD}/site:/site mkdocs-dockerfile build", + "docs:build": "pnpm compile && node scripts/renderer/out/typedoc2html.js", + "docs:mkdocs": "docker run --rm -v ${PWD}:/docs -v ${PWD}/site:/site mkdocs-dockerfile build", + "docs:all": "pnpm docs:prebuild && pnpm docs:build && pnpm docs:mkdocs", "prepare": "husky install" }, "//": "repository must be specified otherwise conventional-changelog will use forked repo (currently cloned)", diff --git a/packages/app-builder-lib/scheme.json b/packages/app-builder-lib/scheme.json index c583e08fedf..e319a84f910 100644 --- a/packages/app-builder-lib/scheme.json +++ b/packages/app-builder-lib/scheme.json @@ -37,7 +37,7 @@ "additionalProperties": false, "properties": { "artifactName": { - "description": "The [artifact file name template](/configuration/configuration#artifact-file-name-template).", + "description": "The [artifact file name template](./configuration.md#artifact-file-name-template).", "type": [ "null", "string" @@ -51,7 +51,7 @@ ] }, "description": { - "description": "As [description](/configuration/configuration#Metadata-description) from application package.json, but allows you to specify different for Linux.", + "description": "As [description](./configuration.md#Metadata-description) from application package.json, but allows you to specify different for Linux.", "type": [ "null", "string" @@ -157,7 +157,7 @@ "type": "string" }, "artifactName": { - "description": "The [artifact file name template](/configuration/configuration#artifact-file-name-template).", + "description": "The [artifact file name template](./configuration.md#artifact-file-name-template).", "type": [ "null", "string" @@ -187,7 +187,7 @@ "type": "boolean" }, "identityName": { - "description": "The name. Corresponds to [Identity.Name](https://msdn.microsoft.com/en-us/library/windows/apps/br211441.aspx). Defaults to the [application name](/configuration/configuration#Metadata-name).", + "description": "The name. Corresponds to [Identity.Name](https://msdn.microsoft.com/en-us/library/windows/apps/br211441.aspx). Defaults to the [application name](./configuration.md#Metadata-name).", "type": [ "null", "string" @@ -523,7 +523,7 @@ ] }, "artifactName": { - "description": "The [artifact file name template](/configuration/configuration#artifact-file-name-template).", + "description": "The [artifact file name template](./configuration.md#artifact-file-name-template).", "type": [ "null", "string" @@ -569,7 +569,7 @@ "description": "Package dependencies. Defaults to `[\"gconf2\", \"gconf-service\", \"libnotify4\", \"libappindicator1\", \"libxtst6\", \"libnss3\"]`.\nIf need to support Debian, `libappindicator1` should be removed, it is [deprecated in Debian](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=895037).\nIf need to support KDE, `gconf2` and `gconf-service` should be removed as it's no longer used [by GNOME](https://packages.debian.org/bullseye/gconf2)." }, "description": { - "description": "As [description](/configuration/configuration#Metadata-description) from application package.json, but allows you to specify different for Linux.", + "description": "As [description](./configuration.md#Metadata-description) from application package.json, but allows you to specify different for Linux.", "type": [ "null", "string" @@ -758,7 +758,7 @@ "additionalProperties": false, "properties": { "artifactName": { - "description": "The [artifact file name template](/configuration/configuration#artifact-file-name-template).", + "description": "The [artifact file name template](./configuration.md#artifact-file-name-template).", "type": [ "null", "string" @@ -799,7 +799,7 @@ "type": "string" }, "icon": { - "description": "The path to DMG icon (volume icon), which will be shown when mounted, relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory.\nDefaults to the application icon (`build/icon.icns`).", + "description": "The path to DMG icon (volume icon), which will be shown when mounted, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory.\nDefaults to the application icon (`build/icon.icns`).", "type": [ "null", "string" @@ -982,7 +982,7 @@ }, "FileAssociation": { "additionalProperties": false, - "description": "File associations.\n\nmacOS (corresponds to [CFBundleDocumentTypes](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-101685)), NSIS, and MSI only.\n\nOn Windows (NSIS) works only if [nsis.perMachine](https://electron.build/configuration/configuration#NsisOptions-perMachine) is set to `true`.", + "description": "File associations.\n\nmacOS (corresponds to [CFBundleDocumentTypes](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-101685)), NSIS, and MSI only.\n\nOn Windows (NSIS) works only if [nsis.perMachine](https://electron.build./configuration.md#NsisOptions-perMachine) is set to `true`.", "properties": { "description": { "description": "*windows-only.* The description.", @@ -1061,7 +1061,7 @@ "type": "string" } ], - "description": "The [glob patterns](/file-patterns)." + "description": "The [glob patterns](./file-patterns.md)." }, "from": { "description": "The source path relative to the project directory.", @@ -1078,7 +1078,7 @@ "additionalProperties": false, "properties": { "artifactName": { - "description": "The [artifact file name template](/configuration/configuration#artifact-file-name-template).", + "description": "The [artifact file name template](./configuration.md#artifact-file-name-template).", "type": [ "null", "string" @@ -1104,7 +1104,7 @@ ] }, "description": { - "description": "As [description](/configuration/configuration#Metadata-description) from application package.json, but allows you to specify different for Linux.", + "description": "As [description](./configuration.md#Metadata-description) from application package.json, but allows you to specify different for Linux.", "type": [ "null", "string" @@ -1262,7 +1262,7 @@ }, "GenericServerOptions": { "additionalProperties": false, - "description": "Generic (any HTTP(S) server) options.\nIn all publish options [File Macros](/file-patterns#file-macros) are supported.", + "description": "Generic (any HTTP(S) server) options.\nIn all publish options [File Macros](./file-patterns.md#file-macros) are supported.", "properties": { "channel": { "default": "latest", @@ -1356,7 +1356,7 @@ ] }, "private": { - "description": "Whether to use private github auto-update provider if `GH_TOKEN` environment variable is defined. See [Private GitHub Update Repo](/auto-update#private-github-update-repo).", + "description": "Whether to use private github auto-update provider if `GH_TOKEN` environment variable is defined. See [Private GitHub Update Repo](./auto-update.md#private-github-update-repo).", "type": [ "null", "boolean" @@ -1438,7 +1438,7 @@ ] }, "token": { - "description": "The access token to support auto-update from private github repositories. Never specify it in the configuration files. Only for [setFeedURL](/auto-update#appupdatersetfeedurloptions).", + "description": "The access token to support auto-update from private github repositories. Never specify it in the configuration files. Only for [setFeedURL](./auto-update.md#appupdatersetfeedurloptions).", "type": [ "null", "string" @@ -1560,7 +1560,7 @@ ] }, "artifactName": { - "description": "The [artifact file name template](/configuration/configuration#artifact-file-name-template). Defaults to `${productName}-${version}.${ext}` (some target can have other defaults, see corresponding options).", + "description": "The [artifact file name template](./configuration.md#artifact-file-name-template). Defaults to `${productName}-${version}.${ext}` (some target can have other defaults, see corresponding options).", "type": [ "null", "string" @@ -1596,7 +1596,7 @@ ] } ], - "description": "A [glob patterns](/file-patterns) relative to the [app directory](#MetadataDirectories-app), which specifies which files to unpack when creating the [asar](http://electron.atom.io/docs/tutorial/application-packaging/) archive." + "description": "A [glob patterns](./file-patterns.md) relative to the [app directory](#MetadataDirectories-app), which specifies which files to unpack when creating the [asar](http://electron.atom.io/docs/tutorial/application-packaging/) archive." }, "category": { "description": "The [application category](https://specifications.freedesktop.org/menu-spec/latest/apa.html#main-category-registry).", @@ -1638,7 +1638,7 @@ "type": "string" }, "description": { - "description": "As [description](/configuration/configuration#Metadata-description) from application package.json, but allows you to specify different for Linux.", + "description": "As [description](./configuration.md#Metadata-description) from application package.json, but allows you to specify different for Linux.", "type": [ "null", "string" @@ -1654,7 +1654,7 @@ }, "disableDefaultIgnoredFiles": { "default": false, - "description": "Whether to exclude all default ignored files(https://www.electron.build/configuration/contents#files) and options. Defaults to `false`.", + "description": "Whether to exclude all default ignored files(https://www.electron.build/contents#files) and options. Defaults to `false`.", "type": [ "null", "boolean" @@ -1675,7 +1675,7 @@ "description": "The electron locales to keep. By default, all Electron locales used as-is." }, "electronUpdaterCompatibility": { - "description": "The [electron-updater compatibility](/auto-update#compatibility) semver range.", + "description": "The [electron-updater compatibility](./auto-update.md#compatibility) semver range.", "type": [ "null", "string" @@ -1804,11 +1804,11 @@ "type": "boolean" }, "icon": { - "description": "The path to icon set directory or one png file, relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory. The icon filename must contain the size (e.g. 32x32.png) of the icon.\nBy default will be generated automatically based on the macOS icns file.", + "description": "The path to icon set directory or one png file, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory. The icon filename must contain the size (e.g. 32x32.png) of the icon.\nBy default will be generated automatically based on the macOS icns file.", "type": "string" }, "maintainer": { - "description": "The maintainer. Defaults to [author](/configuration/configuration#Metadata-author).", + "description": "The maintainer. Defaults to [author](./configuration.md#Metadata-author).", "type": [ "null", "string" @@ -1926,10 +1926,10 @@ } ], "default": "AppImage", - "description": "Target package type: list of `AppImage`, `flatpak`, `snap`, `deb`, `rpm`, `freebsd`, `pacman`, `p5p`, `apk`, `7z`, `zip`, `tar.xz`, `tar.lz`, `tar.gz`, `tar.bz2`, `dir`.\n\nelectron-builder [docker image](/multi-platform-build#docker) can be used to build Linux targets on any platform.\n\nPlease [do not put an AppImage into another archive](https://github.com/probonopd/AppImageKit/wiki/Creating-AppImages#common-mistake) like a .zip or .tar.gz." + "description": "Target package type: list of `AppImage`, `flatpak`, `snap`, `deb`, `rpm`, `freebsd`, `pacman`, `p5p`, `apk`, `7z`, `zip`, `tar.xz`, `tar.lz`, `tar.gz`, `tar.bz2`, `dir`.\n\nelectron-builder [docker image](./multi-platform-build.md#docker) can be used to build Linux targets on any platform.\n\nPlease [do not put an AppImage into another archive](https://github.com/probonopd/AppImageKit/wiki/Creating-AppImages#common-mistake) like a .zip or .tar.gz." }, "vendor": { - "description": "The vendor. Defaults to [author](/configuration/configuration#Metadata-author).", + "description": "The vendor. Defaults to [author](./configuration.md#Metadata-author).", "type": [ "null", "string" @@ -1954,7 +1954,7 @@ ] }, "artifactName": { - "description": "The [artifact file name template](/configuration/configuration#artifact-file-name-template).", + "description": "The [artifact file name template](./configuration.md#artifact-file-name-template).", "type": [ "null", "string" @@ -2000,7 +2000,7 @@ "description": "Package dependencies." }, "description": { - "description": "As [description](/configuration/configuration#Metadata-description) from application package.json, but allows you to specify different for Linux.", + "description": "As [description](./configuration.md#Metadata-description) from application package.json, but allows you to specify different for Linux.", "type": [ "null", "string" @@ -2156,7 +2156,7 @@ ] }, "artifactName": { - "description": "The [artifact file name template](/configuration/configuration#artifact-file-name-template). Defaults to `${productName}-${version}.${ext}` (some target can have other defaults, see corresponding options).", + "description": "The [artifact file name template](./configuration.md#artifact-file-name-template). Defaults to `${productName}-${version}.${ext}` (some target can have other defaults, see corresponding options).", "type": [ "null", "string" @@ -2192,7 +2192,7 @@ ] } ], - "description": "A [glob patterns](/file-patterns) relative to the [app directory](#MetadataDirectories-app), which specifies which files to unpack when creating the [asar](http://electron.atom.io/docs/tutorial/application-packaging/) archive." + "description": "A [glob patterns](./file-patterns.md) relative to the [app directory](#MetadataDirectories-app), which specifies which files to unpack when creating the [asar](http://electron.atom.io/docs/tutorial/application-packaging/) archive." }, "binaries": { "anyOf": [ @@ -2285,7 +2285,7 @@ }, "disableDefaultIgnoredFiles": { "default": false, - "description": "Whether to exclude all default ignored files(https://www.electron.build/configuration/contents#files) and options. Defaults to `false`.", + "description": "Whether to exclude all default ignored files(https://www.electron.build/contents#files) and options. Defaults to `false`.", "type": [ "null", "boolean" @@ -2306,14 +2306,14 @@ "description": "The electron locales to keep. By default, all Electron locales used as-is." }, "electronUpdaterCompatibility": { - "description": "The [electron-updater compatibility](/auto-update#compatibility) semver range.", + "description": "The [electron-updater compatibility](./auto-update.md#compatibility) semver range.", "type": [ "null", "string" ] }, "entitlements": { - "description": "The path to entitlements file for signing the app. `build/entitlements.mac.plist` will be used if exists (it is a recommended way to set).\nMAS entitlements is specified in the [mas](/configuration/mas).\nSee [this folder in osx-sign's repository](https://github.com/electron/osx-sign/tree/main/entitlements) for examples.\nBe aware that your app may crash if the right entitlements are not set like `com.apple.security.cs.allow-jit` for example on arm64 builds with Electron 20+.\nSee [Signing and Notarizing macOS Builds from the Electron documentation](https://www.electronjs.org/docs/latest/tutorial/code-signing#signing--notarizing-macos-builds) for more information.", + "description": "The path to entitlements file for signing the app. `build/entitlements.mac.plist` will be used if exists (it is a recommended way to set).\nMAS entitlements is specified in the [mas](./mas.md).\nSee [this folder in osx-sign's repository](https://github.com/electron/osx-sign/tree/main/entitlements) for examples.\nBe aware that your app may crash if the right entitlements are not set like `com.apple.security.cs.allow-jit` for example on arm64 builds with Electron 20+.\nSee [Signing and Notarizing macOS Builds from the Electron documentation](https://www.electronjs.org/docs/latest/tutorial/code-signing#signing--notarizing-macos-builds) for more information.", "type": [ "null", "string" @@ -2528,7 +2528,7 @@ ] }, "identity": { - "description": "The name of certificate to use when signing. Consider using environment variables [CSC_LINK or CSC_NAME](/code-signing) instead of specifying this option.\nMAS installer identity is specified in the [mas](/configuration/mas).", + "description": "The name of certificate to use when signing. Consider using environment variables [CSC_LINK or CSC_NAME](./code-signing.md) instead of specifying this option.\nMAS installer identity is specified in the [mas](./mas.md).", "type": [ "null", "string" @@ -2794,7 +2794,7 @@ ] }, "artifactName": { - "description": "The [artifact file name template](/configuration/configuration#artifact-file-name-template). Defaults to `${productName}-${version}.${ext}` (some target can have other defaults, see corresponding options).", + "description": "The [artifact file name template](./configuration.md#artifact-file-name-template). Defaults to `${productName}-${version}.${ext}` (some target can have other defaults, see corresponding options).", "type": [ "null", "string" @@ -2830,7 +2830,7 @@ ] } ], - "description": "A [glob patterns](/file-patterns) relative to the [app directory](#MetadataDirectories-app), which specifies which files to unpack when creating the [asar](http://electron.atom.io/docs/tutorial/application-packaging/) archive." + "description": "A [glob patterns](./file-patterns.md) relative to the [app directory](#MetadataDirectories-app), which specifies which files to unpack when creating the [asar](http://electron.atom.io/docs/tutorial/application-packaging/) archive." }, "binaries": { "anyOf": [ @@ -2923,7 +2923,7 @@ }, "disableDefaultIgnoredFiles": { "default": false, - "description": "Whether to exclude all default ignored files(https://www.electron.build/configuration/contents#files) and options. Defaults to `false`.", + "description": "Whether to exclude all default ignored files(https://www.electron.build/contents#files) and options. Defaults to `false`.", "type": [ "null", "boolean" @@ -2944,7 +2944,7 @@ "description": "The electron locales to keep. By default, all Electron locales used as-is." }, "electronUpdaterCompatibility": { - "description": "The [electron-updater compatibility](/auto-update#compatibility) semver range.", + "description": "The [electron-updater compatibility](./auto-update.md#compatibility) semver range.", "type": [ "null", "string" @@ -3166,7 +3166,7 @@ ] }, "identity": { - "description": "The name of certificate to use when signing. Consider using environment variables [CSC_LINK or CSC_NAME](/code-signing) instead of specifying this option.\nMAS installer identity is specified in the [mas](/configuration/mas).", + "description": "The name of certificate to use when signing. Consider using environment variables [CSC_LINK or CSC_NAME](./code-signing.md) instead of specifying this option.\nMAS installer identity is specified in the [mas](./mas.md).", "type": [ "null", "string" @@ -3426,7 +3426,7 @@ }, "output": { "default": "dist", - "description": "The output directory. [File macros](/file-patterns#file-macros) are supported.", + "description": "The output directory. [File macros](./file-patterns.md#file-macros) are supported.", "type": [ "null", "string" @@ -3467,7 +3467,7 @@ "description": "Any additional arguments to be passed to the WiX installer compiler, such as `[\"-ext\", \"WixUtilExtension\"]`" }, "artifactName": { - "description": "The [artifact file name template](/configuration/configuration#artifact-file-name-template).", + "description": "The [artifact file name template](./configuration.md#artifact-file-name-template).", "type": [ "null", "string" @@ -3590,7 +3590,7 @@ "description": "Any additional arguments to be passed to the WiX installer compiler, such as `[\"-ext\", \"WixUtilExtension\"]`" }, "artifactName": { - "description": "The [artifact file name template](/configuration/configuration#artifact-file-name-template).", + "description": "The [artifact file name template](./configuration.md#artifact-file-name-template).", "type": [ "null", "string" @@ -3729,7 +3729,7 @@ "type": "boolean" }, "artifactName": { - "description": "The [artifact file name template](/configuration/configuration#artifact-file-name-template). Defaults to `${productName} Setup ${version}.${ext}`.", + "description": "The [artifact file name template](./configuration.md#artifact-file-name-template). Defaults to `${productName} Setup ${version}.${ext}`.", "type": [ "null", "string" @@ -3774,7 +3774,7 @@ "type": "boolean" }, "guid": { - "description": "See [GUID vs Application Name](../configuration/nsis#guid-vs-application-name).", + "description": "See [GUID vs Application Name](./nsis.md#guid-vs-application-name).", "type": [ "null", "string" @@ -3789,21 +3789,21 @@ }, "installerHeader": { "default": "build/installerHeader.bmp", - "description": "*assisted installer only.* `MUI_HEADERIMAGE`, relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory.", + "description": "*assisted installer only.* `MUI_HEADERIMAGE`, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory.", "type": [ "null", "string" ] }, "installerHeaderIcon": { - "description": "*one-click installer only.* The path to header icon (above the progress bar), relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `build/installerHeaderIcon.ico` or application icon.", + "description": "*one-click installer only.* The path to header icon (above the progress bar), relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `build/installerHeaderIcon.ico` or application icon.", "type": [ "null", "string" ] }, "installerIcon": { - "description": "The path to installer icon, relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `build/installerIcon.ico` or application icon.", + "description": "The path to installer icon, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `build/installerIcon.ico` or application icon.", "type": [ "null", "string" @@ -3827,7 +3827,7 @@ "description": "The installer languages (e.g. `en_US`, `de_DE`). Change only if you understand what do you do and for what." }, "installerSidebar": { - "description": "*assisted installer only.* `MUI_WELCOMEFINISHPAGE_BITMAP`, relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `build/installerSidebar.bmp` or `${NSISDIR}\\\\Contrib\\\\Graphics\\\\Wizard\\\\nsis3-metro.bmp`. Image size 164 × 314 pixels.", + "description": "*assisted installer only.* `MUI_WELCOMEFINISHPAGE_BITMAP`, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `build/installerSidebar.bmp` or `${NSISDIR}\\\\Contrib\\\\Graphics\\\\Wizard\\\\nsis3-metro.bmp`. Image size 164 × 314 pixels.", "type": [ "null", "string" @@ -3982,14 +3982,14 @@ "type": "string" }, "uninstallerIcon": { - "description": "The path to uninstaller icon, relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `build/uninstallerIcon.ico` or application icon.", + "description": "The path to uninstaller icon, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `build/uninstallerIcon.ico` or application icon.", "type": [ "null", "string" ] }, "uninstallerSidebar": { - "description": "*assisted installer only.* `MUI_UNWELCOMEFINISHPAGE_BITMAP`, relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `installerSidebar` option or `build/uninstallerSidebar.bmp` or `build/installerSidebar.bmp` or `${NSISDIR}\\\\Contrib\\\\Graphics\\\\Wizard\\\\nsis3-metro.bmp`", + "description": "*assisted installer only.* `MUI_UNWELCOMEFINISHPAGE_BITMAP`, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `installerSidebar` option or `build/uninstallerSidebar.bmp` or `build/installerSidebar.bmp` or `${NSISDIR}\\\\Contrib\\\\Graphics\\\\Wizard\\\\nsis3-metro.bmp`", "type": [ "null", "string" @@ -4029,7 +4029,7 @@ ] }, "artifactName": { - "description": "The [artifact file name template](/configuration/configuration#artifact-file-name-template). Defaults to `${productName} Web Setup ${version}.${ext}`.", + "description": "The [artifact file name template](./configuration.md#artifact-file-name-template). Defaults to `${productName} Web Setup ${version}.${ext}`.", "type": [ "null", "string" @@ -4074,7 +4074,7 @@ "type": "boolean" }, "guid": { - "description": "See [GUID vs Application Name](../configuration/nsis#guid-vs-application-name).", + "description": "See [GUID vs Application Name](./nsis.md#guid-vs-application-name).", "type": [ "null", "string" @@ -4089,21 +4089,21 @@ }, "installerHeader": { "default": "build/installerHeader.bmp", - "description": "*assisted installer only.* `MUI_HEADERIMAGE`, relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory.", + "description": "*assisted installer only.* `MUI_HEADERIMAGE`, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory.", "type": [ "null", "string" ] }, "installerHeaderIcon": { - "description": "*one-click installer only.* The path to header icon (above the progress bar), relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `build/installerHeaderIcon.ico` or application icon.", + "description": "*one-click installer only.* The path to header icon (above the progress bar), relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `build/installerHeaderIcon.ico` or application icon.", "type": [ "null", "string" ] }, "installerIcon": { - "description": "The path to installer icon, relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `build/installerIcon.ico` or application icon.", + "description": "The path to installer icon, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `build/installerIcon.ico` or application icon.", "type": [ "null", "string" @@ -4127,7 +4127,7 @@ "description": "The installer languages (e.g. `en_US`, `de_DE`). Change only if you understand what do you do and for what." }, "installerSidebar": { - "description": "*assisted installer only.* `MUI_WELCOMEFINISHPAGE_BITMAP`, relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `build/installerSidebar.bmp` or `${NSISDIR}\\\\Contrib\\\\Graphics\\\\Wizard\\\\nsis3-metro.bmp`. Image size 164 × 314 pixels.", + "description": "*assisted installer only.* `MUI_WELCOMEFINISHPAGE_BITMAP`, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `build/installerSidebar.bmp` or `${NSISDIR}\\\\Contrib\\\\Graphics\\\\Wizard\\\\nsis3-metro.bmp`. Image size 164 × 314 pixels.", "type": [ "null", "string" @@ -4282,14 +4282,14 @@ "type": "string" }, "uninstallerIcon": { - "description": "The path to uninstaller icon, relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `build/uninstallerIcon.ico` or application icon.", + "description": "The path to uninstaller icon, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `build/uninstallerIcon.ico` or application icon.", "type": [ "null", "string" ] }, "uninstallerSidebar": { - "description": "*assisted installer only.* `MUI_UNWELCOMEFINISHPAGE_BITMAP`, relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `installerSidebar` option or `build/uninstallerSidebar.bmp` or `build/installerSidebar.bmp` or `${NSISDIR}\\\\Contrib\\\\Graphics\\\\Wizard\\\\nsis3-metro.bmp`", + "description": "*assisted installer only.* `MUI_UNWELCOMEFINISHPAGE_BITMAP`, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory.\nDefaults to `installerSidebar` option or `build/uninstallerSidebar.bmp` or `build/installerSidebar.bmp` or `${NSISDIR}\\\\Contrib\\\\Graphics\\\\Wizard\\\\nsis3-metro.bmp`", "type": [ "null", "string" @@ -4798,7 +4798,7 @@ ] }, "artifactName": { - "description": "The [artifact file name template](/configuration/configuration#artifact-file-name-template).", + "description": "The [artifact file name template](./configuration.md#artifact-file-name-template).", "type": [ "null", "string" @@ -4831,7 +4831,7 @@ ] }, "identity": { - "description": "The name of certificate to use when signing. Consider using environment variables [CSC_LINK or CSC_NAME](/code-signing) instead of specifying this option.", + "description": "The name of certificate to use when signing. Consider using environment variables [CSC_LINK or CSC_NAME](./code-signing.md) instead of specifying this option.", "type": [ "null", "string" @@ -4988,7 +4988,7 @@ "description": "Portable options.", "properties": { "artifactName": { - "description": "The [artifact file name template](/configuration/configuration#artifact-file-name-template).", + "description": "The [artifact file name template](./configuration.md#artifact-file-name-template).", "type": [ "null", "string" @@ -5006,7 +5006,7 @@ "description": "Allows you to provide your own `makensis`, such as one with support for debug logging via LogSet and LogText. (Logging also requires option `debugLogging = true`)" }, "guid": { - "description": "See [GUID vs Application Name](../configuration/nsis#guid-vs-application-name).", + "description": "See [GUID vs Application Name](./nsis.md#guid-vs-application-name).", "type": [ "null", "string" @@ -5358,7 +5358,7 @@ "description": "Specifies which files from the app part to stage and which to exclude. Individual files, directories, wildcards, globstars, and exclusions are accepted. See [Snapcraft filesets](https://snapcraft.io/docs/snapcraft-filesets) to learn more about the format.\n\nThe defaults can be found in [snap.ts](https://github.com/electron-userland/electron-builder/blob/master/packages/app-builder-lib/templates/snap/snapcraft.yaml#L29)." }, "artifactName": { - "description": "The [artifact file name template](/configuration/configuration#artifact-file-name-template).", + "description": "The [artifact file name template](./configuration.md#artifact-file-name-template).", "type": [ "null", "string" @@ -5447,7 +5447,7 @@ "description": "The type of [confinement](https://snapcraft.io/docs/reference/confinement) supported by the snap." }, "description": { - "description": "As [description](/configuration/configuration#Metadata-description) from application package.json, but allows you to specify different for Linux.", + "description": "As [description](./configuration.md#Metadata-description) from application package.json, but allows you to specify different for Linux.", "type": [ "null", "string" @@ -5636,7 +5636,7 @@ "description": "The list of Ubuntu packages to use that are needed to support the `app` part creation. Like `depends` for `deb`.\nDefaults to `[\"libnspr4\", \"libnss3\", \"libxss1\", \"libappindicator3-1\", \"libsecret-1-0\"]`.\n\nIf list contains `default`, it will be replaced to default list, so, `[\"default\", \"foo\"]` can be used to add custom package `foo` in addition to defaults." }, "summary": { - "description": "The 78 character long summary. Defaults to [productName](/configuration/configuration#Configuration-productName).", + "description": "The 78 character long summary. Defaults to [productName](./configuration.md#Configuration-productName).", "type": [ "null", "string" @@ -5835,7 +5835,7 @@ "additionalProperties": false, "properties": { "artifactName": { - "description": "The [artifact file name template](/configuration/configuration#artifact-file-name-template).", + "description": "The [artifact file name template](./configuration.md#artifact-file-name-template).", "type": [ "null", "string" @@ -5998,7 +5998,7 @@ ] }, "artifactName": { - "description": "The [artifact file name template](/configuration/configuration#artifact-file-name-template). Defaults to `${productName}-${version}.${ext}` (some target can have other defaults, see corresponding options).", + "description": "The [artifact file name template](./configuration.md#artifact-file-name-template). Defaults to `${productName}-${version}.${ext}` (some target can have other defaults, see corresponding options).", "type": [ "null", "string" @@ -6034,7 +6034,7 @@ ] } ], - "description": "A [glob patterns](/file-patterns) relative to the [app directory](#MetadataDirectories-app), which specifies which files to unpack when creating the [asar](http://electron.atom.io/docs/tutorial/application-packaging/) archive." + "description": "A [glob patterns](./file-patterns.md) relative to the [app directory](#MetadataDirectories-app), which specifies which files to unpack when creating the [asar](http://electron.atom.io/docs/tutorial/application-packaging/) archive." }, "azureSignOptions": { "anyOf": [ @@ -6048,14 +6048,14 @@ "description": "Options for usage of Azure Trusted Signing (beta)" }, "certificateFile": { - "description": "The path to the *.pfx certificate you want to sign with. Please use it only if you cannot use env variable `CSC_LINK` (`WIN_CSC_LINK`) for some reason.\nPlease see [Code Signing](/code-signing).", + "description": "The path to the *.pfx certificate you want to sign with. Please use it only if you cannot use env variable `CSC_LINK` (`WIN_CSC_LINK`) for some reason.\nPlease see [Code Signing](./code-signing.md).", "type": [ "null", "string" ] }, "certificatePassword": { - "description": "The password to the certificate provided in `certificateFile`. Please use it only if you cannot use env variable `CSC_KEY_PASSWORD` (`WIN_CSC_KEY_PASSWORD`) for some reason.\nPlease see [Code Signing](/code-signing).", + "description": "The password to the certificate provided in `certificateFile`. Please use it only if you cannot use env variable `CSC_KEY_PASSWORD` (`WIN_CSC_KEY_PASSWORD`) for some reason.\nPlease see [Code Signing](./code-signing.md).", "type": [ "null", "string" @@ -6114,7 +6114,7 @@ }, "disableDefaultIgnoredFiles": { "default": false, - "description": "Whether to exclude all default ignored files(https://www.electron.build/configuration/contents#files) and options. Defaults to `false`.", + "description": "Whether to exclude all default ignored files(https://www.electron.build/contents#files) and options. Defaults to `false`.", "type": [ "null", "boolean" @@ -6135,7 +6135,7 @@ "description": "The electron locales to keep. By default, all Electron locales used as-is." }, "electronUpdaterCompatibility": { - "description": "The [electron-updater compatibility](/auto-update#compatibility) semver range.", + "description": "The [electron-updater compatibility](./auto-update.md#compatibility) semver range.", "type": [ "null", "string" @@ -6458,7 +6458,7 @@ } ], "default": "nsis", - "description": "The target package type: list of `nsis`, `nsis-web` (Web installer), `portable` ([portable](/configuration/nsis#portable) app without installation), `appx`, `msi`, `msi-wrapped`, `squirrel`, `7z`, `zip`, `tar.xz`, `tar.lz`, `tar.gz`, `tar.bz2`, `dir`.\nAppX package can be built only on Windows 10.\n\nTo use Squirrel.Windows please install `electron-builder-squirrel-windows` dependency." + "description": "The target package type: list of `nsis`, `nsis-web` (Web installer), `portable` ([portable]./nsis.md#portable) app without installation), `appx`, `msi`, `msi-wrapped`, `squirrel`, `7z`, `zip`, `tar.xz`, `tar.lz`, `tar.gz`, `tar.bz2`, `dir`.\nAppX package can be built only on Windows 10.\n\nTo use Squirrel.Windows please install `electron-builder-squirrel-windows` dependency." }, "timeStampServer": { "default": "http://timestamp.digicert.com", @@ -6487,14 +6487,14 @@ ] }, "certificateFile": { - "description": "The path to the *.pfx certificate you want to sign with. Please use it only if you cannot use env variable `CSC_LINK` (`WIN_CSC_LINK`) for some reason.\nPlease see [Code Signing](/code-signing).", + "description": "The path to the *.pfx certificate you want to sign with. Please use it only if you cannot use env variable `CSC_LINK` (`WIN_CSC_LINK`) for some reason.\nPlease see [Code Signing](./code-signing.md).", "type": [ "null", "string" ] }, "certificatePassword": { - "description": "The password to the certificate provided in `certificateFile`. Please use it only if you cannot use env variable `CSC_KEY_PASSWORD` (`WIN_CSC_KEY_PASSWORD`) for some reason.\nPlease see [Code Signing](/code-signing).", + "description": "The password to the certificate provided in `certificateFile`. Please use it only if you cannot use env variable `CSC_KEY_PASSWORD` (`WIN_CSC_KEY_PASSWORD`) for some reason.\nPlease see [Code Signing](./code-signing.md).", "type": [ "null", "string" @@ -6724,7 +6724,7 @@ "description": "The function (or path to file or module id) to be run on artifact build start." }, "artifactName": { - "description": "The [artifact file name template](/configuration/configuration#artifact-file-name-template). Defaults to `${productName}-${version}.${ext}` (some target can have other defaults, see corresponding options).", + "description": "The [artifact file name template](./configuration.md#artifact-file-name-template). Defaults to `${productName}-${version}.${ext}` (some target can have other defaults, see corresponding options).", "type": [ "null", "string" @@ -6760,7 +6760,7 @@ ] } ], - "description": "A [glob patterns](/file-patterns) relative to the [app directory](#MetadataDirectories-app), which specifies which files to unpack when creating the [asar](http://electron.atom.io/docs/tutorial/application-packaging/) archive." + "description": "A [glob patterns](./file-patterns.md) relative to the [app directory](#MetadataDirectories-app), which specifies which files to unpack when creating the [asar](http://electron.atom.io/docs/tutorial/application-packaging/) archive." }, "beforeBuild": { "anyOf": [ @@ -6877,7 +6877,7 @@ }, "disableDefaultIgnoredFiles": { "default": false, - "description": "Whether to exclude all default ignored files(https://www.electron.build/configuration/contents#files) and options. Defaults to `false`.", + "description": "Whether to exclude all default ignored files(https://www.electron.build/contents#files) and options. Defaults to `false`.", "type": [ "null", "boolean" @@ -6941,7 +6941,7 @@ "description": "The electron locales to keep. By default, all Electron locales used as-is." }, "electronUpdaterCompatibility": { - "description": "The [electron-updater compatibility](/auto-update#compatibility) semver range.", + "description": "The [electron-updater compatibility](./auto-update.md#compatibility) semver range.", "type": [ "null", "string" diff --git a/packages/app-builder-lib/src/configuration.ts b/packages/app-builder-lib/src/configuration.ts index 80f381c68af..f4187cd8c1e 100644 --- a/packages/app-builder-lib/src/configuration.ts +++ b/packages/app-builder-lib/src/configuration.ts @@ -315,7 +315,7 @@ export interface MetadataDirectories { readonly buildResources?: string | null /** - * The output directory. [File macros](/file-patterns#file-macros) are supported. + * The output directory. [File macros](./file-patterns.md#file-macros) are supported. * @default dist */ readonly output?: string | null diff --git a/packages/app-builder-lib/src/core.ts b/packages/app-builder-lib/src/core.ts index 99c15b8843f..826c2fd63e8 100644 --- a/packages/app-builder-lib/src/core.ts +++ b/packages/app-builder-lib/src/core.ts @@ -93,7 +93,7 @@ export abstract class Target { export interface TargetSpecificOptions { /** - The [artifact file name template](/configuration/configuration#artifact-file-name-template). + The [artifact file name template](./configuration.md#artifact-file-name-template). */ readonly artifactName?: string | null diff --git a/packages/app-builder-lib/src/errorMessages.ts b/packages/app-builder-lib/src/errorMessages.ts index 0b75fba04b8..0ff65f7f90a 100644 --- a/packages/app-builder-lib/src/errorMessages.ts +++ b/packages/app-builder-lib/src/errorMessages.ts @@ -3,5 +3,5 @@ export const authorEmailIsMissed = `Please specify author 'email' in the applica See https://docs.npmjs.com/files/package.json#people-fields-author-contributors It is required to set Linux .deb package maintainer. Or you can set maintainer in the custom linux options. -(see https://www.electron.build/configuration/linux). +(see https://www.electron.build/linux). ` diff --git a/packages/app-builder-lib/src/options/AppXOptions.ts b/packages/app-builder-lib/src/options/AppXOptions.ts index d5e2a3e9932..1a37def4b7f 100644 --- a/packages/app-builder-lib/src/options/AppXOptions.ts +++ b/packages/app-builder-lib/src/options/AppXOptions.ts @@ -19,7 +19,7 @@ export interface AppXOptions extends TargetSpecificOptions { readonly displayName?: string | null /** - * The name. Corresponds to [Identity.Name](https://msdn.microsoft.com/en-us/library/windows/apps/br211441.aspx). Defaults to the [application name](/configuration/configuration#Metadata-name). + * The name. Corresponds to [Identity.Name](https://msdn.microsoft.com/en-us/library/windows/apps/br211441.aspx). Defaults to the [application name](./configuration.md#Metadata-name). */ readonly identityName?: string | null diff --git a/packages/app-builder-lib/src/options/FileAssociation.ts b/packages/app-builder-lib/src/options/FileAssociation.ts index 4be4e9c62be..68d1afc5879 100644 --- a/packages/app-builder-lib/src/options/FileAssociation.ts +++ b/packages/app-builder-lib/src/options/FileAssociation.ts @@ -3,7 +3,7 @@ * * macOS (corresponds to [CFBundleDocumentTypes](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/CoreFoundationKeys.html#//apple_ref/doc/uid/20001431-101685)), NSIS, and MSI only. * - * On Windows (NSIS) works only if [nsis.perMachine](https://electron.build/configuration/configuration#NsisOptions-perMachine) is set to `true`. + * On Windows (NSIS) works only if [nsis.perMachine](https://electron.build./configuration.md#NsisOptions-perMachine) is set to `true`. */ export interface FileAssociation { /** diff --git a/packages/app-builder-lib/src/options/PlatformSpecificBuildOptions.ts b/packages/app-builder-lib/src/options/PlatformSpecificBuildOptions.ts index 1f23932a8c2..70843371428 100644 --- a/packages/app-builder-lib/src/options/PlatformSpecificBuildOptions.ts +++ b/packages/app-builder-lib/src/options/PlatformSpecificBuildOptions.ts @@ -11,7 +11,7 @@ export interface FileSet { */ to?: string /** - * The [glob patterns](/file-patterns). + * The [glob patterns](./file-patterns.md). */ filter?: Array | string } @@ -35,7 +35,7 @@ export interface PlatformSpecificBuildOptions extends TargetSpecificOptions { readonly appId?: string | null /** - * The [artifact file name template](/configuration/configuration#artifact-file-name-template). Defaults to `${productName}-${version}.${ext}` (some target can have other defaults, see corresponding options). + * The [artifact file name template](./configuration.md#artifact-file-name-template). Defaults to `${productName}-${version}.${ext}` (some target can have other defaults, see corresponding options). */ readonly artifactName?: string | null @@ -51,7 +51,7 @@ export interface PlatformSpecificBuildOptions extends TargetSpecificOptions { readonly compression?: CompressionLevel | null /** - * Whether to exclude all default ignored files(https://www.electron.build/configuration/contents#files) and options. Defaults to `false`. + * Whether to exclude all default ignored files(https://www.electron.build/contents#files) and options. Defaults to `false`. * * @default false */ @@ -70,7 +70,7 @@ export interface PlatformSpecificBuildOptions extends TargetSpecificOptions { readonly asar?: AsarOptions | boolean | null /** - * A [glob patterns](/file-patterns) relative to the [app directory](#MetadataDirectories-app), which specifies which files to unpack when creating the [asar](http://electron.atom.io/docs/tutorial/application-packaging/) archive. + * A [glob patterns](./file-patterns.md) relative to the [app directory](#MetadataDirectories-app), which specifies which files to unpack when creating the [asar](http://electron.atom.io/docs/tutorial/application-packaging/) archive. */ readonly asarUnpack?: Array | string | null @@ -97,7 +97,7 @@ export interface PlatformSpecificBuildOptions extends TargetSpecificOptions { readonly forceCodeSigning?: boolean /** - * The [electron-updater compatibility](/auto-update#compatibility) semver range. + * The [electron-updater compatibility](./auto-update.md#compatibility) semver range. */ readonly electronUpdaterCompatibility?: string | null diff --git a/packages/app-builder-lib/src/options/SnapOptions.ts b/packages/app-builder-lib/src/options/SnapOptions.ts index 764e312d774..028a0cfcf41 100644 --- a/packages/app-builder-lib/src/options/SnapOptions.ts +++ b/packages/app-builder-lib/src/options/SnapOptions.ts @@ -19,7 +19,7 @@ export interface SnapOptions extends CommonLinuxOptions, TargetSpecificOptions { readonly environment?: { [key: string]: string } | null /** - * The 78 character long summary. Defaults to [productName](/configuration/configuration#Configuration-productName). + * The 78 character long summary. Defaults to [productName](./configuration.md#Configuration-productName). */ readonly summary?: string | null diff --git a/packages/app-builder-lib/src/options/linuxOptions.ts b/packages/app-builder-lib/src/options/linuxOptions.ts index 2e3ff83ba33..6f9a732c196 100644 --- a/packages/app-builder-lib/src/options/linuxOptions.ts +++ b/packages/app-builder-lib/src/options/linuxOptions.ts @@ -4,7 +4,7 @@ export interface LinuxConfiguration extends CommonLinuxOptions, PlatformSpecific /** * Target package type: list of `AppImage`, `flatpak`, `snap`, `deb`, `rpm`, `freebsd`, `pacman`, `p5p`, `apk`, `7z`, `zip`, `tar.xz`, `tar.lz`, `tar.gz`, `tar.bz2`, `dir`. * - * electron-builder [docker image](/multi-platform-build#docker) can be used to build Linux targets on any platform. + * electron-builder [docker image](./multi-platform-build.md#docker) can be used to build Linux targets on any platform. * * Please [do not put an AppImage into another archive](https://github.com/probonopd/AppImageKit/wiki/Creating-AppImages#common-mistake) like a .zip or .tar.gz. * @default AppImage @@ -12,17 +12,17 @@ export interface LinuxConfiguration extends CommonLinuxOptions, PlatformSpecific readonly target?: TargetConfigType /** - * The maintainer. Defaults to [author](/configuration/configuration#Metadata-author). + * The maintainer. Defaults to [author](./configuration.md#Metadata-author). */ readonly maintainer?: string | null /** - * The vendor. Defaults to [author](/configuration/configuration#Metadata-author). + * The vendor. Defaults to [author](./configuration.md#Metadata-author). */ readonly vendor?: string | null /** - * The path to icon set directory or one png file, relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory. The icon filename must contain the size (e.g. 32x32.png) of the icon. + * The path to icon set directory or one png file, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory. The icon filename must contain the size (e.g. 32x32.png) of the icon. * By default will be generated automatically based on the macOS icns file. */ readonly icon?: string @@ -41,7 +41,7 @@ export interface CommonLinuxOptions { readonly synopsis?: string | null /** - * As [description](/configuration/configuration#Metadata-description) from application package.json, but allows you to specify different for Linux. + * As [description](./configuration.md#Metadata-description) from application package.json, but allows you to specify different for Linux. */ readonly description?: string | null diff --git a/packages/app-builder-lib/src/options/macOptions.ts b/packages/app-builder-lib/src/options/macOptions.ts index 3c6f0bae26b..87597c54ac8 100644 --- a/packages/app-builder-lib/src/options/macOptions.ts +++ b/packages/app-builder-lib/src/options/macOptions.ts @@ -19,8 +19,8 @@ export interface MacConfiguration extends PlatformSpecificBuildOptions { readonly target?: Array | MacOsTargetName | TargetConfiguration | null /** - * The name of certificate to use when signing. Consider using environment variables [CSC_LINK or CSC_NAME](/code-signing) instead of specifying this option. - * MAS installer identity is specified in the [mas](/configuration/mas). + * The name of certificate to use when signing. Consider using environment variables [CSC_LINK or CSC_NAME](./code-signing.md) instead of specifying this option. + * MAS installer identity is specified in the [mas](./mas.md). */ readonly identity?: string | null @@ -32,7 +32,7 @@ export interface MacConfiguration extends PlatformSpecificBuildOptions { /** * The path to entitlements file for signing the app. `build/entitlements.mac.plist` will be used if exists (it is a recommended way to set). - * MAS entitlements is specified in the [mas](/configuration/mas). + * MAS entitlements is specified in the [mas](./mas.md). * See [this folder in osx-sign's repository](https://github.com/electron/osx-sign/tree/main/entitlements) for examples. * Be aware that your app may crash if the right entitlements are not set like `com.apple.security.cs.allow-jit` for example on arm64 builds with Electron 20+. * See [Signing and Notarizing macOS Builds from the Electron documentation](https://www.electronjs.org/docs/latest/tutorial/code-signing#signing--notarizing-macos-builds) for more information. @@ -256,7 +256,7 @@ export interface DmgOptions extends TargetSpecificOptions { backgroundColor?: string | null /** - * The path to DMG icon (volume icon), which will be shown when mounted, relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory. + * The path to DMG icon (volume icon), which will be shown when mounted, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory. * Defaults to the application icon (`build/icon.icns`). */ icon?: string | null diff --git a/packages/app-builder-lib/src/options/pkgOptions.ts b/packages/app-builder-lib/src/options/pkgOptions.ts index 3074a12b1e5..cda9f3a8fa8 100644 --- a/packages/app-builder-lib/src/options/pkgOptions.ts +++ b/packages/app-builder-lib/src/options/pkgOptions.ts @@ -58,7 +58,7 @@ export interface PkgOptions extends TargetSpecificOptions { readonly allowRootDirectory?: boolean | null /** - * The name of certificate to use when signing. Consider using environment variables [CSC_LINK or CSC_NAME](/code-signing) instead of specifying this option. + * The name of certificate to use when signing. Consider using environment variables [CSC_LINK or CSC_NAME](./code-signing.md) instead of specifying this option. */ readonly identity?: string | null diff --git a/packages/app-builder-lib/src/options/winOptions.ts b/packages/app-builder-lib/src/options/winOptions.ts index 24dff95a8da..8bda04c261e 100644 --- a/packages/app-builder-lib/src/options/winOptions.ts +++ b/packages/app-builder-lib/src/options/winOptions.ts @@ -3,7 +3,7 @@ import { CustomWindowsSign } from "../codeSign/windowsSignToolManager" export interface WindowsConfiguration extends PlatformSpecificBuildOptions { /** - * The target package type: list of `nsis`, `nsis-web` (Web installer), `portable` ([portable](/configuration/nsis#portable) app without installation), `appx`, `msi`, `msi-wrapped`, `squirrel`, `7z`, `zip`, `tar.xz`, `tar.lz`, `tar.gz`, `tar.bz2`, `dir`. + * The target package type: list of `nsis`, `nsis-web` (Web installer), `portable` ([portable]./nsis.md#portable) app without installation), `appx`, `msi`, `msi-wrapped`, `squirrel`, `7z`, `zip`, `tar.xz`, `tar.lz`, `tar.gz`, `tar.bz2`, `dir`. * AppX package can be built only on Windows 10. * * To use Squirrel.Windows please install `electron-builder-squirrel-windows` dependency. @@ -35,13 +35,13 @@ export interface WindowsConfiguration extends PlatformSpecificBuildOptions { readonly sign?: CustomWindowsSign | string | null /** * The path to the *.pfx certificate you want to sign with. Please use it only if you cannot use env variable `CSC_LINK` (`WIN_CSC_LINK`) for some reason. - * Please see [Code Signing](/code-signing). + * Please see [Code Signing](./code-signing.md). * @deprecated Please use {@link signtoolOptions.certificateFile} */ readonly certificateFile?: string | null /** * The password to the certificate provided in `certificateFile`. Please use it only if you cannot use env variable `CSC_KEY_PASSWORD` (`WIN_CSC_KEY_PASSWORD`) for some reason. - * Please see [Code Signing](/code-signing). + * Please see [Code Signing](./code-signing.md). * @deprecated Please use {@link signtoolOptions.certificatePassword} */ readonly certificatePassword?: string | null @@ -143,13 +143,13 @@ export interface WindowsSigntoolConfiguration { /** * The path to the *.pfx certificate you want to sign with. Please use it only if you cannot use env variable `CSC_LINK` (`WIN_CSC_LINK`) for some reason. - * Please see [Code Signing](/code-signing). + * Please see [Code Signing](./code-signing.md). */ readonly certificateFile?: string | null /** * The password to the certificate provided in `certificateFile`. Please use it only if you cannot use env variable `CSC_KEY_PASSWORD` (`WIN_CSC_KEY_PASSWORD`) for some reason. - * Please see [Code Signing](/code-signing). + * Please see [Code Signing](./code-signing.md). */ readonly certificatePassword?: string | null diff --git a/packages/app-builder-lib/src/publish/BitbucketPublisher.ts b/packages/app-builder-lib/src/publish/BitbucketPublisher.ts index 59d3fb9040b..c6ea059de7a 100644 --- a/packages/app-builder-lib/src/publish/BitbucketPublisher.ts +++ b/packages/app-builder-lib/src/publish/BitbucketPublisher.ts @@ -22,7 +22,7 @@ export class BitbucketPublisher extends HttpPublisher { const username = info.username || process.env.BITBUCKET_USERNAME || null if (isEmptyOrSpaces(token)) { - throw new InvalidConfigurationError(`Bitbucket token is not set using env "BITBUCKET_TOKEN" (see https://www.electron.build/configuration/publish#BitbucketOptions)`) + throw new InvalidConfigurationError(`Bitbucket token is not set using env "BITBUCKET_TOKEN" (see https://www.electron.build/publish#BitbucketOptions)`) } if (isEmptyOrSpaces(username)) { diff --git a/packages/app-builder-lib/src/publish/KeygenPublisher.ts b/packages/app-builder-lib/src/publish/KeygenPublisher.ts index 14be6f4c336..dbb5dd4b806 100644 --- a/packages/app-builder-lib/src/publish/KeygenPublisher.ts +++ b/packages/app-builder-lib/src/publish/KeygenPublisher.ts @@ -91,7 +91,7 @@ export class KeygenPublisher extends HttpPublisher { const token = process.env.KEYGEN_TOKEN if (isEmptyOrSpaces(token)) { - throw new InvalidConfigurationError(`Keygen token is not set using env "KEYGEN_TOKEN" (see https://www.electron.build/configuration/publish#KeygenOptions)`) + throw new InvalidConfigurationError(`Keygen token is not set using env "KEYGEN_TOKEN" (see https://www.electron.build/publish#KeygenOptions)`) } this.info = info diff --git a/packages/app-builder-lib/src/publish/PublishManager.ts b/packages/app-builder-lib/src/publish/PublishManager.ts index 1e39e8aca87..853ed343fb8 100644 --- a/packages/app-builder-lib/src/publish/PublishManager.ts +++ b/packages/app-builder-lib/src/publish/PublishManager.ts @@ -545,7 +545,7 @@ async function getResolvedPublishConfig( return info } - const message = `Cannot detect repository by .git/config. Please specify "repository" in the package.json (https://docs.npmjs.com/files/package.json#repository).\nPlease see https://electron.build/configuration/publish` + const message = `Cannot detect repository by .git/config. Please specify "repository" in the package.json (https://docs.npmjs.com/files/package.json#repository).\nPlease see https://electron.build/publish` if (errorIfCannot) { throw new Error(message) } else { diff --git a/packages/app-builder-lib/src/publish/s3/spacesPublisher.ts b/packages/app-builder-lib/src/publish/s3/spacesPublisher.ts index d9826c0f191..c46cb07f1f1 100644 --- a/packages/app-builder-lib/src/publish/s3/spacesPublisher.ts +++ b/packages/app-builder-lib/src/publish/s3/spacesPublisher.ts @@ -16,10 +16,10 @@ export default class SpacesPublisher extends BaseS3Publisher { // eslint-disable-next-line @typescript-eslint/no-unused-vars static checkAndResolveOptions(options: SpacesOptions, channelFromAppVersion: string | null, errorIfCannot: boolean) { if (options.name == null) { - throw new InvalidConfigurationError(`Please specify "name" for "spaces" publish provider (see https://www.electron.build/configuration/publish#spacesoptions)`) + throw new InvalidConfigurationError(`Please specify "name" for "spaces" publish provider (see https://www.electron.build/publish#spacesoptions)`) } if (options.region == null) { - throw new InvalidConfigurationError(`Please specify "region" for "spaces" publish provider (see https://www.electron.build/configuration/publish#spacesoptions)`) + throw new InvalidConfigurationError(`Please specify "region" for "spaces" publish provider (see https://www.electron.build/publish#spacesoptions)`) } if (options.channel == null && channelFromAppVersion != null) { @@ -41,10 +41,10 @@ export default class SpacesPublisher extends BaseS3Publisher { const accessKey = process.env.DO_KEY_ID const secretKey = process.env.DO_SECRET_KEY if (isEmptyOrSpaces(accessKey)) { - throw new InvalidConfigurationError("Please set env DO_KEY_ID (see https://www.electron.build/configuration/publish#spacesoptions)") + throw new InvalidConfigurationError("Please set env DO_KEY_ID (see https://www.electron.build/publish#spacesoptions)") } if (isEmptyOrSpaces(secretKey)) { - throw new InvalidConfigurationError("Please set env DO_SECRET_KEY (see https://www.electron.build/configuration/publish#spacesoptions)") + throw new InvalidConfigurationError("Please set env DO_SECRET_KEY (see https://www.electron.build/publish#spacesoptions)") } args.push("--accessKey", accessKey) args.push("--secretKey", secretKey) diff --git a/packages/app-builder-lib/src/targets/FpmTarget.ts b/packages/app-builder-lib/src/targets/FpmTarget.ts index f15b7130026..c9efaa00e80 100644 --- a/packages/app-builder-lib/src/targets/FpmTarget.ts +++ b/packages/app-builder-lib/src/targets/FpmTarget.ts @@ -76,7 +76,7 @@ export default class FpmTarget extends Target { const projectUrl = await packager.appInfo.computePackageUrl() const errors: Array = [] if (projectUrl == null) { - errors.push("Please specify project homepage, see https://electron.build/configuration/configuration#Metadata-homepage") + errors.push("Please specify project homepage, see https://electron.build./configuration.md#Metadata-homepage") } const options = this.options diff --git a/packages/app-builder-lib/src/targets/LinuxTargetHelper.ts b/packages/app-builder-lib/src/targets/LinuxTargetHelper.ts index 96a52023fa9..248b939b4ac 100644 --- a/packages/app-builder-lib/src/targets/LinuxTargetHelper.ts +++ b/packages/app-builder-lib/src/targets/LinuxTargetHelper.ts @@ -180,7 +180,7 @@ export class LinuxTargetHelper { log.warn( { reason: "linux.category is not set and cannot map from macOS", - docs: "https://www.electron.build/configuration/linux", + docs: "https://www.electron.build/linux", }, 'application Linux category is set to default "Utility"' ) diff --git a/packages/app-builder-lib/src/targets/nsis/nsisOptions.ts b/packages/app-builder-lib/src/targets/nsis/nsisOptions.ts index f340cae1fb1..caa1a3010d2 100644 --- a/packages/app-builder-lib/src/targets/nsis/nsisOptions.ts +++ b/packages/app-builder-lib/src/targets/nsis/nsisOptions.ts @@ -33,7 +33,7 @@ export interface CommonNsisOptions { readonly unicode?: boolean /** - * See [GUID vs Application Name](../configuration/nsis#guid-vs-application-name). + * See [GUID vs Application Name](./nsis.md#guid-vs-application-name). */ readonly guid?: string | null @@ -100,32 +100,32 @@ export interface NsisOptions extends CommonNsisOptions, CommonWindowsInstallerCo readonly removeDefaultUninstallWelcomePage?: boolean /** - * The path to installer icon, relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory. + * The path to installer icon, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory. * Defaults to `build/installerIcon.ico` or application icon. */ readonly installerIcon?: string | null /** - * The path to uninstaller icon, relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory. + * The path to uninstaller icon, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory. * Defaults to `build/uninstallerIcon.ico` or application icon. */ readonly uninstallerIcon?: string | null /** - * *assisted installer only.* `MUI_HEADERIMAGE`, relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory. + * *assisted installer only.* `MUI_HEADERIMAGE`, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory. * @default build/installerHeader.bmp */ readonly installerHeader?: string | null /** - * *one-click installer only.* The path to header icon (above the progress bar), relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory. + * *one-click installer only.* The path to header icon (above the progress bar), relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory. * Defaults to `build/installerHeaderIcon.ico` or application icon. */ readonly installerHeaderIcon?: string | null /** - * *assisted installer only.* `MUI_WELCOMEFINISHPAGE_BITMAP`, relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory. + * *assisted installer only.* `MUI_WELCOMEFINISHPAGE_BITMAP`, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory. * Defaults to `build/installerSidebar.bmp` or `${NSISDIR}\\Contrib\\Graphics\\Wizard\\nsis3-metro.bmp`. Image size 164 × 314 pixels. */ readonly installerSidebar?: string | null /** - * *assisted installer only.* `MUI_UNWELCOMEFINISHPAGE_BITMAP`, relative to the [build resources](/configuration/configuration#MetadataDirectories-buildResources) or to the project directory. + * *assisted installer only.* `MUI_UNWELCOMEFINISHPAGE_BITMAP`, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory. * Defaults to `installerSidebar` option or `build/uninstallerSidebar.bmp` or `build/installerSidebar.bmp` or `${NSISDIR}\\Contrib\\Graphics\\Wizard\\nsis3-metro.bmp` */ readonly uninstallerSidebar?: string | null @@ -155,7 +155,7 @@ export interface NsisOptions extends CommonNsisOptions, CommonWindowsInstallerCo readonly license?: string | null /** - * The [artifact file name template](/configuration/configuration#artifact-file-name-template). Defaults to `${productName} Setup ${version}.${ext}`. + * The [artifact file name template](./configuration.md#artifact-file-name-template). Defaults to `${productName} Setup ${version}.${ext}`. */ readonly artifactName?: string | null @@ -241,7 +241,7 @@ export interface NsisWebOptions extends NsisOptions { readonly appPackageUrl?: string | null /** - * The [artifact file name template](/configuration/configuration#artifact-file-name-template). Defaults to `${productName} Web Setup ${version}.${ext}`. + * The [artifact file name template](./configuration.md#artifact-file-name-template). Defaults to `${productName} Web Setup ${version}.${ext}`. */ readonly artifactName?: string | null } diff --git a/packages/app-builder-lib/src/util/config/config.ts b/packages/app-builder-lib/src/util/config/config.ts index c490805df7b..b6e258f37d9 100644 --- a/packages/app-builder-lib/src/util/config/config.ts +++ b/packages/app-builder-lib/src/util/config/config.ts @@ -244,12 +244,12 @@ export async function validateConfiguration(config: Configuration, debugLogger: } const site = "https://www.electron.build" - let url = `${site}/configuration/configuration` + let url = `${site}/configuration` const targets = new Set(["mac", "dmg", "pkg", "mas", "win", "nsis", "appx", "linux", "appimage", "snap"]) const dataPath: string = error.dataPath == null ? null : error.dataPath const targetPath = dataPath.startsWith(".") ? dataPath.substr(1).toLowerCase() : null if (targetPath != null && targets.has(targetPath)) { - url = `${site}/configuration/${targetPath}` + url = `${site}/${targetPath}` } return `${formattedError}\n How to fix: diff --git a/packages/builder-util-runtime/src/publishOptions.ts b/packages/builder-util-runtime/src/publishOptions.ts index 2ee3353071d..48ac8a6db85 100644 --- a/packages/builder-util-runtime/src/publishOptions.ts +++ b/packages/builder-util-runtime/src/publishOptions.ts @@ -112,12 +112,12 @@ export interface GithubOptions extends PublishConfiguration { readonly protocol?: "https" | "http" | null /** - * The access token to support auto-update from private github repositories. Never specify it in the configuration files. Only for [setFeedURL](/auto-update#appupdatersetfeedurloptions). + * The access token to support auto-update from private github repositories. Never specify it in the configuration files. Only for [setFeedURL](./auto-update.md#appupdatersetfeedurloptions). */ readonly token?: string | null /** - * Whether to use private github auto-update provider if `GH_TOKEN` environment variable is defined. See [Private GitHub Update Repo](/auto-update#private-github-update-repo). + * Whether to use private github auto-update provider if `GH_TOKEN` environment variable is defined. See [Private GitHub Update Repo](./auto-update.md#private-github-update-repo). */ readonly private?: boolean | null @@ -143,7 +143,7 @@ export function githubUrl(options: GithubOptions, defaultHost = "github.com") { /** * Generic (any HTTP(S) server) options. - * In all publish options [File Macros](/file-patterns#file-macros) are supported. + * In all publish options [File Macros](./file-patterns.md#file-macros) are supported. */ export interface GenericServerOptions extends PublishConfiguration { /** diff --git a/packages/builder-util-runtime/src/updateInfo.ts b/packages/builder-util-runtime/src/updateInfo.ts index 408c62a9ad5..9a279e7fb0e 100644 --- a/packages/builder-util-runtime/src/updateInfo.ts +++ b/packages/builder-util-runtime/src/updateInfo.ts @@ -70,7 +70,7 @@ export interface UpdateInfo { releaseDate: string /** - * The [staged rollout](/auto-update#staged-rollouts) percentage, 0-100. + * The [staged rollout](./auto-update.md#staged-rollouts) percentage, 0-100. */ readonly stagingPercentage?: number diff --git a/packages/electron-builder-squirrel-windows/src/SquirrelWindowsTarget.ts b/packages/electron-builder-squirrel-windows/src/SquirrelWindowsTarget.ts index a31b7868ddd..f0f273330f6 100644 --- a/packages/electron-builder-squirrel-windows/src/SquirrelWindowsTarget.ts +++ b/packages/electron-builder-squirrel-windows/src/SquirrelWindowsTarget.ts @@ -89,9 +89,7 @@ export default class SquirrelWindowsTarget extends Target { } if (iconUrl == null) { - throw new InvalidConfigurationError( - "squirrelWindows.iconUrl is not specified, please see https://www.electron.build/configuration/squirrel-windows#SquirrelWindowsOptions-iconUrl" - ) + throw new InvalidConfigurationError("squirrelWindows.iconUrl is not specified, please see https://www.electron.build/squirrel-windows#SquirrelWindowsOptions-iconUrl") } } diff --git a/packages/electron-forge-maker-appimage/readme.md b/packages/electron-forge-maker-appimage/readme.md index cb1e46701f3..c65cc78e7df 100644 --- a/packages/electron-forge-maker-appimage/readme.md +++ b/packages/electron-forge-maker-appimage/readme.md @@ -6,4 +6,4 @@ Recommended to build electron-forge project using electron-builder directly. [Publishing](https://www.electron.build/configuration/publish), [Auto Update](https://electron.build/auto-update) and [Code Signing](https://electron.build/code-signing) supported only in this case -(including all other useful [packaging options](https://electron.build/configuration/configuration) like [files](https://electron.build/configuration/configuration#Config-files)). \ No newline at end of file +(including all other useful [packaging options](https://electron.build/configuration/configuration) like [files](https://electron.build./configuration.md#Config-files)). \ No newline at end of file diff --git a/packages/electron-forge-maker-nsis-web/readme.md b/packages/electron-forge-maker-nsis-web/readme.md index a16f9026a01..c837e96bd9d 100644 --- a/packages/electron-forge-maker-nsis-web/readme.md +++ b/packages/electron-forge-maker-nsis-web/readme.md @@ -6,4 +6,4 @@ Recommended to build electron-forge project using electron-builder directly. [Publishing](https://www.electron.build/configuration/publish), [Auto Update](https://electron.build/auto-update) and [Code Signing](https://electron.build/code-signing) supported only in this case -(including all other useful [packaging options](https://electron.build/configuration/configuration) like [files](https://electron.build/configuration/configuration#Config-files)). \ No newline at end of file +(including all other useful [packaging options](https://electron.build/configuration/configuration) like [files](https://electron.build./configuration.md#Config-files)). \ No newline at end of file diff --git a/packages/electron-forge-maker-nsis/readme.md b/packages/electron-forge-maker-nsis/readme.md index 2403e34d02a..c0e27581ae2 100644 --- a/packages/electron-forge-maker-nsis/readme.md +++ b/packages/electron-forge-maker-nsis/readme.md @@ -6,4 +6,4 @@ Recommended to build electron-forge project using electron-builder directly. [Publishing](https://www.electron.build/configuration/publish), [Auto Update](https://electron.build/auto-update) and [Code Signing](https://electron.build/code-signing) supported only in this case -(including all other useful [packaging options](https://electron.build/configuration/configuration) like [files](https://electron.build/configuration/configuration#Config-files)). \ No newline at end of file +(including all other useful [packaging options](https://electron.build/configuration/configuration) like [files](https://electron.build./configuration.md#Config-files)). \ No newline at end of file diff --git a/packages/electron-forge-maker-snap/readme.md b/packages/electron-forge-maker-snap/readme.md index a188009b37a..1a2dae28983 100644 --- a/packages/electron-forge-maker-snap/readme.md +++ b/packages/electron-forge-maker-snap/readme.md @@ -6,4 +6,4 @@ Recommended to build electron-forge project using electron-builder directly. [Publishing](https://www.electron.build/configuration/publish), [Auto Update](https://electron.build/auto-update) and [Code Signing](https://electron.build/code-signing) supported only in this case -(including all other useful [packaging options](https://electron.build/configuration/configuration) like [files](https://electron.build/configuration/configuration#Config-files)). \ No newline at end of file +(including all other useful [packaging options](https://electron.build/configuration/configuration) like [files](https://electron.build./configuration.md#Config-files)). \ No newline at end of file diff --git a/packages/electron-updater/src/AppUpdater.ts b/packages/electron-updater/src/AppUpdater.ts index 152a105c05b..6d2ecaddd08 100644 --- a/packages/electron-updater/src/AppUpdater.ts +++ b/packages/electron-updater/src/AppUpdater.ts @@ -257,7 +257,7 @@ export abstract class AppUpdater extends (EventEmitter as new () => TypedEmitter } /** - * Configure update provider. If value is `string`, [GenericServerOptions](/configuration/publish#genericserveroptions) will be set with value as `url`. + * Configure update provider. If value is `string`, [GenericServerOptions](./publish.md#genericserveroptions) will be set with value as `url`. * @param options If you want to override configuration in the `app-update.yml`. */ setFeedURL(options: PublishConfiguration | AllPublishOptions | string) { diff --git a/pages/api/electron-builder.md b/pages/api/electron-builder.md index 6003cb8aecd..fce4f2819b2 100644 --- a/pages/api/electron-builder.md +++ b/pages/api/electron-builder.md @@ -1,5 +1,4 @@ -Developer API only. See [Configuration](../configuration/configuration.md) for user documentation. +Developer API only. See [Configuration](../configuration.md) for user documentation. - +{% include "../electron-builder/globals.md" %} - diff --git a/pages/appimage.md b/pages/appimage.md index 53eaae03f15..005fb0b20df 100644 --- a/pages/appimage.md +++ b/pages/appimage.md @@ -3,5 +3,6 @@ The top-level [appImage](configuration.md#Configuration-appImage) key contains s !!! info "Desktop Integration" Since electron-builder 21 desktop integration is not a part of produced AppImage file. [AppImageLauncher](https://github.com/TheAssassin/AppImageLauncher) is the recommended way to integrate AppImages. +# Configuration {% include "./app-builder-lib.Interface.AppImageOptions.md" %} diff --git a/pages/appx.md b/pages/appx.md index 308d9c6f20d..3386f8882f9 100644 --- a/pages/appx.md +++ b/pages/appx.md @@ -2,9 +2,9 @@ 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 diff --git a/pages/auto-update.md b/pages/auto-update.md index 789b8664d3a..5fb6773f2a2 100644 --- a/pages/auto-update.md +++ b/pages/auto-update.md @@ -1,4 +1,4 @@ -Auto updates are enabled by the `electron-updater` package. Ideally, auto updates are configured to run in a CI pipeline to automatically provision new releases. See [publish configuration](configuration/publish.md) for information on how to configure your local or CI environment for automated deployments. +Auto updates are enabled by the `electron-updater` package. Ideally, auto updates are configured to run in a CI pipeline to automatically provision new releases. See [publish configuration](./publish.md) for information on how to configure your local or CI environment for automated deployments. Auto updates work as follows: @@ -38,7 +38,7 @@ The `electron-updater` package offers a different functionality compared to Elec 1. Install [electron-updater](https://yarn.pm/electron-updater) as an app dependency. -2. Configure the [`publish`](configuration/publish.md) options depending on where you want to host your release files. +2. Configure the [`publish`](./publish.md) options depending on where you want to host your release files. 3. Build your application and check that the build directory contains the metadata `.yml` files next to the built application. For most publish targets, the building step will also upload the files, except for the generic server option, where you have to upload your built releases and metadata manually. @@ -68,7 +68,7 @@ The `electron-updater` package offers a different functionality compared to Elec !!! note 1. Do not call [setFeedURL](#appupdatersetfeedurloptions). electron-builder automatically creates `app-update.yml` file for you on build in the `resources` (this file is internal, you don't need to be aware of it). - 2. `zip` target for macOS is **required** for Squirrel.Mac, otherwise `latest-mac.yml` cannot be created, which causes `autoUpdater` error. Default [target](configuration/mac.md#MacOptions-target) for macOS is `dmg`+`zip`, so there is no need to explicitly specify target. + 2. `zip` target for macOS is **required** for Squirrel.Mac, otherwise `latest-mac.yml` cannot be created, which causes `autoUpdater` error. Default [target](./mac.md#MacOptions-target) for macOS is `dmg`+`zip`, so there is no need to explicitly specify target. ## Examples diff --git a/pages/cli.md b/pages/cli.md index 4b5b7f7f295..b913b6e9eac 100644 --- a/pages/cli.md +++ b/pages/cli.md @@ -67,10 +67,10 @@ Prepend `npx` to sample commands below if you run it from Terminal and not from Without target configuration, electron-builder builds Electron app for current platform and current architecture using default target. * macOS - DMG and ZIP for Squirrel.Mac. -* Windows - [NSIS](configuration/nsis.md). +* Windows - [NSIS]./nsis.md). * Linux: - - if you build on Windows or macOS: [Snap](configuration/snap.md) and [AppImage](configuration/appimage.md) for x64. - - if you build on Linux: [Snap](configuration/snap.md) and [AppImage](configuration/appimage.md) for current architecture. + - if you build on Windows or macOS: [Snap](./snap.md) and [AppImage](./appimage.md) for x64. + - if you build on Linux: [Snap](./snap.md) and [AppImage](./appimage.md) for current architecture. Platforms and archs can be configured or using [CLI args](https://github.com/electron-userland/electron-builder#cli-usage), or in the configuration. @@ -119,6 +119,33 @@ For example, if you don't want to pass `--ia32` and `--x64` flags each time, but arch: universal ``` + electron-builder.config.js + ```js + module.exports = { + "win": { + "target": [ + { + "target": "nsis", + "arch": [ + "x64", + "ia32" + ] + } + ] + }, + "mac": { + "target": [ + { + "target": "dmg", + "arch": [ + "universal" + ] + } + ] + } + } + ``` + and use ``` build -wl diff --git a/pages/code-signing.md b/pages/code-signing.md index 207d31b83da..ee8caa4506b 100644 --- a/pages/code-signing.md +++ b/pages/code-signing.md @@ -31,7 +31,7 @@ To sign an app on Windows, there are two types of certificates: Both certificates work with auto-update. The regular (and often cheaper) Code Signing Certificate shows a warning during installation that goes away once enough users installed your application and you've built up trust. The EV Certificate has more trust and thus works immediately without any warnings. However, it is not possible to export the EV Certificate as it is bound to a physical USB dongle. Thus, you can't export the certificate for signing code on a CI, such as AppVeyor. -If you are using an EV Certificate, you need to provide [win.certificateSubjectName](configuration/win.md#WindowsConfiguration-certificateSubjectName) in your electron-builder configuration. +If you are using an EV Certificate, you need to provide [win.certificateSubjectName](./win.md#WindowsConfiguration-certificateSubjectName) in your electron-builder configuration. If you use Windows 7, please ensure that [PowerShell](https://blogs.technet.microsoft.com/heyscriptingguy/2013/06/02/weekend-scripter-install-powershell-3-0-on-windows-7/) is updated to version 3.0. diff --git a/pages/configuration.md b/pages/configuration.md index 9d993be0305..7931ccee846 100644 --- a/pages/configuration.md +++ b/pages/configuration.md @@ -21,44 +21,44 @@ electron-builder [configuration](#configuration) can be defined Most of the options accept `null` — for example, to explicitly set that DMG icon must be default volume icon from the OS and default rules must be not applied (i.e. use application icon as DMG icon), set `dmg.icon` to `null`. -## Artifact File Name Template +# Artifact File Name Template -`${ext}` macro is supported in addition to [file macros](../file-patterns.md#file-macros). +`${ext}` macro is supported in addition to [file macros](./file-patterns.md#file-macros). -## Environment Variables from File +# Environment Variables from File Env file `electron-builder.env` in the current dir ([example](https://github.com/motdotla/dotenv-expand/blob/1cc80d02e1f8aa749253a04a2061c0fecb9bdb69/tests/.env)). Supported only for CLI usage. -## How to Read Docs +# How to Read Docs * Name of optional property is normal, **required** is bold. * Type is specified after property name: `Array | String`. Union like this means that you can specify or string (`**/*`), or array of strings (`["**/*", "!foo.js"]`). -## Configuration +# Configuration - - - +{% include "./app-builder-lib.Interface.Configuration.md" %} --- -### Overridable per Platform Options +# Overridable per Platform Options Following options can be set also per platform (top-level keys [mac](mac.md), [linux](linux.md) and [win](win.md)) if need. +# Base Configuration + {% include "./app-builder-lib.Interface.PlatformSpecificBuildOptions.md" %} -## Metadata +# Metadata Some standard fields should be defined in the `package.json`. {% include "./app-builder-lib.Interface.Metadata.md" %} -## Proton Native +# Proton Native To package [Proton Native](https://proton-native.js.org/) app, set `protonNodeVersion` option to `current` or specific NodeJS version that you are packaging for. Currently, only macOS and Linux supported. -## Build Version Management +# Build Version Management `CFBundleVersion` (macOS) and `FileVersion` (Windows) will be set automatically to `version.build_number` on CI server (Travis, AppVeyor, CircleCI and Bamboo supported). {% include "./hooks.md" %} diff --git a/pages/contents.md b/pages/contents.md index a5423fd5f5f..7fdb0699827 100644 --- a/pages/contents.md +++ b/pages/contents.md @@ -2,7 +2,7 @@ `Array | String | FileSet` -A [glob patterns](../file-patterns.md) relative to the [app directory](configuration.md#MetadataDirectories-app), which specifies which files to include when copying files to create the package. +A [glob patterns](./file-patterns.md) relative to the [app directory](configuration.md#MetadataDirectories-app), which specifies which files to include when copying files to create the package. Defaults to: ```json @@ -58,7 +58,7 @@ If you don't use two-package.json structure and don't set custom app directory, `String` -The destination path relative to and defaults to: +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`. diff --git a/pages/dmg.md b/pages/dmg.md index 913efec5e23..0d10411c4fe 100644 --- a/pages/dmg.md +++ b/pages/dmg.md @@ -1,8 +1,8 @@ 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 diff --git a/pages/flatpak.md b/pages/flatpak.md index 7793d6e5f5e..e9e6d89867c 100644 --- a/pages/flatpak.md +++ b/pages/flatpak.md @@ -8,9 +8,10 @@ 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" %} - --- diff --git a/pages/icons.md b/pages/icons.md index d5a8de6a5d1..6c613272b94 100644 --- a/pages/icons.md +++ b/pages/icons.md @@ -8,13 +8,13 @@ Files * *Optional* `background.png` (macOS DMG background). * *Optional* `background@2x.png` (macOS DMG Retina background). -need to be placed in the [buildResources](configuration/configuration.md#MetadataDirectories-buildResources) directory (defaults to `build`). All files are optional — but it is important to provide `icon.icns` (or `icon.png`), as otherwise the default Electron icon will be used. +need to be placed in the [buildResources](./configuration.md#MetadataDirectories-buildResources) directory (defaults to `build`). All files are optional — but it is important to provide `icon.icns` (or `icon.png`), as otherwise the default Electron icon will be used. ## Windows (NSIS) * *Optional* `icon.ico` (Windows app icon) or `icon.png`. Icon size should be at least 256x256. -needs to be placed in the [buildResources](configuration/configuration.md#MetadataDirectories-buildResources) directory (defaults to `build`). It is important to provide `icon.ico` (or `icon.png`), as otherwise the default Electron icon will be used. +needs to be placed in the [buildResources](./configuration.md#MetadataDirectories-buildResources) directory (defaults to `build`). It is important to provide `icon.ico` (or `icon.png`), as otherwise the default Electron icon will be used. ## Linux @@ -25,4 +25,4 @@ The filename must contain the size (e.g. `256x256.png`) of the icon). Recommende ## AppX -See [AppX Assets](configuration/appx.md#appx-assets). +See [AppX Assets](./appx.md#appx-assets). diff --git a/pages/index.md b/pages/index.md deleted file mode 100644 index 0d01dc2ebab..00000000000 --- a/pages/index.md +++ /dev/null @@ -1,167 +0,0 @@ -# electron-builder [![npm version](https://img.shields.io/npm/v/electron-builder.svg?label=latest)](https://www.npmjs.com/package/electron-builder) [![downloads per month](https://img.shields.io/npm/dm/electron-builder.svg)](https://yarn.pm/electron-builder) [![donate](https://img.shields.io/badge/donate-donorbox-brightgreen.svg)](https://www.electron.build/donate) -A complete solution to package and build a ready for distribution [Electron](https://electronjs.org), [Proton Native](https://proton-native.js.org/) app for macOS, Windows and Linux with “auto update” support out of the box. :shipit: - -Always looking for community contributions! 👀 Setting up a [dev environment](https://github.com/electron-userland/electron-builder/blob/master/CONTRIBUTING.md) is easy to do 🪩 - -**We condemn Russia’s military aggression against Ukraine. We stand with the people of Ukraine.** - -## Sponsors - - - - - - - - - - - - - -
- -
- WorkFlowy -
- Notes, Tasks, Projects.
All in a Single Place. - -
-
-
- -
- Tidepool -
- Your gateway to understanding your diabetes data - -
- 		-
- -
- Keygen -
- An open, source-available software licensing and distribution API - -
-
-
- -
- ToDesktop -
- ToDesktop: An all-in-one platform for building and releasing Electron apps - -
- 		-
- -
- Dashcam -
- Dashcam: Capture the steps to reproduce any bug with video crash reports for Electron. - -
-
- - -## Documentation - -See the full documentation on [electron.build](https://www.electron.build). - -* NPM packages management: - * [Native application dependencies](https://electron.atom.io/docs/tutorial/using-native-node-modules/) compilation (including [Yarn](http://yarnpkg.com/) support). - * Development dependencies are never included. You don't need to ignore them explicitly. - * [Two package.json structure](https://www.electron.build/tutorials/two-package-structure) is supported, but you are not forced to use it even if you have native production dependencies. -* [Code Signing](https://www.electron.build/code-signing) on a CI server or development machine. -* [Auto Update](https://www.electron.build/auto-update) ready application packaging. -* Numerous target formats: - * All platforms: `7z`, `zip`, `tar.xz`, `tar.7z`, `tar.lz`, `tar.gz`, `tar.bz2`, `dir` (unpacked directory). - * [macOS](https://www.electron.build/configuration/mac): `dmg`, `pkg`, `mas`. - * [Linux](https://www.electron.build/configuration/linux): [AppImage](http://appimage.org), [snap](http://snapcraft.io), debian package (`deb`), `rpm`, `freebsd`, `pacman`, `p5p`, `apk`. - * [Windows](https://www.electron.build/configuration/win): `nsis` (Installer), `nsis-web` (Web installer), `portable` (portable app without installation), AppX (Windows Store), MSI, Squirrel.Windows. -* [Publishing artifacts](https://www.electron.build/configuration/publish) to GitHub Releases, Amazon S3, DigitalOcean Spaces and Bintray. -* Advanced building: - * Pack in a distributable format [already packaged app](https://www.electron.build/#pack-only-in-a-distributable-format). - * Separate [build steps](https://github.com/electron-userland/electron-builder/issues/1102#issuecomment-271845854). - * Build and publish in parallel, using hard links on CI server to reduce IO and disk space usage. - * [electron-compile](https://github.com/electron/electron-compile) support (compile for release-time on the fly on build). -* [Docker](https://www.electron.build/multi-platform-build#docker) images to build Electron app for Linux or Windows on any platform. -* [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) | - -## Installation -[Yarn](http://yarnpkg.com/) is [strongly](https://github.com/electron-userland/electron-builder/issues/1147#issuecomment-276284477) recommended instead of npm. - -`yarn add electron-builder --dev` - -### Note for PNPM - -In order to use with `pnpm`, you'll need to adjust your `.npmrc` to use any one the following approaches in order for your dependencies to be bundled correctly (ref: [#6389](https://github.com/electron-userland/electron-builder/issues/6289#issuecomment-1042620422)): -``` -node-linker=hoisted -``` -``` -public-hoist-pattern=* -``` -``` -shamefully-hoist=true -``` - -Note: Setting shamefully-hoist to true is the same as setting public-hoist-pattern to *. - -### Note for Yarn 3 - -Yarn 3 use PnP by default, but electron-builder still need node-modules(ref: [yarnpkg/berry#4804](https://github.com/yarnpkg/berry/issues/4804#issuecomment-1234407305)). Add configuration in the `.yarnrc.yaml` as follows: -``` -nodeLinker: "node-modules" -``` -will declare to use node-modules instead of PnP. - -## Quick Setup Guide - -[electron-webpack-quick-start](https://github.com/electron-userland/electron-webpack-quick-start) is a recommended way to create a new Electron application. See [Boilerplates](https://www.electron.build/#boilerplates). - -1. Specify the standard fields in the application `package.json` — [name](https://electron.build/configuration/configuration#Metadata-name), `description`, `version` and [author](https://docs.npmjs.com/files/package.json#people-fields-author-contributors). - -2. Specify the [build](https://electron.build/configuration/configuration#build) configuration in the `package.json` as follows: - ```json - "build": { - "appId": "your.id", - "mac": { - "category": "your.app.category.type" - } - } - ``` - See [all options](https://www.electron.build/configuration/configuration). Option [files](https://www.electron.build/configuration/contents#files) to indicate which files should be packed in the final application, including the entry file, maybe required. - You can also use separate configuration files, such as `js`, `ts`, `yml`, and `json`/`json5`. See [read-config-file](https://www.npmjs.com/package/read-config-file) for supported extensions. [JS Example for programmatic API](https://www.electron.build/api/programmatic-usage) - -3. Add [icons](https://www.electron.build/icons). - -4. Add the [scripts](https://docs.npmjs.com/cli/run-script) key to the development `package.json`: - ```json - "scripts": { - "app:dir": "electron-builder --dir", - "app:dist": "electron-builder" - } - ``` - Then you can run `yarn app:dist` (to package in a distributable format (e.g. dmg, windows installer, deb package)) or `yarn app:dir` (only generates the package directory without really packaging it. This is useful for testing purposes). - - To ensure your native dependencies are always matched electron version, simply add script `"postinstall": "electron-builder install-app-deps"` to your `package.json`. - -5. If you have native addons of your own that are part of the application (not as a dependency), set [nodeGypRebuild](https://www.electron.build/configuration/configuration#Configuration-nodeGypRebuild) to `true`. - -Please note that everything is packaged into an asar archive [by default](https://electron.build/configuration/configuration#Configuration-asar). - -For an app that will be shipped to production, you should sign your application. See [Where to buy code signing certificates](https://www.electron.build/code-signing#where-to-buy-code-signing-certificate). - -## Donate - -We do this open source work in our free time. If you'd like us to invest more time on it, please [donate](https://www.electron.build/donate). diff --git a/pages/linux.md b/pages/linux.md index 52e63089509..ee1759f8b20 100644 --- a/pages/linux.md +++ b/pages/linux.md @@ -1,10 +1,6 @@ The top-level [linux](configuration.md#Configuration-linux) key contains set of options instructing electron-builder on how it should build Linux targets. These options applicable for any Linux target. - - - - ---- +# Base Linux Configuration {% include "./app-builder-lib.Interface.LinuxConfiguration.md" %} diff --git a/pages/mac.md b/pages/mac.md index 59afbaddb4f..a9be81b0614 100644 --- a/pages/mac.md +++ b/pages/mac.md @@ -1,13 +1,9 @@ The top-level [mac](configuration.md#Configuration-mac) key contains set of options instructing electron-builder on how it should build macOS targets. These options applicable for any macOS target. ---- +# Configuration {% include "./app-builder-lib.Interface.MacConfiguration.md" %} ---- +# Notarize Configuration {% include "./app-builder-lib.Interface.NotarizeNotaryOptions.md" %} - - - - diff --git a/pages/mas.md b/pages/mas.md index f7cb53395ef..03defd415a4 100644 --- a/pages/mas.md +++ b/pages/mas.md @@ -1,6 +1,7 @@ The top-level [mas](configuration.md#Configuration-mas) key contains set of options instructing electron-builder on how it should build MAS (Mac Application Store) target. Inherits [macOS options](mac.md). - +# Configuration + +{% include "./app-builder-lib.Interface.MasConfiguration.md" %} - diff --git a/pages/nsis.md b/pages/nsis.md index 1fbfc2a6cb4..3259f1c6267 100644 --- a/pages/nsis.md +++ b/pages/nsis.md @@ -2,7 +2,7 @@ The top-level [nsis](configuration.md#Configuration-nsis) key contains set of op These options also applicable for [Web installer](#web-installer), use top-level `nsisWeb` key. ---- +# Configuration {% include "./app-builder-lib.Interface.NsisOptions.md" %} diff --git a/pages/pkg.md b/pages/pkg.md index e9cdbad899e..9f70f218faf 100644 --- a/pages/pkg.md +++ b/pages/pkg.md @@ -1,5 +1,5 @@ The top-level [pkg](configuration.md#Configuration-pkg) key contains set of options instructing electron-builder on how it should build [PKG](https://goo.gl/yVvgF6) (macOS installer component package). - +# Configuration - +{% include "./app-builder-lib.Interface.PkgOptions.md" %} \ No newline at end of file diff --git a/pages/publish.md b/pages/publish.md index a6e241717d6..db7ba6e204e 100644 --- a/pages/publish.md +++ b/pages/publish.md @@ -114,16 +114,31 @@ Detected automatically using: * or `CIRCLE_PROJECT_USERNAME`/`CIRCLE_PROJECT_REPONAME`, * if no env, from `.git/config` origin url. -## Publishers -**Options Available:** -- GenericServerOptions -- GithubOptions -- SnapStoreOptions -- SpacesOptions -- KeygenOptions -- BitbucketOptions -- S3Options - - - - +# Publishers + +# Bitbucket +{% include "./builder-util-runtime.Interface.BitbucketOptions.md" %} + +# Github + +{% include "./builder-util-runtime.Interface.GithubOptions.md" %} + +# Keygen + +{% include "./builder-util-runtime.Interface.KeygenOptions.md" %} + +# S3 + +{% include "./builder-util-runtime.Interface.S3Options.md" %} + +# Snap Store + +{% include "./builder-util-runtime.Interface.SnapStoreOptions.md" %} + +# Spaces + +{% include "./builder-util-runtime.Interface.SpacesOptions.md" %} + +# BYO Generic (create-your-own) +(And maybe submit it upstream in a PR!) +{% include "./builder-util-runtime.Interface.GenericServerOptions.md" %} \ No newline at end of file diff --git a/pages/snap.md b/pages/snap.md index 271dd183016..adab38b789f 100644 --- a/pages/snap.md +++ b/pages/snap.md @@ -1,5 +1,5 @@ The top-level [snap](configuration.md#Configuration-snap) key contains set of options instructing electron-builder on how it should build [Snap](http://snapcraft.io). - +# Configuration - +{% include "./app-builder-lib.Interface.SnapOptions.md" %} \ No newline at end of file diff --git a/pages/squirrel-windows.md b/pages/squirrel-windows.md index b542feb776e..0a2f3ae7754 100644 --- a/pages/squirrel-windows.md +++ b/pages/squirrel-windows.md @@ -7,6 +7,6 @@ To build for Squirrel.Windows on macOS, please install `mono` (`brew install mon Your app must be able to handle Squirrel.Windows startup events that occur during install and uninstall. See [electron-squirrel-startup](https://github.com/mongodb-js/electron-squirrel-startup). - +# Configuration - +{% include "./app-builder-lib.Interface.SquirrelWindowsOptions.md" %} \ No newline at end of file diff --git a/pages/stylesheets/autowidth.css b/pages/stylesheets/autowidth.css new file mode 100644 index 00000000000..15063bdc57a --- /dev/null +++ b/pages/stylesheets/autowidth.css @@ -0,0 +1,14 @@ +.md-main__inner.md-grid { + max-width: initial; +} + +.md-grid { + max-width: initial; +} + +table th:first-of-type { + width: 50%; +} +table th:nth-of-type(2) { + width: 50%; +} diff --git a/pages/tutorials/macos-kernel-extensions.md b/pages/tutorials/macos-kernel-extensions.md index c83728dca99..b16136de8c9 100644 --- a/pages/tutorials/macos-kernel-extensions.md +++ b/pages/tutorials/macos-kernel-extensions.md @@ -3,12 +3,12 @@ Installing macOS kernel extensions with `electron-builder` can be done using scr First, in `package.json`, make sure you're building a package (`.pkg`) and not the default `.dmg`: ```json -"mac": { +"mac": { "target": "pkg" } ``` -Place your script and the kernel extensions in `build/pkg-scripts`, or [define a custom directory](../configuration/pkg.md#PkgOptions-scripts). Note that the script **must** be called either `preinstall` or `postinstall`. Remember to use ` #!/bin/sh` as the first line in your script. Also, your script must be executable (`chmod +x `). +Place your script and the kernel extensions in `build/pkg-scripts`, or [define a custom directory](../pkg.md#PkgOptions-scripts). Note that the script **must** be called either `preinstall` or `postinstall`. Remember to use ` #!/bin/sh` as the first line in your script. Also, your script must be executable (`chmod +x `). An example script: ```sh diff --git a/pages/tutorials/two-package-structure.md b/pages/tutorials/two-package-structure.md index fcc715c2d9e..30a8d8c7bd3 100644 --- a/pages/tutorials/two-package-structure.md +++ b/pages/tutorials/two-package-structure.md @@ -2,7 +2,7 @@ Since version 8 electron-builder rebuilds only production dependencies, so, you are not forced to use two package.json structure. 1. For development (`./package.json`) - + The `package.json` resides in the root of your project. Here you declare the dependencies for your development environment and build scripts (`devDependencies`). 2. For your application (`./app/package.json`) @@ -12,7 +12,7 @@ Why? 1. Native npm modules (those written in C, not JavaScript) need to be compiled and here we have two different compilation targets for them. Those used within the application need to be compiled against the electron runtime and all `devDependencies` need to be compiled against your local node.js environment. Thanks to the two `package.json` structure, this is trivial (see [#39](https://github.com/electron-userland/electron-builder/issues/39)). -2. No need to specify which [files](../configuration/configuration.md#Configuration-files) to include in the app (because development files reside outside the `app` directory). +2. No need to specify which [files](../configuration.md#Configuration-files) to include in the app (because development files reside outside the `app` directory). Please see [Loading App Dependencies Manually](loading-app-dependencies-manually.md) and [#379](https://github.com/electron-userland/electron-builder/issues/379#issuecomment-218503881). diff --git a/pages/win.md b/pages/win.md index baab40e3258..e87af0e6379 100644 --- a/pages/win.md +++ b/pages/win.md @@ -1,11 +1,13 @@ The top-level [win](configuration.md#Configuration-win) key contains set of options instructing electron-builder on how it should build Windows targets. These options applicable for any Windows target. +# Configuration + {% include "./app-builder-lib.Interface.WindowsConfiguration.md" %} --- -## Common Questions -#### How do delegate code signing? +# Common Questions +## How do delegate code signing? Use [sign](#WindowsConfiguration-sign) option. Please also see [why sign.js is called 8 times](https://github.com/electron-userland/electron-builder/issues/3995). @@ -22,7 +24,7 @@ exports.default = async function(configuration) { } ``` -#### How do use a custom verify function to enable nsis signature verification alternatives instead of powershell? +## How do use a custom verify function to enable nsis signature verification alternatives instead of powershell? Use the `verifyUpdateCodeSignature` interface: @@ -65,7 +67,7 @@ export default class AppUpdater { ``` -#### How do create Parallels Windows 10 Virtual Machine? +## How do create Parallels Windows 10 Virtual Machine? !!! warning "Disable "Share Mac user folders with Windows"" If you use Parallels, you [must not use](https://github.com/electron-userland/electron-builder/issues/865#issuecomment-258105498) "Share Mac user folders with Windows" feature and must not run installers from such folders. @@ -81,7 +83,7 @@ You don't need to have Windows 10 license. Free is provided (expire after 90 day Parallels Windows 10 VM will be used automatically to build AppX on macOS. No need even start VM — it will be started automatically on demand and suspended after build. No need to specify VM — it will be detected automatically (first Windows 10 VM will be used). -#### How do create VirtualBox Windows 10 Virtual Machine? +## How do create VirtualBox Windows 10 Virtual Machine? If you are not on macOS or don't want to buy [Parallels Desktop](https://www.parallels.com/products/desktop/), you can use free [VirtualBox](https://www.virtualbox.org/wiki/Downloads). diff --git a/scripts/renderer/src/typedoc2html.ts b/scripts/renderer/src/typedoc2html.ts index 56ecfec7307..94f7ec3d4b8 100644 --- a/scripts/renderer/src/typedoc2html.ts +++ b/scripts/renderer/src/typedoc2html.ts @@ -20,217 +20,12 @@ async function main() { await rm(dest, { recursive: true }) } await copy(origin, dest) - await copy(path.resolve("./README.md"), path.resolve(origin, "index.md")) + await copy(path.resolve("./README.md"), path.resolve(dest, "README.md")) const typedocConfig: Partial = { options: "typedoc.config.js", }; - const options = { - ...typedocConfig, - "pluginPages": { - "pages": [ - { - "name": "Usage", - "children": [ - { - "name": "CLI", - "source": "api/cli.md" - }, - { - "name": "JS Config/API", - "source": "api/programmatic-usage.md" - }, - ] - }, - { - "name": "Configuration", - "source": "configuration.md", - "children": [ - { - "name": "Contents", - "source": "contents.md" - }, - { - "name": "Publish", - "source": "publish.md" - }, - { - "name": "Mac", - "source": "mac.md", - "children": [ - { - "name": "Dmg", - "source": "dmg.md" - }, - { - "name": "Mas", - "source": "mas.md" - }, - ] - }, - { - "name": "Linux", - "source": "linux.md", - "children": [ - { - "name": "AppImage", - "source": "appimage.md" - }, - { - "name": "Snap", - "source": "snap.md" - }, - { - "name": "Flatpak", - "source": "flatpak.md" - }, - { - "name": "Pkg", - "source": "pkg.md" - }, - ] - }, - { - "name": "Windows", - "source": "windows.md", - "children": [ - { - "name": "MSI", - "source": "msi.md" - }, - { - "name": "Squirrel", - "source": "squirrel-windows.md" - }, - { - "name": "NSIS", - "source": "nsis.md" - }, - { - "name": "AppX", - "source": "appx.md" - }, - { - "name": "MSI Wrapped", - "source": "msi-wrapped.md" - }, - ] - }, - ] - }, - { - "name": "Tutorials", - "children": [ - { - "name": "release-using-channels", - "source": "tutorials/release-using-channels.md" - }, - { - "name": "test-update-on-s3-locally", - "source": "tutorials/test-update-on-s3-locally.md" - }, - { - "name": "macos-kernel-extensions", - "source": "tutorials/macos-kernel-extensions.md" - }, - { - "name": "code-signing-windows-apps-on-unix", - "source": "tutorials/code-signing-windows-apps-on-unix.md" - }, - { - "name": "two-package-structure", - "source": "tutorials/two-package-structure.md" - }, - { - "name": "auto-update", - "source": "tutorials/auto-update.md" - }, - { - "name": "code-signing", - "source": "tutorials/code-signing.md" - }, - { - "name": "loading-app-dependencies-manually", - "source": "tutorials/loading-app-dependencies-manually.md" - }, - ] - }, - { - "name": "Setup", - "children": [ - { - "name": "setup", - "source": "setup/setup.md" - }, - { - "name": "multi-platform-build", - "source": "setup/multi-platform-build.md" - }, - { - "name": "platform-specific-configuration-note", - "source": "setup/platform-specific-configuration-note.md" - }, - { - "name": "file-patterns", - "source": "setup/file-patterns.md" - }, - { - "name": "hooks", - "source": "setup/hooks.md" - }, - { - "name": "icons", - "source": "setup/icons.md" - }, - ] - }, - { - "name": "Donate", - "source": "donate.md" - }, - ] - } - - // pluginPages: { - // pages: [ - // { name: "appimage", source: "appimage.md" }, - // { name: "appx", source: "appx.md" }, - // { name: "auto-update", source: "auto-update.md" }, - // { name: "cli", source: "cli.md" }, - // { name: "code-signing-windows-apps-on-unix", source: "code-signing-windows-apps-on-unix.md" }, - // { name: "code-signing", source: "code-signing.md" }, - // { name: "configuration", source: "configuration.md" }, - // { name: "contents", source: "contents.md" }, - // { name: "dmg", source: "dmg.md" }, - // { name: "donate", source: "donate.md" }, - // { name: "file-patterns", source: "file-patterns.md" }, - // { name: "flatpak", source: "flatpak.md" }, - // { name: "icons", source: "icons.md" }, - // { name: "index", source: "index.md" }, - // { name: "linux", source: "linux.md" }, - // { name: "loading-app-dependencies-manually", source: "loading-app-dependencies-manually.md" }, - // { name: "mac", source: "mac.md" }, - // { name: "macos-kernel-extensions", source: "macos-kernel-extensions.md" }, - // { name: "mas", source: "mas.md" }, - // { name: "msi-wrapped", source: "msi-wrapped.md" }, - // { name: "msi", source: "msi.md" }, - // { name: "multi-platform-build", source: "multi-platform-build.md" }, - // { name: "nsis", source: "nsis.md" }, - // { name: "pkg", source: "pkg.md" }, - // { name: "programmatic-usage", source: "programmatic-usage.md" }, - // { name: "publish", source: "publish.md" }, - // { name: "release-using-channels", source: "release-using-channels.md" }, - // { name: "snap", source: "snap.md" }, - // { name: "squirrel-windows", source: "squirrel-windows.md" }, - // { name: "test-update-on-s3-locally", source: "test-update-on-s3-locally.md" }, - // { name: "two-package-structure", source: "two-package-structure.md" }, - // { name: "win", source: "win.md" }, - // ], - // }, - } - - const config = { ...typedocConfig, flattenOutputFiles: true diff --git a/typedoc.config.js b/typedoc.config.js index 7d2e41628dc..395aa64fc17 100644 --- a/typedoc.config.js +++ b/typedoc.config.js @@ -17,14 +17,15 @@ module.exports = { ], "hideGroupHeadings": true, "hidePageTitle": true, + disableSources: true, "hidePageHeader": false, - "indexFormat": "table", - "parametersFormat": "table", - "interfacePropertiesFormat": "table", - "classPropertiesFormat": "table", - "enumMembersFormat": "table", - "typeDeclarationFormat": "table", - "propertyMembersFormat": "table", + // "indexFormat": "table", + // "parametersFormat": "table", + // "interfacePropertiesFormat": "table", + // "classPropertiesFormat": "table", + // "enumMembersFormat": "table", + // "typeDeclarationFormat": "table", + // "propertyMembersFormat": "table", "tableColumnSettings": { "hideDefaults": false, "hideInherited": false,