Skip to content

Commit

Permalink
update links to mdx
Browse files Browse the repository at this point in the history
  • Loading branch information
caesay committed Mar 2, 2024
1 parent 4c1e8cb commit a8445a5
Show file tree
Hide file tree
Showing 11 changed files with 38 additions and 38 deletions.
4 changes: 2 additions & 2 deletions docs/distributing/github-actions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ your application.

Compile your application. This example will do so by publishing the application to a folder in a self-contained manner.
You can publish without the self-contained flag if using Velopack to install such dependencies
(see [Bootstrapping](../packaging/bootstrapping.md) for details). This command uses the `-c` flag to set the build
(see [Bootstrapping](../packaging/bootstrapping.mdx) for details). This command uses the `-c` flag to set the build
configuration to `Release` mode, `-o` to set the output directory to `publish`, `-r` to set the runtime
to `win-x64` for distributing on 64-bit Windows, and `--self-contained` to publish the .NET runtime with the
application. Adapt this command to your needs. You can learn more about
Expand All @@ -90,7 +90,7 @@ between the current release and the new one, as well as populating the releases
3. Invokes the Velopack CLI to package your application. The `-v` argument calls upon
the `version` variable assigned earlier, which is accessed using the `id` of the step that assigned it (`get-version`).
`-p` is pointed at the `publish` directory that was used in the previous step. For more information on the Velopack CLI
and which flags are available for the `pack` command, [see here](../packaging/overview.md).
and which flags are available for the `pack` command, [see here](../packaging/overview.mdx).
4. Creates a new release in your repository and uploads the necessary files to it automatically.

:::tip
Expand Down
10 changes: 5 additions & 5 deletions docs/distributing/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ The general steps for creating and deploying a Velopack release are:
0. Upload your newly created 1.0.1 assets.
0. Update the remote `releases.{channel}.json` to reflect the newly uploaded assets.

See also: [Deployment commands](deploy-cli.md) can make this process much easier.
See also: [Deployment commands](deploy-cli.mdx) can make this process much easier.

## List of assets produced
After packing a release with Velopack, you should have something like the following in your output directory:
Expand All @@ -30,7 +30,7 @@ Releases
```

### Full and delta nupkg's
These are the update packages that installed applications use to find/install the latest version. Full packages contain an entire replication of your input files, plus some files Velopack adds. A delta package is a diff from the previously created full package. You need to have the previous version (eg. 1.0.0 in the above example) downloaded and in the output directory for a delta to be created (in this case, `1.0.0->1.0.0`). There are helpful [deployment commands](deploy-cli.md) which can download the latest version for you, so that deltas will be generated automatically.
These are the update packages that installed applications use to find/install the latest version. Full packages contain an entire replication of your input files, plus some files Velopack adds. A delta package is a diff from the previously created full package. You need to have the previous version (eg. 1.0.0 in the above example) downloaded and in the output directory for a delta to be created (in this case, `1.0.0->1.0.0`). There are helpful [deployment commands](deploy-cli.mdx) which can download the latest version for you, so that deltas will be generated automatically.

You must distribute these packages in the same folder as the `releases.{channel}.json` file for updates to work.

Expand All @@ -40,7 +40,7 @@ This is what your user should download and run to install your app. On MacOS, yo
### Release feed (`releases.{channel}.json`)
This file should be distributed in the same folder as the `nupkg` files are deployed. It contains a list of all available releases.

When you provide a HTTP url to `UpdateManager`, it will search for this file. For example, if you `new UpdateManager("https://the.place/you-host/updates")`, then UpdateManager will request for `https://the.place/you-host/updates/releases.{channel}.json`. The channel UpdateManager uses in the request is automatic, you can [read more here about channels](../packaging/channels.md).
When you provide a HTTP url to `UpdateManager`, it will search for this file. For example, if you `new UpdateManager("https://the.place/you-host/updates")`, then UpdateManager will request for `https://the.place/you-host/updates/releases.{channel}.json`. The channel UpdateManager uses in the request is automatic, you can [read more here about channels](../packaging/channels.mdx).

For example, if you packed `1.0.0` and then `1.0.1` immediately after, the contents of this file might look like:

Expand Down Expand Up @@ -81,10 +81,10 @@ The releases file should always mirror what files are _actually available_ in th
This file is the only way that UpdateManager can discover releases, if you do not update it properly it may result in your users not getting updates.
:::

It is tedious to update this file manually, so Velopack CLI provides deployment commands which can deploy assets and update this file automatically for you, as well as apply rentention policies around the number of releases to keep. [[Read more]](deploy-cli.md)
It is tedious to update this file manually, so Velopack CLI provides deployment commands which can deploy assets and update this file automatically for you, as well as apply rentention policies around the number of releases to keep. [[Read more]](deploy-cli.mdx)

### Legacy release feed (`RELEASES`)
This releases format was used by Clowd.Squirrel and Squirrel.Windows, and is still produced by Velopack to allow you to migrate an application using one of those frameworks to Velopack. If you do not have any legacy users which need to migrate to Velopack, you can safely ignore this file.

### Assets file
This file contains a list of assets produced by the latest `pack` command. It is used by the [Velopack deployment commands](deploy-cli.md) to know which files should be uploaded. It can be ignored / deleted if you do not intend to use these commands to deploy releases and automatically update your release feed.
This file contains a list of assets produced by the latest `pack` command. It is used by the [Velopack deployment commands](deploy-cli.mdx) to know which files should be uploaded. It can be ignored / deleted if you do not intend to use these commands to deploy releases and automatically update your release feed.
14 changes: 7 additions & 7 deletions docs/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ Be sure to check us out on [GitHub](https://github.com/velopack/velopack) and [j

## Overview
To enable your application to make full use of Velopack, you need to do 3 things:
1. Integrate the SDK into your app, and check for updates. [[Read more]](integrating/overview.md)
0. Run the `vpk` command line tool to generate your update packages and installers. [[Read more]](packaging/overview.md)
0. Upload your release somewhere your app can download updates from. [[Read more]](distributing/overview.md)
1. Integrate the SDK into your app, and check for updates. [[Read more]](integrating/overview.mdx)
0. Run the `vpk` command line tool to generate your update packages and installers. [[Read more]](packaging/overview.mdx)
0. Upload your release somewhere your app can download updates from. [[Read more]](distributing/overview.mdx)

## Language Support
There are libraries planned or supported for the languages below.
Expand All @@ -19,10 +19,10 @@ If your language is not listed, you can [open an issue to request it](https://gi

| Lang | Status | Runtime Deps | Async | Links |
|:-:|---|---|---|---|
| C# | ✅ Ready | ✅ None | ✅ Yes | [quick start](./getting-started/csharp.md), [docs](./reference/cs/Velopack/), [samples](https://github.com/velopack/velopack/tree/master/samples), [nuget.org](https://nuget.org/packages/velopack) |
| JS | ✅ Ready | ✅ None | ✅ Yes | [quick start](./getting-started/electron.md), [docs](./reference/js/classes/UpdateManager.md), [samples](https://github.com/velopack/velopack.fusion/tree/master/for-js/samples), [npmjs.com](https://www.npmjs.com/package/velopack) |
| Rust | ✅ Ready | ✅ None | ✅ Yes | [quick start](./getting-started/rust.md), [docs](https://docs.rs/velopack), [samples](https://github.com/velopack/velopack.fusion/tree/master/for-rust/samples), [crates.io](https://crates.io/crates/velopack) |
| C++ | 🔶 Experimental | 🔶 vfusion.exe | ❌ No | [quick start](./getting-started/cpp.md), [docs](./reference/cpp/api.md), [samples](https://github.com/velopack/velopack.fusion/tree/master/for-cpp/samples), [velopack.hpp](https://github.com/velopack/velopack.fusion/tree/master/for-cpp) |
| C# | ✅ Ready | ✅ None | ✅ Yes | [quick start](./getting-started/csharp.mdx), [docs](./reference/cs/Velopack/), [samples](https://github.com/velopack/velopack/tree/master/samples), [nuget.org](https://nuget.org/packages/velopack) |
| JS | ✅ Ready | ✅ None | ✅ Yes | [quick start](./getting-started/electron.mdx), [docs](./reference/js/classes/UpdateManager.md), [samples](https://github.com/velopack/velopack.fusion/tree/master/for-js/samples), [npmjs.com](https://www.npmjs.com/package/velopack) |
| Rust | ✅ Ready | ✅ None | ✅ Yes | [quick start](./getting-started/rust.mdx), [docs](https://docs.rs/velopack), [samples](https://github.com/velopack/velopack.fusion/tree/master/for-rust/samples), [crates.io](https://crates.io/crates/velopack) |
| C++ | 🔶 Experimental | 🔶 vfusion.exe | ❌ No | [quick start](./getting-started/cpp.mdx), [docs](./reference/cpp/api.md), [samples](https://github.com/velopack/velopack.fusion/tree/master/for-cpp/samples), [velopack.hpp](https://github.com/velopack/velopack.fusion/tree/master/for-cpp) |
| Java | Planned | - | - | - | - |
| Python | Planned | - | - | - | - |
| Swift | Planned | - | - | - | - |
Expand Down
8 changes: 4 additions & 4 deletions docs/integrating/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ static void Main(string[] args)
}
```

The full list of options [for VelopackApp is available here](../reference/cs//Velopack/VelopackApp.md). You can also read more about [how hooks work](./hooks.md).
The full list of options [for VelopackApp is available here](../reference/cs//Velopack/VelopackApp.md). You can also read more about [how hooks work](./hooks.mdx).

:::warning
A "FastCallback" requires that your application show no UI and exit quickly. When the callback returns, your application will exit. If you do not exit this callback quickly enough your process will be killed.
Expand Down Expand Up @@ -79,15 +79,15 @@ You can host your update packages basically anywhere, here are a few examples:
There are a variety of built-in sources (eg. [GithubSource](../reference/cs/Velopack.Sources/GithubSource.md), [SimpleWebSource](../reference/cs/Velopack.Sources/SimpleWebSource.md)) you can use when checking for updates, but you can also build your own by [deriving from IUpdateSource](../reference/cs/Velopack.Sources/IUpdateSource.md).

### Check for updates
`CheckForUpdatesAsync` will read the provided update source for a `releases.{channel}.json` file to retrieve available updates ([Read about channels](../packaging/channels.md)). If there is an update available, a non-null [UpdateInfo](../reference/cs/Velopack/UpdateInfo.md) will be returned with some details about the update. You can also [retrieve any release notes](release-notes.md) which were provided when the update was packaged.
`CheckForUpdatesAsync` will read the provided update source for a `releases.{channel}.json` file to retrieve available updates ([Read about channels](../packaging/channels.mdx)). If there is an update available, a non-null [UpdateInfo](../reference/cs/Velopack/UpdateInfo.md) will be returned with some details about the update. You can also [retrieve any release notes](release-notes.mdx) which were provided when the update was packaged.

There are [also some options](../reference/cs/Velopack/UpdateOptions.md) which can be passed in to [UpdateManager](../reference/cs/Velopack/UpdateManager.md) to customise how updates are handled, eg. to allow things like [switching channels](switching-channels.md).
There are [also some options](../reference/cs/Velopack/UpdateOptions.md) which can be passed in to [UpdateManager](../reference/cs/Velopack/UpdateManager.md) to customise how updates are handled, eg. to allow things like [switching channels](switching-channels.mdx).

### Download updates
`DownloadUpdatesAsync` will attempt to download deltas (if available) and re-construct the latest full release. If there are no deltas available, or the delta reconstruction fails, the latest full release package will be downloaded instead. Note that if an option like `AllowVersionDowngrade` is specified, the downloaded version might be older than the currently executing version.

### Apply updates
Once the update has downloaded, you have a few options available. Calling `ApplyUpdatesAndRestart` or `ApplyUpdatesAndExit` will exit your app, install any [bootstrap prerequisites](../packaging/bootstrapping.md), install the update, and then optionally restart your app right away.
Once the update has downloaded, you have a few options available. Calling `ApplyUpdatesAndRestart` or `ApplyUpdatesAndExit` will exit your app, install any [bootstrap prerequisites](../packaging/bootstrapping.mdx), install the update, and then optionally restart your app right away.

If you do not want to exit your app immediately, you can call `WaitExitThenApplyUpdates` instead, which will launch Update.exe and wait for 60 seconds before proceeding. If your app has not exited within 60 seconds it will be killed.

Expand Down
2 changes: 1 addition & 1 deletion docs/integrating/release-notes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<AppliesTo all />
It is possible to store release notes (Markdown) in update packages and access it while Updating. This could be useful, for example, to show a user a list of changes before downloading a update.

- Write your release notes to a file (eg. releasenotes.md).
- Write your release notes to a file (eg. releasenotes.mdx).
- While packing your release, provide these to Velopack with `--releaseNotes {path/to/releasenotes.md}`

The Velopack builder will render this to HTML for your convenience, and store both the HTML and the markdown into your update package.
Expand Down
2 changes: 1 addition & 1 deletion docs/integrating/switching-channels.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Switching Channels
<AppliesTo all />
By default, `UpdateManager` will try and search for releases in the same channel that it was built for. You can [read more about packaging channels here](../packaging/channels.md). So normally, you should not provide a channel at all to the `UpdateManager` constructor.
By default, `UpdateManager` will try and search for releases in the same channel that it was built for. You can [read more about packaging channels here](../packaging/channels.mdx). So normally, you should not provide a channel at all to the `UpdateManager` constructor.

However, from time to time, it may be useful to allow a user to switch channels without re-installing the application. For example, a user opts into getting "beta" features via your application settings. In that case, you can provide the channel explicitly:

Expand Down
2 changes: 1 addition & 1 deletion docs/migrating/squirrel.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Here are the general steps needed:
dotnet tool install -g vpk
```

0. You will need to replace `SquirrelAwareApp` at the beginning of your app to `VelopackApp.Build().Run()`. Shortcuts [[Read more]](integrating/shortcuts.md) and registry entries are managed automatically for you in Velopack, so if you are currently doing this in `SquirrelAwareApp` hooks they should be removed. For example, if your hooks were this before:
0. You will need to replace `SquirrelAwareApp` at the beginning of your app to `VelopackApp.Build().Run()`. Shortcuts [[Read more]](integrating/shortcuts.mdx) and registry entries are managed automatically for you in Velopack, so if you are currently doing this in `SquirrelAwareApp` hooks they should be removed. For example, if your hooks were this before:
```cs
public static void Main(string[] args)
{
Expand Down
8 changes: 4 additions & 4 deletions docs/packaging/installer.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@
<AppliesTo win mac />
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)
In both operating systems, if [code signing is configured](signing.mdx) 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]](../integrating/shortcuts.md)
The setup will install a shortcut to `StartMenuRoot` and `Desktop` by default. [[Read more]](../integrating/shortcuts.mdx)

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.
Expand All @@ -16,7 +16,7 @@ The key options which will customize the installer are as follows:

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.
You can also [bootstrap required frameworks](bootstrapping.mdx) before installing your app.

The Windows installer will extract the application to `%LocalAppData%\{packId}`, and the directory structure will look like:

Expand All @@ -29,7 +29,7 @@ The Windows installer will extract the application to `%LocalAppData%\{packId}`,
└── Update.exe
```

The `current` directory will be fully replaced [while doing updates](../integrating/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.
The `current` directory will be fully replaced [while doing updates](../integrating/overview.mdx). 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.
Expand Down
Loading

0 comments on commit a8445a5

Please sign in to comment.