From c6c59f5c68cd1450e8bf7b5f3e6948a85922be31 Mon Sep 17 00:00:00 2001 From: jdx <216188+jdx@users.noreply.github.com> Date: Mon, 14 Jul 2025 00:30:54 -0500 Subject: [PATCH] docs: tweak static backend docs --- docs/components/settings.vue | 37 +++++++++++++++++++------------ docs/configuration.md | 2 +- docs/dev-tools/backends/github.md | 21 ++++++------------ docs/dev-tools/backends/gitlab.md | 16 +++++-------- docs/dev-tools/backends/http.md | 8 +++++-- docs/faq.md | 10 +++++++-- docs/getting-started.md | 2 +- docs/plugin-usage.md | 8 +++++-- docs/troubleshooting.md | 4 ++-- 9 files changed, 60 insertions(+), 48 deletions(-) diff --git a/docs/components/settings.vue b/docs/components/settings.vue index 2bb536e01e..6c5f116c26 100644 --- a/docs/components/settings.vue +++ b/docs/components/settings.vue @@ -6,6 +6,9 @@ const { child } = defineProps(["child", "level"]); const settings = child ? (data.find((f) => f.key === child)?.settings ?? []) : data; + +// Check if there are any settings to display +const hasSettings = settings.some((f) => f.type) || settings.some((f) => !f.type); @@ -20,23 +23,29 @@ const settings = child diff --git a/docs/configuration.md b/docs/configuration.md index 5da697a7e0..4814728fd0 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -93,7 +93,7 @@ Different configuration sections merge in different ways: # Result: experimental = true, jobs = 4 ``` -:::tip +::: tip Run `mise config` to see what files mise has loaded in order of precedence. ::: diff --git a/docs/dev-tools/backends/github.md b/docs/dev-tools/backends/github.md index a5e6dddb25..c922ad3f65 100644 --- a/docs/dev-tools/backends/github.md +++ b/docs/dev-tools/backends/github.md @@ -43,7 +43,9 @@ For most tools, you can simply install without specifying patterns: mise install github:user/repo ``` -> **Note:** The autodetection logic is implemented in [`src/backend/asset_detector.rs`](https://github.com/jdx/mise/blob/main/src/backend/asset_detector.rs), which is shared by both the GitHub and GitLab backends. +::: tip +The autodetection logic is implemented in [`src/backend/asset_detector.rs`](https://github.com/jdx/mise/blob/main/src/backend/asset_detector.rs), which is shared by both the GitHub and GitLab backends. +::: ### `asset_pattern` @@ -131,7 +133,9 @@ Number of directory components to strip when extracting archives: "github:cli/cli" = { version = "latest", strip_components = 1 } ``` -**Auto-detection:** If `strip_components` is not explicitly set, mise will automatically detect when to apply `strip_components = 1`. This happens when the extracted archive contains exactly one directory at the root level and no files. This is common with tools like ripgrep that package their binaries in a versioned directory (e.g., `ripgrep-14.1.0-x86_64-unknown-linux-musl/rg`). The auto-detection ensures the binary is placed directly in the install path where mise expects it. +::: info +If `strip_components` is not explicitly set, mise will automatically detect when to apply `strip_components = 1`. This happens when the extracted archive contains exactly one directory at the root level and no files. This is common with tools like ripgrep that package their binaries in a versioned directory (e.g., `ripgrep-14.1.0-x86_64-unknown-linux-musl/rg`). The auto-detection ensures the binary is placed directly in the install path where mise expects it. +::: ### `bin_path` @@ -156,10 +160,7 @@ For GitHub Enterprise or self-hosted GitHub instances, specify the API URL: ```toml [tools] -"github:myorg/mytool" = { - version = "latest", - api_url = "https://github.mycompany.com/api/v3" -} +"github:myorg/mytool" = { version = "latest", api_url = "https://github.mycompany.com/api/v3" } ``` ## Self-hosted GitHub @@ -181,11 +182,3 @@ export MISE_GITHUB_ENTERPRISE_TOKEN="your-token" import Settings from '/components/settings.vue'; - -::: warning -The GitHub backend is experimental and requires the `mise.experimental` setting to be enabled: - -```sh -mise settings set experimental true -``` -::: diff --git a/docs/dev-tools/backends/gitlab.md b/docs/dev-tools/backends/gitlab.md index 4a29fcedf2..94b380c0f1 100644 --- a/docs/dev-tools/backends/gitlab.md +++ b/docs/dev-tools/backends/gitlab.md @@ -43,7 +43,9 @@ For most tools, you can simply install without specifying patterns: mise install gitlab:user/repo ``` -> **Note:** The autodetection logic is implemented in [`src/backend/asset_detector.rs`](https://github.com/jdx/mise/blob/main/src/backend/asset_detector.rs), which is shared by both the GitHub and GitLab backends. +::: tip +The autodetection logic is implemented in [`src/backend/asset_detector.rs`](https://github.com/jdx/mise/blob/main/src/backend/asset_detector.rs), which is shared by both the GitHub and GitLab backends. +::: ### `asset_pattern` @@ -145,7 +147,9 @@ Number of directory components to strip when extracting archives: "gitlab:gitlab-org/gitlab-runner" = { version = "latest", strip_components = 1 } ``` -**Auto-detection:** If `strip_components` is not explicitly set, mise will automatically detect when to apply `strip_components = 1`. This happens when the extracted archive contains exactly one directory at the root level and no files. This is common with tools like ripgrep that package their binaries in a versioned directory (e.g., `ripgrep-14.1.0-x86_64-unknown-linux-musl/rg`). The auto-detection ensures the binary is placed directly in the install path where mise expects it. +::: info +If `strip_components` is not explicitly set, mise will automatically detect when to apply `strip_components = 1`. This happens when the extracted archive contains exactly one directory at the root level and no files. This is common with tools like ripgrep that package their binaries in a versioned directory (e.g., `ripgrep-14.1.0-x86_64-unknown-linux-musl/rg`). The auto-detection ensures the binary is placed directly in the install path where mise expects it. +::: ### `bin_path` @@ -192,11 +196,3 @@ export MISE_GITLAB_ENTERPRISE_TOKEN="your-token" import Settings from '/components/settings.vue'; - -::: warning -The GitLab backend is experimental and requires the `mise.experimental` setting to be enabled: - -```sh -mise settings set experimental true -``` -::: diff --git a/docs/dev-tools/backends/http.md b/docs/dev-tools/backends/http.md index 69b722c68c..462f0399ff 100644 --- a/docs/dev-tools/backends/http.md +++ b/docs/dev-tools/backends/http.md @@ -51,7 +51,9 @@ macos-arm64 = { url = "https://example.com/releases/my-tool-v1.0.0-macos-arm64.t linux-x64 = { url = "https://example.com/releases/my-tool-v1.0.0-linux-x64.tar.gz" } ``` -> **Note:** You can use either `macos` or `darwin`, and `x64` or `amd64` for platform keys. `macos` and `x64` are preferred in documentation and examples, but all variants are accepted. +::: tip +You can use either `macos` or `darwin`, and `x64` or `amd64` for platform keys. `macos` and `x64` are preferred in documentation and examples, but all variants are accepted. +::: ### `checksum` @@ -114,7 +116,9 @@ url = "https://example.com/releases/my-tool-v1.0.0.tar.gz" strip_components = 1 ``` -**Auto-detection:** If `strip_components` is not explicitly set, mise will automatically detect when to apply `strip_components = 1`. This happens when the extracted archive contains exactly one directory at the root level and no files. This is common with tools like ripgrep that package their binaries in a versioned directory (e.g., `ripgrep-14.1.0-x86_64-unknown-linux-musl/rg`). The auto-detection ensures the binary is placed directly in the install path where mise expects it. +::: info +If `strip_components` is not explicitly set, mise will automatically detect when to apply `strip_components = 1`. This happens when the extracted archive contains exactly one directory at the root level and no files. This is common with tools like ripgrep that package their binaries in a versioned directory (e.g., `ripgrep-14.1.0-x86_64-unknown-linux-musl/rg`). The auto-detection ensures the binary is placed directly in the install path where mise expects it. +::: ### `bin_path` diff --git a/docs/faq.md b/docs/faq.md index 9526ebada1..ad23d982e1 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -77,12 +77,14 @@ and `mise deactivate` to work without wrapping them in `eval "$(mise shell)"`. ## Windows support? +::: warning While mise runs great in WSL, native Windows is also supported, though via the use of shims until someone adds [powershell](https://github.com/jdx/mise/issues/3451) support. As you'll need to use shims, this means you won't have environment variables from mise.toml unless you run mise via [`mise x`](/cli/exec) or [`mise run`](/cli/run)—though that's actually how I use mise on my mac so for me that's my preferred workflow anyway. +::: ## How do I use mise with http proxies? @@ -131,8 +133,10 @@ wouldn't want to install a version that is already installed. - remove asdf from your shell rc file - Run `mise install` in a directory with an asdf `.tool-versions` file and mise will install the tools +::: info Note that `mise` does not consider `~/.tool-versions` files to be a global config file like `asdf` does. `mise` uses a `~/.config/mise/config.toml` file for global configuration. +::: Here is an example script you can use to migrate your global `.tool-versions` file to mise: @@ -152,11 +156,13 @@ multiple tools can be specified at once. However, asdf-style syntax is still sup install node 20.0.0`). This is the case for most commands, though the help for the command may say that asdf-style syntax is supported. When in doubt, just try asdf syntax and see if it works—it probably does. +::: info UPDATE (2025-01-01): mise was designed to be compatible with the asdf written in bash (<=0.15). The new asdf written in go (>=0.16) has commands mise does not support like `asdf set`. `mise set` is an existing command that is completely different than `asdf set`—in mise that sets env vars. This isn't important for usability reasons so much as making it so plugins continue to work that call asdf commands inside of the plugin code. +::: Using commands like `mise use` may output `.tool-versions` files that are not compatible with asdf, such as using fuzzy versions. You can set `--pin` or `MISE_PIN=1` to make `mise use` output asdf-compatible versions @@ -172,8 +178,8 @@ teams which use both in tandem, issues with such a setup are unlikely to be prio mise uses [console.rs](https://docs.rs/console/latest/console/fn.colors_enabled.html) which honors the [clicolors spec](https://bixense.com/clicolors/): -- `CLICOLOR != 0`: ANSI colors are supported and should be used when the program isn’t piped. -- `CLICOLOR == 0`: Don’t output ANSI color escape codes. +- `CLICOLOR != 0`: ANSI colors are supported and should be used when the program isn't piped. +- `CLICOLOR == 0`: Don't output ANSI color escape codes. - `CLICOLOR_FORCE != 0`: ANSI colors should be enabled no matter what. ## Is mise secure? diff --git a/docs/getting-started.md b/docs/getting-started.md index a2bcceb352..521ef335c6 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -115,7 +115,7 @@ mise exec -- node my-script.js Another useful command is [`mise r|run`](/cli/run.html) which allows you to run a [`mise task`](/tasks/) or a script with the `mise` context. -:::tip +::: tip You can set a shell alias in your shell's rc file like `alias x="mise x --"` to save some keystrokes. ::: diff --git a/docs/plugin-usage.md b/docs/plugin-usage.md index 0240573f89..1bb4c50a12 100644 --- a/docs/plugin-usage.md +++ b/docs/plugin-usage.md @@ -161,7 +161,9 @@ mise use vfox-npm:prettier@latest mise exec vfox-npm:prettier -- --check . ``` -**Note**: This is just an example plugin for testing. mise already has built-in npm support that you should use instead: `mise install npm:prettier@latest` +::: info +This is just an example plugin for testing. mise already has built-in npm support that you should use instead: `mise install npm:prettier@latest` +::: ## Backend Plugins (Advanced) @@ -186,12 +188,14 @@ Both architectures provide a flexible plugin system that can handle diverse inst ## Security Considerations +::: danger When using plugins, be aware that: - **Plugins execute arbitrary code** during installation and use - **Only install plugins from trusted sources** - **Review plugin code** before installation when possible -- **Use version pinning** to avoid unexpected updates +- **Use version pinning** to avoid unexpected updates like [`mise.lock`](/dev-tools/mise-lock.md) +::: ## Troubleshooting diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 4bfd6af8af..342cfd62cc 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -86,11 +86,11 @@ setting `MISE_USE_VERSIONS_HOST=0`. ## Windows problems +::: warning Very basic support for windows is currently available, however because Windows can't support asdf plugins, they must use core and vfox only—which means only a handful of tools are available on Windows. - -As of this writing, env var management and task execution are not yet supported on Windows. +::: ## mise isn't working when calling from tmux or another shell initialization script