docs: a lot more documentation

docs/pages/getting-started/csharp.md

@@ -0,0 +1,46 @@
+*Applies to: Windows, MacOS, Linux*
+
+# Getting Started: C# / .NET
+
+1. Install the command line tool `vpk`:
+   ```cmd
+   dotnet tool update -g vpk
+   ```
+2. Install the  [Velopack NuGet Package](https://www.nuget.org/packages/velopack) in your main project:
+   ```cmd
+   dotnet add package Velopack
+   ```
+3. Configure your Velopack app at the beginning of `Program.Main`:
+   ```cs
+   static void Main(string[] args)
+   {
+       VelopackApp.Build().Run();
+       // ... your other startup code below
+   }
+   ```
+4. Add automatic updating to your app:
+   ```cs
+   private static async Task UpdateMyApp()
+   {
+       var mgr = new UpdateManager("https://the.place/you-host/updates");
+
+       // check for new version
+       var newVersion = await mgr.CheckForUpdatesAsync();
+       if (newVersion == null)
+           return; // no update available
+
+       // download new version
+       await mgr.DownloadUpdatesAsync(newVersion);
+
+       // install new version and restart app
+       mgr.ApplyUpdatesAndRestart();
+   }
+   ```
+5. Publish dotnet and build your first Velopack release! 🎉
+   ```cmd
+   dotnet publish -c Release --self-contained -r win-x64 -o .\publish
+   vpk pack -u YourAppId -v 1.0.0 -p .\publish -e yourMainApp.exe
+   ```
+6. Upload the files created by Velopack to `https://the.place/you-host/updates`
+
+If you're not sure how these instructions fit into your app, check the example apps for common scenarios such as WPF or Avalonia.

docs/pages/getting-started/toc.yml

@@ -1,2 +1,2 @@
-- name: C# / .NET
+- name: C# .NET
   href: csharp.md

docs/pages/packaging/bootstrapping.md

@@ -10,8 +10,8 @@ vpk pack ... --framework net6.0-x64-desktop,vcredist142-x64
 
 These dependencies will be downloaded and installed before your application will be installed.
 
-## ❗ Important for dotnet ❗
+> [!CAUTION]
-If you are building your application with `--self-contained`, you should **NOT** provide a `--framework` argument specifying that your app requires dotnet installed, because your application already has the runtime bundled in. If you are publishing your application with `--no-self-contained`, then you should provide the `--framework` argument.
+> If you are building a dotnet application with `--self-contained`, you should **NOT** provide a `--framework` argument specifying that your app requires dotnet installed, because your application already has the runtime bundled in. If you are publishing your application with `--no-self-contained`, then you should provide the `--framework` argument.
 
 ## Adding dependencies during updates
 

docs/pages/packaging/installer.md

@@ -1,2 +1,48 @@
 *Applies to: Windows, MacOS*
-# Customising Installers
+
+# Installer Overview
+Velopack takes a relatively light-touch when it comes to installers, so there is not a lot of customisation available like you would find in other installation frameworks. This is the tradeoff Velopack makes to ensure that the developer/user experience is as fast and easy as possible.
+
+In both operating systems, if [code signing is configured](signing.md) the installer will also be signed. (This is _required_ on MacOS)
+
+## Windows Overview
+The Windows installer is currently a "one-click" installer, meaning when the `Setup.exe` binary is run, Velopack will not show any questions / wizards to the user, it will simply attempt to install the app as fast as possible and then launch it. 
+
+The setup will install a shortcut to `StartMenuRoot` and `Desktop` by default. [[Read more]](../updating/shortcuts.md)
+
+The key options which will customize the installer are as follows:
+- `--packTitle {app name}` customizes shortcut names, the Apps & Features name, and the portable entry exe name.
+- `--icon {path}` sets the .ico on Update.exe and Setup.exe (and also the icon of any dialogs shown)
+- `--splashImage {path}` sets the (possibly animated) splash image to be shown while installing.
+
+The splash image can be a `jpeg`, `png`, or `gif`. In the latter case, it will be animated.
+
+You can also [bootstrap required frameworks](bootstrapping.md) before installing your app.
+
+The Windows installer will extract the application to `%LocalAppData%\{packId}`, and the directory structure will look like:
+
+```
+{packId}
+├── current
+│   ├── YourFile.dll
+│   ├── sq.version
+│   └── YourApp.exe
+└── Update.exe
+```
+
+The `current` directory will be fully replaced [while doing updates](../updating/overview.md). The other two files added by Velopack (`Update.exe` and `sq.version`) are crucial and are required files for Velopack to be able to properly update your application.
+
+## MacOS Overview
+The MacOS installer will be a standard `.pkg` - which is just a bundle where the UI is provided by the operating system, allowing the user to pick the install location. The app will be launched automatically after the install (mirroring the behavior on Windows) because of a `postinstall` script added by Velopack.
+
+The key options which will customize the installer are as follows:
+- `--packTitle {app name}` customizes the name of the `.app` bundle and the app name shown in the `.pkg`
+- `--pkgWelcome {path}` adds a Welcome page
+- `--pkgReadme {path}` adds a Readme page
+- `--pkgLicense {path}` adds a License Acceptance page
+- `--pkgConclusion {path}` adds a Conclusion page
+- `--noPkg` disable generating a `.pkg` installer entirely
+
+The pkgPage arguments can be a `.rtf` or a `.html` file.
+
+The `.app` package can be extracted to `/Applications` or `~/Applications`, this is selected by the user while installing.

docs/pages/packaging/overview.md

@@ -0,0 +1,58 @@
+*Applies to: Windows, MacOS, Linux*
+# Packaging Overview
+
+Packaging a release is accomplished with the `pack` command in Velopack. Regardless of your operating system, the common required arguments are roughly the same. 
+
+## Creating your first release
+You first should compile your application with whatever toolchain you would normally use (eg. `dotnet publish`, `msbuild.exe`, so forth). 
+Henceforth this will be called `{build_dir}`.
+
+### Required arguments
+- `--packId {id}` The unique ID of your application. This should be unique enough to avoid other application authors from colliding with your app.
+- `--packVersion {version}` The current version you are releasing - in [semver2 format](https://semver.org/) (eg. `1.0.0-build.23+metadata`). 
+- `--packDir {build_dir}` The folder containing your compiled application.
+- `--mainExe {exeName}` The main executable to be started after install, and the binary that will [handle Velopack Hooks](../updating/overview.md).
+- `--icon {path}` The icon used to bundle your app. Only required on MacOS and Linux.
+
+> [!TIP]
+> Velopack does not support 4 part versions (eg. `1.0.0.0`), as it would not be practical to support both formats simultaneously and semver2 offers a lot more flexibility.
+
+A complete example:
+```cmd
+dotnet publish -c Release -r win-x64 -o publish
+vpk pack --packId MyAppId -packVersion 1.0.0 --packDir publish --mainExe MyApp.exe
+```
+
+### Optional recommended arguments
+There are many optional arguments, the best way to see what features are available for your operating system is to check `vpk pack -h`. To mention a couple:
+- `--packTitle {name}` The friendly name for your app, shown to users in dialogs, shortcuts, etc.
+- `--outputDir {path}` The location Velopack should create the final releases (defaults to `.\Releases`)
+
+### Release output
+When building a release has completed, you should have the following assets in your `--outputDir`:
+- `MyAppId-1.0.0-full.nupkg` - Full Release: contains your entire update package.
+- `MyAppId-1.0.0-delta.nupkg` - Delta Release: only if there was a previous release to build a delta from. These are optional to build/deploy, but speeds up the updating process for sers because they only need to download what's changed between versions instead of the full package.
+- `MyAppId-Portable.zip` - Portable Release: Can deploy this optionally to allow users to run and update your app without installing.
+- `MyAppId-Setup.exe` - Installer: Used by most users to install the app to the local filesystem.
+- `releases.{channel}.json` - Releases Index: a list of every available release. Used by `UpdateManager` to locate the latest applicable release.
+- `RELEASES` - Legacy Releases File: only used for clients [migrating to Velopack](../migrating.md) from Squirrel.
+- `assets.{channel}.json` - Build Assets: A list of assets created in the most recent build. Used by [Velopack deployment commands](../distributing/overview.md).
+
+You do not need to deploy all of these files to allow users to update, so you should review the [deployment guide](../distributing/overview.md) for more information on which files to distribute.
+
+> [!TIP]
+> There is no setup/installer package for Linux. The program is distributed as a self-updating `.AppImage`. The reason is that `.AppImage` will run on pretty much every modern distro with no extra dependencies needed. Just download the `.AppImage`, run `chmod +x`, and click it to start. It is possible to install an `.AppImage`, but this is left up to the user to install something like [appimaged](https://github.com/probonopd/go-appimage/blob/master/src/appimaged/README.md) or [AppImageLauncher](https://github.com/TheAssassin/AppImageLauncher).
+
+## Code signing
+While this is not required for local builds / testing, you should always code-sign your application before distributing your application to users. 
+
+> [!WARNING]
+> If you do not code-sign, your application may fail to run. [[Read more]](signing.md)
+
+## Customising the installer
+On platforms which ship installers, you can customise the behavior. [[Read more]](installer.md)
+
+## Other recommended arguments
+- If your application is operating-system or CPU architecture specific you should consider adding an `--rid`. [[Read more]](rid.md)
+- If you plan on distributing release channels for different architectures or features, consider adding a `--channel` [[Read more]](channels.md)
+- If your app requires additional frameworks (eg. vcredist) consider `--framework` [[Read more]](bootstrapping.md)

docs/pages/packaging/rid.md

@@ -0,0 +1,22 @@
+*Applies to: Windows, MacOS, Linux*
+
+# RID (Runtime Identifier)
+Similar to how you provide a RID to dotnet to designate your target operating system and architecture, you can do the same for Velopack to tell it what your application supports. 
+
+An RID is composed of three parts (`{os}{version?}-{arch}`)
+ - os: operating system (`win`, `osx`, or `linux`)
+ - version: optionally, specify minimum supported version (eg. `win7`, `win8.1`, `win10.0.18362`)
+ - arch: optionaly, specify supported CPU architecture (eg.`win-x86`, `win-x64`, `win-arm64`)
+
+If you were to provide the RID `--rid win10-arm64`, any users trying to install your app on Windows 7, 8, or 8.1 will receive a message saying their operating system is not supported. Similarly, if a Windows 11 user with an x64 cpu were trying to install - it would also fail with a helpful message.
+
+If trying to target Windows 11, they did not increment the major build number from 10 to 11. Anything >= build 22000 is classified as Windows 11. For example:
+ - `win11 == win10.0.22000`
+ - `win11.0.22621 == win10.0.22621`
+
+On MacOS, the RID (min version and arch) is just stored as metadata in the `.pkg` which will be handled natively by the operating system.
+
+#### Also read
+- [Windows 10 version history](https://en.wikipedia.org/wiki/Windows_10_version_history)
+- [Windows 11 version history](https://en.wikipedia.org/wiki/Windows_11_version_history)
+- [.NET RID Catalog](https://learn.microsoft.com/en-us/dotnet/core/rid-catalog)

docs/pages/packaging/toc.yml

@@ -4,9 +4,9 @@
   href: channels.md
 - name: Code Signing
   href: signing.md
-- name: Customising Installers
+- name: Installer Overview
   href: installer.md
-- name: Boostrapping frameworks (.NET, .Net Framework, VCRedist, etc)
+- name: Boostrapping (.NET, .Net Framework, VCRedist, etc)
   href: bootstrapping.md
-- name: RID / Minimum Supported OS
+- name: RID / Min Supported OS
   href: rid.md

docs/pages/toc.yml

@@ -3,29 +3,33 @@
 
 - name: Getting Started
   href: getting-started/toc.yml
+  homepage: getting-started/csharp.md
 
 - name: Sample Apps
   items:
-  - name: Avalonia / Cross Platform
+  - name: C# Avalonia / Cross Platform
     href: https://github.com/velopack/velopack/tree/master/examples/AvaloniaCrossPlat
-  - name: WPF Windows
+  - name: C# WPF / .Net Framework
     href: https://github.com/velopack/velopack/tree/master/examples/VeloWpfSample
 
 - name: Packaging Releases
   href: packaging/toc.yml
+  homepage: packaging/overview.md
 
 - name: Distributing Releases
   href: distributing/toc.yml
+  homepage: distributing/overview.md
 
 - name: Updating
   href: updating/toc.yml
+  homepage: updating/overview.md
 
 - name: Troubleshooting
   href: troubleshooting/toc.yml
+  homepage: troubleshooting/debugging.md
 
 - name: Migrating to Velopack
   href: migrating.md
 
 - name: Contributing
   href: compiling.md
-

docs/pages/troubleshooting/toc.yml

@@ -1,4 +1,4 @@
-- name: Command Line Reference
-  href: cli.md
 - name: Debugging / Logging
   href: debugging.md
+- name: Command Line Reference
+  href: cli.md

docs/templates/velopack/public/main.css

@@ -54,6 +54,14 @@ h3 {
     font-size: 1.5rem;
 }
 
+h4 {
+    font-size: 1.25rem;
+}
+
+pre {
+    border-radius: 6px;
+}
+
 ul {
     margin-bottom: 16px !important;
 }