docs

Author: jdx

.mise.toml

@@ -1,4 +1,5 @@
-tasks.build.run = "bun run docs:build"
+tasks.dev = "bun run docs:dev"
+tasks.build = "bun run docs:build"
 
 [tasks."commit-and-push"]
 depends = ["build"]

.vitepress/config.ts

@@ -7,8 +7,9 @@ export default defineConfig({
   lastUpdated: true,
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
+    outline: 'deep',
     nav: [
-      { text: 'Dev Tools', link: '/dev-tools' },
+      { text: 'Dev Tools', link: '/dev-tools/' },
       { text: 'Environments', link: '/environments' },
       { text: 'Tasks', link: '/tasks/' },
     ],
@@ -18,6 +19,7 @@ export default defineConfig({
       { text: 'Getting Started', link: '/getting-started' },
       { text: 'Demo', link: '/demo' },
       { text: 'Configuration', link: '/configuration' },
+      { text: 'Plugins', link: '/plugins' },
       { text: 'IDE Integration', link: '/ide-integration' },
       { text: 'Continuous Integration', link: '/continuous-integration' },
       { text: 'Coming from rtx', link: '/rtx' },
@@ -27,12 +29,19 @@ export default defineConfig({
       { text: 'How I Use mise', link: '/how-i-use-mise' },
       {
         text: 'Dev Tools',
-        link: '/dev-tools',
+        link: '/dev-tools/',
         items: [
-          { text: 'Plugins', link: '/plugins' },
-          { text: 'Shims', link: '/shims' },
-          { text: 'Aliases', link: '/aliases' },
-          { text: 'Comparison to asdf', link: '/comparison-to-asdf' },
+          { text: 'Shims', link: '/dev-tools/shims' },
+          { text: 'Aliases', link: '/dev-tools/aliases' },
+          { text: 'Comparison to asdf', link: '/dev-tools/comparison-to-asdf' },
+          {
+            text: 'Backends',
+            items: [
+              { text: 'asdf', link: '/dev-tools/backends/asdf' },
+              { text: 'cargo', link: '/dev-tools/backends/cargo' },
+              { text: 'npm', link: '/dev-tools/backends/npm' },
+            ]
+          }
         ],
       },
       {

about.md

@@ -13,7 +13,7 @@ Its functionality is grouped into 3 categories described below.
 
 `mise` installs and manages dev tools/runtimes like node, python, or terraform both
 simplifying installing these tools and allowing you to specify which version of these
-tools to use in different projects. `mise` supports [hundreds](/plugins) of dev tools.
+tools to use in different projects. `mise` supports [hundreds](/plugins.md) of dev tools.
 
 `mise` manages environment variables letting you specify configuration like
 `AWS_ACCESS_KEY_ID` that may differ between projects. It can also be used to

cli/index.md

@@ -1,5 +1,4 @@
 <!-- MISE:COMMANDS -->
-
 # Commands
 
 ## `mise activate [OPTIONS] [SHELL_TYPE]`

configuration.md

@@ -1,6 +1,3 @@
----
-outline: 'deep'
----
 
 # Configuration
 
@@ -101,7 +98,7 @@ but doesn't require a separate file.
 ### `[aliases]` - Tool version aliases
 
 The following makes `mise install node@my_custom_node` install node-20.x
-this can also be specified in a [plugin](/aliases).
+this can also be specified in a [plugin](/dev-tools/aliases.md).
 note adding an alias will also add a symlink, in this case:
 
     ~/.local/share/mise/installs/node/20 -> ./20.x.x

continuous-integration.md

@@ -20,7 +20,7 @@ script: |
   mise x npm -- test
 ```
 
-Alternatively, you can add the [shims](/shims) directory to your `PATH`, if the CI provider allows it.
+Alternatively, you can add the [shims](/dev-tools/shims.md) directory to your `PATH`, if the CI provider allows it.
 
 ## GitHub Actions
 
@@ -70,4 +70,4 @@ Remember to run your tools using `mise x` from your scripts:
 
 ```bash
 mise x swiftlint -- {args}
-```
+```

aliases.md dev-tools/aliases.md

@@ -0,0 +1,21 @@
+# asdf Backend
+
+asdf is the original backend for mise. It's the default if no backend is specified,
+e.g.: `mise use -g riprep` will use asdf but `mise use -g cargo-riprip` will use
+the [cargo](./cargo) backend.
+
+There are [hundreds of plugins](https://github.com/mise-plugins/registry) available in the
+[mise registry](https://github.com/mise-plugins) and you can also install plugins from git
+repos or local directories.
+
+::: warning
+Take care using plugins as well as anything else you get from the internet. CLIs are
+unfortunately capable of doing a lot of damage to your system if a bad actor manages to
+get into your sytem through a plugin or other tool.
+:::
+
+## Writing asdf plugins for mise
+
+See the asdf documentation for more information on [writing plugins](https://asdf-vm.com/plugins/create.html).
+
+_TODO: document special features only available in mise._

dev-tools/backends/asdf.md

@@ -0,0 +1,61 @@
+# Cargo Backend <Badge type="warning" text="experimental" />
+
+You may install packages directly from [Cargo Crates](https://crates.io/) even if there
+isn't an asdf plugin for it.
+
+The code for this is inside of the mise repository at [`./src/forge/cargo.rs`](https://github.com/jdx/mise/blob/main/src/forge/cargo.rs).
+
+## Dependencies
+
+This relies on having `cargo` installed. You can either install it on your
+system via [rustup](https://rustup.rs/):
+
+```sh
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+Or you can install it via mise:
+
+```sh
+mise use -g rust
+```
+
+## Usage
+
+The following installs the latest version of [eza](https://crates.io/crates/eza) and
+sets it as the active version on PATH:
+
+```sh
+$ mise use -g cargo-eza
+$ eza --version
+eza - A modern, maintained replacement for ls
+v0.17.1 [+git]
+https://github.com/eza-community/eza
+```
+
+The version will be set in `~/.config/mise/config.toml` with the following format:
+
+```toml
+[tools]
+prettier = "latest"
+```
+
+## Configuration
+
+Set these with `mise settings set [VARIABLE] [VALUE]` or by setting the environment variable listed.
+
+### `cargo_binstall`
+
+* Type: `bool`
+* Env: `MISE_CARGO_BINSTALL`
+* Default: `true`
+
+If true, mise will use `cargo binstall` instead of `cargo install` if
+[`cargo-binstall`](https://crates.io/crates/cargo-binstall) is installed and on PATH.
+This makes installing CLIs with cargo _much_ faster by downloading precompiled binaries.
+
+You can install it with mise:
+
+```sh
+mise use -g cargo-binstall
+```

dev-tools/backends/cargo.md

@@ -0,0 +1,33 @@
+# NPM Backend <Badge type="warning" text="experimental" />
+
+You may install packages directly from [npmjs.org](https://npmjs.org/) even if there
+isn't an asdf plugin for it.
+
+The code for this is inside of the mise repository at [`./src/forge/npm.rs`](https://github.com/jdx/mise/blob/main/src/forge/npm.rs).
+
+## Dependencies
+
+This relies on having `npm` installed. You can install it with or without mise.
+Here is how to install `npm` with mise:
+
+```sh
+mise use -g node
+```
+
+## Usage
+
+The following installs the latest version of [prettier](https://www.npmjs.com/package/prettier)
+and sets it as the active version on PATH:
+
+```sh
+$ mise use -g npm-prettier
+$ prettier --version
+3.1.0
+```
+
+The version will be set in `~/.config/mise/config.toml` with the following format:
+
+```toml
+[tools]
+prettier = "latest"
+```

dev-tools/backends/npm.md

@@ -92,3 +92,13 @@ where it's not possible—or at least very challenging—for us to definitively
 used and so we default to mise-style. While there aren't many of these, asdf-compatibility is done
 as a "best-effort" in order to make transitioning from asdf feel familiar for those users who can
 rely on their muscle memory. Ensuring asdf-syntax works with everything is not a design goal.
+
+## Extra backends <Badge type="warning" text="experimental" />
+
+mise has support for backends other than asdf plugins. For example you can install CLIs
+directly from cargo and npm:
+
+```sh
+$ mise use -g cargo-ripgrep@14
+$ mise use -g npm-prettier@3
+```

comparison-to-asdf.md dev-tools/comparison-to-asdf.md

@@ -1,6 +1,3 @@
----
----
-
 # Dev Tools
 
 _Like [asdf](https://asdf-vm.com) (or [nvm](https://github.com/nvm-sh/nvm) or [pyenv](https://github.com/pyenv/pyenv) but for any language) it manages dev tools like node, python, cmake, terraform, and [hundreds more](/plugins)._
@@ -16,11 +13,11 @@ directory. Other projects on your machine can use a different set of versions.
 
 mise is inspired by [asdf](https://asdf-vm.com) and uses asdf's vast [plugin ecosystem](https://github.com/rtx-plugins/registry)
 under the hood. However, it is _much_ faster than asdf and has a more friendly user experience.
-For more on how mise compares to asdf, [see below](/comparison-to-asdf).
+For more on how mise compares to asdf, [see below](./comparison-to-asdf).
 
 mise can be configured in many ways. The most typical is by `.mise.toml`, but it's also compatible
 with asdf `.tool-versions` files. It can also use idiomatic version files like `.node-version` and
-`.ruby-version`. See [Configuration](./configuration) for more.
+`.ruby-version`. See [Configuration](/configuration) for more.
 
 * Like [direnv](https://github.com/direnv/direnv) it manages [environment variables](/configuration#env---arbitrary-environment-variables) for different project directories.
 * Like [make](https://www.gnu.org/software/make/manual/make.html) it manages [tasks](/tasks/) used to build and test projects.
@@ -50,6 +47,19 @@ You should note that mise does not directly install these tools.
 Instead, it leverages plugins to install runtimes.
 See [plugins](/plugins) below.
 
+## Backends 
+
+In addition to asdf plugins, you can also directly install CLIs with some package managers.
+
+* [asdf](/dev-tools/backends/asdf)
+* [Cargo](/dev-tools/backends/cargo) <Badge type="warning" text="experimental" />
+* [NPM](/dev-tools/backends/npm) <Badge type="warning" text="experimental" />
+
+::: tip
+If you'd like to contribute a new backend to mise, they're not difficult to write.
+See [`./src/forge/`](https://github.com/jdx/mise/tree/main/src/forge) for examples.
+:::
+
 ## Common commands
 
 Here are some of the most important commands when it comes to working with dev tools.

dev-tools.md dev-tools/index.md

@@ -1,6 +1,3 @@
----
----
-
 # Shims
 
 While the PATH design of mise works great in most cases, there are some situations where shims are

shims.md dev-tools/shims.md

@@ -1,7 +1,3 @@
----
-outline: 'deep'
----
-
 # Directory Structure
 
 The following are the directories that mise uses.

directories.md

@@ -1,6 +1,3 @@
----
----
-
 # direnv
 
 [direnv](https://direnv.net) and mise both manage environment variables based on directory. Because they both analyze
@@ -51,7 +48,7 @@ export MISE_PYTHON_VERSION=3.11
 Of course if you use `mise activate`, then these steps won't have been necessary and you can use mise
 as if direnv was not used.
 
-If you continue to struggle, you can also try using the [shims method](./shims).
+If you continue to struggle, you can also try using the [shims method](dev-tools/shims.md).
 
 ### Do you need direnv?
 

direnv.md

@@ -1,7 +1,3 @@
----
-outline: 'deep'
----
-
 # Environments
 
 Use mise to specify environment variables used for different projects. Create a `.mise.toml` file

environments.md

@@ -51,7 +51,7 @@ situations where it needs to run without the directory changing, for example if
 Because it runs on prompt display, if you attempt to use `mise activate` in a
 non-interactive session (like a bash script), it will never call `mise hook-env` and in effect will
 never modify PATH because it never displays a prompt. For this type of setup, you can either call
-`mise hook-env` manually every time you wish to update PATH, or use [shims](/shims) instead (preferred).
+`mise hook-env` manually every time you wish to update PATH, or use [shims](/dev-tools/shims.md) instead (preferred).
 Or if you only need to use mise for certain commands, just prefix the commands with
 [`mise x --`](./cli/#mise-exec-options-tool-version-command).
 For example, `mise x -- npm test` or `mise x -- ./my_script.sh`.
@@ -86,7 +86,7 @@ You can also set `MISE_LOG_FILE_LEVEL=debug MISE_LOG_FILE=/path/to/logfile` to w
 
 If something is happening with the activate hook, you can try disabling it and calling `eval "$(mise hook-env)"` manually.
 It can also be helpful to use `mise env` which will just output environment variables that would be set.
-Also consider using [shims](/shims) which can be more compatible.
+Also consider using [shims](/dev-tools/shims.md) which can be more compatible.
 
 If runtime installation isn't working right, try using the `--raw` flag which will install things in
 series and connect stdin/stdout/stderr directly to the terminal. If a plugin is trying to interact

faq.md

@@ -1,7 +1,3 @@
----
-outline: 'deep'
----
-
 # Getting Started
 
 Using mise typically involves 3 steps:
@@ -31,7 +27,7 @@ mise 2024.x.x
 
 ### 2. Activate mise <Badge type="tip" text="optional" />
 
-`mise activate` is one way to setup mise but alternatively you can use [shims](./shims), [direnv](./direnv), or skip
+`mise activate` is one way to setup mise but alternatively you can use [shims](dev-tools/shims.md), [direnv](./direnv), or skip
 this step entirely. If you skip it, then tools like `npm` and `node` will not be in PATH. You'll need to prefix
 commands with `mise exec` or run tasks with `mise run` in order to use tools managed with mise.
 

getting-started.md

@@ -23,7 +23,7 @@ hero:
       link: https://discord.gg/UBa7pJUN7Z
 
 features:
-  - title: <a href="/dev-tools.html">Dev Tools</a>
+  - title: <a href="/dev-tools/">Dev Tools</a>
     details: mise is a polyglot tool version manager. It replaces tools like <a href="https://asdf-vm.com">asdf</a>, nvm, pyenv, rbenv, etc.
   - title: <a href="/environments.html">Environments</a>
     details: mise allows you to switch sets of env vars in different project directories. It can replace <a href="https://github.com/direnv/direnv">direnv</a>.

index.md

@@ -1,7 +1,3 @@
----
-outline: 'deep'
----
-
 # Python
 
 The following are instructions for using the python mise core plugin. The core plugin will be used so long as no plugin is manually

lang/python.md

@@ -14,13 +14,13 @@ time. They can be easily overridden by installing a plugin with the same name, e
 
 You can see the core plugins with `mise plugin ls --core`.
 
-- [Bun](./lang/bun)
-- [Deno](./lang/deno)
-- [Go](./lang/go)
-- [Java](./lang/java)
-- [NodeJS](./lang/node)
-- [Python](./lang/python)
-- [Ruby](./lang/ruby)
+- [Bun](/lang/bun)
+- [Deno](/lang/deno)
+- [Go](/lang/go)
+- [Java](/lang/java)
+- [NodeJS](/lang/node)
+- [Python](/lang/python)
+- [Ruby](/lang/ruby)
 
 ## Plugin Authors
 

plugins.md

@@ -37,7 +37,6 @@ const board = [
   }
 ]
 </script>
-
 # Team
 
 Jeff Dickey is the primary developer behind mise. He does the bulk