chore(docs): fix hyperlinks and add more documentation (#8501)

.changeset/two-donuts-return.md

@@ -0,0 +1,5 @@
+---
+"app-builder-lib": patch
+---
+
+chore(docs): update more docs with proper hyperlinks

README.md

@@ -129,7 +129,7 @@ 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.md#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), `description`, `version` and [author](https://docs.npmjs.com/files/package.json#people-fields-author-contributors).
 
 2. Specify the [build](https://electron.build./configuration.md#build) configuration in the `package.json` as follows:
     ```json
@@ -156,16 +156,16 @@ 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.md#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#nodeGypRebuild) to `true`.
 
-Please note that everything is packaged into an asar archive [by default](https://electron.build./configuration.md#Configuration-asar).
+Please note that everything is packaged into an asar archive [by default](https://electron.build./configuration.md#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).
+See `node_modules/electron-builder/out/index.d.ts`. Typings for TypeScript are provided and also can be found [here](./electron-builder.md).
 
-Code snippit provided below is also shown "in action" [here](/api/programmatic-usage.md) as well.
+Code snippit provided below is also shown "in action" [here](./programmatic-usage.md) as well.
 ```js
 "use strict"
 

packages/app-builder-lib/src/configuration.ts

@@ -30,7 +30,7 @@ export interface Configuration extends PlatformSpecificBuildOptions, Hooks {
   readonly appId?: string | null
 
   /**
-   * As [name](#Metadata-name), but allows you to specify a product name for your executable which contains spaces and other special characters not allowed in the [name property](https://docs.npmjs.com/files/package.json#name).
+   * As [name](#metadata), but allows you to specify a product name for your executable which contains spaces and other special characters not allowed in the [name property](https://docs.npmjs.com/files/package.json#name).
    * If not specified inside of the `build` configuration, `productName` property defined at the top level of `package.json` is used. If not specified at the top level of `package.json`, [name property](https://docs.npmjs.com/files/package.json#name) is used.
    */
   readonly productName?: string | null
@@ -41,6 +41,9 @@ export interface Configuration extends PlatformSpecificBuildOptions, Hooks {
    */
   readonly copyright?: string | null
 
+  /**
+   * Directories for build resources
+   */
   readonly directories?: MetadataDirectories | null
 
   /**
@@ -295,25 +298,30 @@ File `myBeforePackHook.js` in the project root directory:
 
   /**
    * The function (or path to file or module id) to be [run after the prebuilt Electron binary has been extracted to the output directory](#afterextract)
+   * Same setup as {@link beforePack}
    */
   readonly afterExtract?: Hook<AfterExtractContext, any> | string | null
 
   /**
    * The function (or path to file or module id) to be [run after pack](#afterpack) (but before pack into distributable format and sign).
+   * Same setup as {@link beforePack}
    */
   readonly afterPack?: Hook<AfterPackContext, any> | string | null
 
   /**
    * The function (or path to file or module id) to be [run after pack and sign](#aftersign) (but before pack into distributable format).
+   * Same setup as {@link beforePack}
    */
   readonly afterSign?: Hook<AfterPackContext, any> | string | null
 
   /**
    * The function (or path to file or module id) to be run on artifact build start.
+   * Same setup as {@link beforePack}
    */
   readonly artifactBuildStarted?: Hook<ArtifactBuildStarted, any> | string | null
   /**
    * The function (or path to file or module id) to be run on artifact build completed.
+   * Same setup as {@link beforePack}
    */
   readonly artifactBuildCompleted?: Hook<ArtifactCreated, any> | string | null
   /**

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.md#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).
    */
   readonly identityName?: string | null
 

packages/app-builder-lib/src/options/PlatformSpecificBuildOptions.ts

@@ -5,7 +5,7 @@ export interface FileSet {
   /**
    * The source path relative to and defaults to:
    *
-   *  - the [app directory](configuration.md#MetadataDirectories-app) for `files`,
+   *  - the [app directory](configuration.md#directories) for `files`,
    *  - the project directory for `extraResources` and `extraFiles`.
    * If you don't use two-package.json structure and don't set custom app directory, app directory equals to project directory.
    */
@@ -36,7 +36,7 @@ export interface AsarOptions {
 
 export interface FilesBuildOptions {
   /**
-   * 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#directories), which specifies which files to include when copying files to create the package.
 
 Defaults to:
 ```json
@@ -126,13 +126,13 @@ export interface PlatformSpecificBuildOptions extends TargetSpecificOptions, Fil
   /**
    * Whether to package the application's source code into an archive, using [Electron's archive format](http://electron.atom.io/docs/tutorial/application-packaging/).
    *
-   * Node modules, that must be unpacked, will be detected automatically, you don't need to explicitly set [asarUnpack](#configuration-asarUnpack) - please file an issue if this doesn't work.
+   * Node modules, that must be unpacked, will be detected automatically, you don't need to explicitly set [asarUnpack](#asarUnpack) - please file an issue if this doesn't work.
    * @default true
    */
   readonly asar?: AsarOptions | boolean | null
 
   /**
-   * 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.
+   * A [glob patterns](./file-patterns.md) relative to the [app directory](#directories), which specifies which files to unpack when creating the [asar](http://electron.atom.io/docs/tutorial/application-packaging/) archive.
    */
   readonly asarUnpack?: Array<string> | string | null
 
@@ -209,7 +209,7 @@ export interface ReleaseInfo {
   releaseNotes?: string | null
 
   /**
-   * The path to release notes file. Defaults to `release-notes-${platform}.md` (where `platform` it is current platform — `mac`, `linux` or `windows`) or `release-notes.md` in the [build resources](#MetadataDirectories-buildResources).
+   * The path to release notes file. Defaults to `release-notes-${platform}.md` (where `platform` it is current platform — `mac`, `linux` or `windows`) or `release-notes.md` in the [build resources](./contents.md#extraresources).
    */
   releaseNotesFile?: string | null
 

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.md#Configuration-productName).
+   * The 78 character long summary. Defaults to [productName](./configuration.md#productName).
    */
   readonly summary?: string | null
 

packages/app-builder-lib/src/options/linuxOptions.ts

@@ -12,17 +12,17 @@ export interface LinuxConfiguration extends CommonLinuxOptions, PlatformSpecific
   readonly target?: TargetConfigType
 
   /**
-   * The maintainer. Defaults to [author](./configuration.md#Metadata-author).
+   * The maintainer. Defaults to [author](./configuration.md#author).
    */
   readonly maintainer?: string | null
 
   /**
-   * The vendor. Defaults to [author](./configuration.md#Metadata-author).
+   * The vendor. Defaults to [author](./configuration.md#author).
    */
   readonly vendor?: string | null
 
   /**
-   * 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.
+   * The path to icon set directory or one png file, relative to the [build resources](./contents.md#extraresources) 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.md#Metadata-description) from application package.json, but allows you to specify different for Linux.
+   * As [description](./configuration.md#description) from application package.json, but allows you to specify different for Linux.
    */
   readonly description?: string | null
 

packages/app-builder-lib/src/options/macOptions.ts

@@ -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.md#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](./contents.md#extraresources) or to the project directory.
    * Defaults to the application icon (`build/icon.icns`).
    */
   icon?: string | null

packages/app-builder-lib/src/targets/nsis/nsisOptions.ts

@@ -100,32 +100,32 @@ export interface NsisOptions extends CommonNsisOptions, CommonWindowsInstallerCo
   readonly removeDefaultUninstallWelcomePage?: boolean
 
   /**
-   * The path to installer icon, relative to the [build resources](./configuration.md#MetadataDirectories-buildResources) or to the project directory.
+   * The path to installer icon, relative to the [build resources](./contents.md#extraresources) 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.md#MetadataDirectories-buildResources) or to the project directory.
+   * The path to uninstaller icon, relative to the [build resources](./contents.md#extraresources) 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.md#MetadataDirectories-buildResources) or to the project directory.
+   * *assisted installer only.* `MUI_HEADERIMAGE`, relative to the [build resources](./contents.md#extraresources) 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.md#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](./contents.md#extraresources) 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.md#MetadataDirectories-buildResources) or to the project directory.
+   * *assisted installer only.* `MUI_WELCOMEFINISHPAGE_BITMAP`, relative to the [build resources](./contents.md#extraresources) 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.md#MetadataDirectories-buildResources) or to the project directory.
+   * *assisted installer only.* `MUI_UNWELCOMEFINISHPAGE_BITMAP`, relative to the [build resources](./contents.md#extraresources) 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

pages/appimage.md

@@ -1,4 +1,4 @@
-The top-level [appImage](configuration.md#Configuration-appImage) key contains set of options instructing electron-builder on how it should build [AppImage](https://appimage.org/).
+The top-level [appImage](configuration.md#appImage) key contains set of options instructing electron-builder on how it should build [AppImage](https://appimage.org/).
 
 !!! 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.

pages/appx.md

@@ -1,10 +1,10 @@
-The top-level [appx](configuration.md#Configuration-appx) key contains set of options instructing electron-builder on how it should build AppX (Windows Store).
+The top-level [appx](configuration.md#appx) key contains set of options instructing electron-builder on how it should build AppX (Windows Store).
 
 All options are optional. All required for AppX configuration is inferred and computed automatically.
 
 ## AppX Package Code Signing
 
-* If the AppX package is meant for enterprise or self-made distribution (manually install the app without using the Store for testing or for enterprise distribution), it must be [signed](../code-signing.md).
+* If the AppX package is meant for enterprise or self-made distribution (manually install the app without using the Store for testing or for enterprise distribution), it must be [signed](./code-signing.md).
 * If the AppX package is meant for Windows Store distribution, no need to sign the package with any certificate. The Windows Store will take care of signing it with a Microsoft certificate during the submission process.
 
 ## AppX Assets

pages/auto-update.md

@@ -188,15 +188,15 @@ Emitted when checking if an update has started.
 
 #### Event: `update-available`
 
-* `info` [UpdateInfo](#UpdateInfo) (for generic and github providers) | [VersionInfo](#VersionInfo) (for Bintray provider)
+* `info` [UpdateInfo](#updateinfo) (for generic and github providers) | [VersionInfo](#VersionInfo) (for Bintray provider)
 
 Emitted when there is an available update. The update is downloaded automatically if `autoDownload` is `true`.
 
 #### Event: `update-not-available`
 
 Emitted when there is no available update.
 
-* `info` [UpdateInfo](#UpdateInfo) (for generic and github providers) | [VersionInfo](#VersionInfo) (for Bintray provider)
+* `info` [UpdateInfo](#updateinfo) (for generic and github providers) | [VersionInfo](#VersionInfo) (for Bintray provider)
 
 #### Event: `download-progress`
 * `progress` ProgressInfo
@@ -209,8 +209,8 @@ Emitted on progress.
 
 #### Event: `update-downloaded`
 
-* `info` [UpdateInfo](#UpdateInfo) — for generic and github providers. [VersionInfo](#VersionInfo) for Bintray provider.
+* `info` [UpdateInfo](#updateinfo) — for generic and github providers. [VersionInfo](#VersionInfo) for Bintray provider.
 
-<!-- do not edit. start of generated block -->
+## UpdateInfo
 
-<!-- end of generated block -->
+{!./electron-updater.Interface.UpdateInfo.md!}

pages/cli.md

@@ -7,6 +7,7 @@ Commands:
                                             for Windows apps
   electron-builder start                    Run application in a development
                                             mode using electron-webpack
+  electron-builder publish                  Publish any files with your publish config
 
 Building:
   --mac, -m, -o, --macos   Build for macOS, accepts target list (see
@@ -34,6 +35,22 @@ Publishing:
                  https://goo.gl/tSFycD
                 [choices: "onTag", "onTagOrDraft", "always", "never", undefined]
 
+
+-----
+
+electron-builder publish
+
+Publish a list of artifacts
+
+Options:
+  -v, --version  The app/build version used when searching for an upload release
+                 (used by some Publishers)                              [string]
+      --help     Show help                                             [boolean]
+  -f, --files    The file(s) to upload to your publisher      [array] [required]
+  -c, --config   The path to an electron-builder config. Defaults to
+                 `electron-builder.yml` (or `json`, or `json5`, or `js`, or
+                 `ts`), see https://goo.gl/YFRJOM                       [string]
+
 Other:
   --help     Show help                                                 [boolean]
   --version  Show version number                                       [boolean]

pages/dmg.md

@@ -1,4 +1,4 @@
-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).
+The top-level [dmg](configuration.md#dmg) key contains set of options instructing electron-builder on how it should build [DMG](https://en.wikipedia.org/wiki/Apple_Disk_Image).
 
 ## DMG License
 

pages/file-patterns.md

@@ -48,4 +48,4 @@ You can use macros in the file patterns, artifact file name patterns and publish
 * `${version}`
 * `${channel}` — detected prerelease component from version (e.g. `beta`).
 * `${env.ENV_NAME}` — any environment variable.
-* Any property of [AppInfo](api/electron-builder.md#AppInfo) (e.g. `buildVersion`, `buildNumber`).
+* Any property of [AppInfo](./app-builder-lib.Class.AppInfo.md) (e.g. `buildVersion`, `buildNumber`).

pages/flatpak.md

@@ -3,7 +3,7 @@
 
     For what it's worth, there are [some](https://discourse.flathub.org/t/seeking-contractors-for-work-on-flathub-project/1889) [plans](https://discourse.flathub.org/t/is-it-possible-to-publish-a-self-contained-flatpak-file-to-flathub/2083) to make it easier to publish Electron apps to Flathub. When that happens, it should be easier to create a Flathub publisher for `electron-builder` (which would work similary to the other publishers).
 
-The top-level [flatpak](configuration.md#Configuration-flatpak) key contains a set of options instructing electron-builder on how it should build a [Flatpak](https://flatpak.org/) bundle.
+The top-level [flatpak](configuration.md#flatpak) key contains a set of options instructing electron-builder on how it should build a [Flatpak](https://flatpak.org/) bundle.
 
 !!! info "Build dependencies"
     The `flatpak` and `flatpak-builder` packages need to be installed in order to build Flatpak bundles.