| description | Preview and build the mise documentation site, and follow its rules for pages, examples, links, style, and generated reference content. |
|---|
This directory holds the mise documentation website, built with VitePress. This guide is for contributors; the site does not publish it. Run the commands below from the repository root.
Install the repository's development tools with mise install, then start the site:
mise run docsOpen the local URL printed by VitePress. Edits reload automatically.
Before submitting a change, build the production site:
mise run docs:buildThe task installs JavaScript dependencies, runs the social image and redirect
tests, and builds the site. It then checks the generated social images and
every internal link, including section anchors and links written in raw HTML or
Vue components. Use mise run docs:preview to serve the production build
locally.
To re-record docs/tapes/demo.gif and docs/tapes/demo.mp4 after changing
docs/tapes/demo.tape, start Docker and run mise run docs:demos.
| Content | Location |
|---|---|
| Project introduction and a short runnable example | Root README.md |
| Website overview and entry points | docs/index.md and the hero in docs/.vitepress/theme/HomeHero.vue |
| First tool, environment variable, and task | docs/getting-started.md |
| Adding mise to an existing project | docs/walkthrough.md |
| Shell activation and completions | docs/shell-setup.md |
| Feature guides | Each feature's directory, such as docs/dev-tools/, and its overview page |
| Configuration reference | docs/configuration.md and docs/configuration/ |
| Site navigation | docs/.vitepress/sidebar.ts |
| Generated command reference | docs/cli/, generated from the sources in Generated content |
Put detailed behavior in the relevant feature guide and link to it from onboarding pages. Keep the README short enough for someone deciding whether to try mise.
- Changing a page's title or H1 keeps its URL. Make the page's label in
docs/.vitepress/sidebar.tsmatch the new H1. - Moving, renaming, or removing a page file changes its URL. Add an entry to
pageRedirectsindocs/.vitepress/redirects.mjsso the old URL sends readers to the new page. - Moving a section to another page breaks links to its anchor. Add an
anchorRedirectsentry from/old-page.html#old-idto its new location. - Rewording a heading changes its anchor. Keep the old anchor with an explicit
ID such as
{#activate-mise}. Released mise binaries print some docs URLs, so searchsrc/,crates/, andsettings.tomlas well asdocs/before you rename a heading.
- State prerequisites, the working directory, and whether shell activation is required.
- Include every file, tool, and dependency needed for a runnable example. Label excerpts and illustrations.
- Explain what a command changes: installing a tool, saving a version request, or running a process.
- Use a small observable result, such as printing an environment variable. Avoid live deployment as a first example.
- Distinguish version requests from exact pins and lockfile resolutions. Avoid output that becomes stale with each release.
- Keep platform-specific commands in labeled code groups. Use
mise execormise runwhen activation is unnecessary. - Use
packslip,aqua, orgithubbackends in examples, not the deprecatedubi.
Use descriptive headings and link text. Internal website links start at the
docs root and end in .html, for example /dev-tools/backends/github.html, or
in / for a section index, such as /dev-tools/.
The docs use TOML 1.1. Multiline inline tables, comments inside them, and trailing commas are valid. Keep that syntax when it makes an example easier to read:
[tools]
node = {
version = "24", # a version request, not an exact pin
}Validate snippets with the repository's built mise (mise fmt --stdin) or
another TOML 1.1 parser. A TOML 1.0-only validator can incorrectly reject valid
examples. Parse each complete example separately, and label fragments that need
surrounding configuration. Alternative definitions of the same TOML key must
be separate examples or commented out.
The schema_matches_parser unit test reads every toml block as a whole
mise.toml and fails when schema/mise.json and mise's parser disagree on it.
It leaves out blocks titled with a file that is not a mise config, such as
[mise.lock]. Put <!-- schema: skip --> on the line above any
other block that is not a whole mise config, such as an excerpt or a registry
file, and <!-- schema: invalid --> above an example of a mistake, which the
schema must then reject.
The docs_show_commands_that_exist unit test
(cargo test -p mise --bin mise docs_commands) walks every mise ... command
in a shell block, a block with no language or an inline code span through the
usage spec and fails on a subcommand or flag mise does not have. A command is
read where mise starts it, also behind a prompt, sudo or env; a mise
that another program is handed as an argument is not. Give a block
of output the text language. The test checks nothing on Windows, where it
still reports a pass, so run it on Linux or macOS. It does not check values, so
placeholders such as <tool> are fine. Text that starts with mise and is not
a command to type, such as a message mise prints or the mise <task>
shorthand, needs <!-- cli: skip -->: on its own line above a fenced block or
a heading, or directly after the inline code with no space between.
The quoted_messages_are_in_the_source unit test reads docs/errors.md and
fails when a message it quotes is no longer in the Rust source: every code
span in a heading, and every code span in the body that is not a single word,
a mise command line, or a config line. Write the parts that vary as
<placeholders>, keep each code span on one line, and update the page when a
message is reworded. For a message the test cannot find because mise builds it
from several strings or a dependency words it, add
<!-- errors: unchecked `the message as quoted`: reason --> on its own
line. The test does not find messages that are missing from the page.
- Write for a developer who knows their shell but not mise. Use "you", the present tense, and the active voice, and describe what mise does rather than selling it.
- Write
misein lowercase, even at the start of a sentence, and use sentence case for headings. - Give every page a frontmatter
description: one sentence of 50 to 160 characters that starts with a verb. The paragraph under the H1 becomes the page's summary inllms.txt, so make it a complete statement on its own. - Say each fact once, where it belongs, and link to it from other pages.
- Cut throat-clearing openers ("This page explains"), recap sections, history asides about what an option used to do, filler ("Note that", "simply"), and marketing words ("powerful", "seamless", "modern").
- Do not use em dashes, bold-label bullet lists ("Feature: text"), or "will" for current behavior.
- Use VitePress containers such as
::: tipand::: warningat most once per section, and never for a required step.
Never edit generated files: docs/cli/, mise.usage.kdl, man/,
schema/*.json, and docs/public/llms.txt. Check for a generated-file comment
before editing any reference page.
Each CLI page in docs/cli/ combines three sources:
- The command's help text, arguments, flags, and examples come from its clap
definition in
src/cli/. - Source-code links and argument completions come from
src/assets/mise-extra.usage.kdl. - The "Related documentation" links at the end of each page come from the
guidesmap indocs/.vitepress/cli-reference.ts. Update it when you add a command or move the page a guide points to; the render fails when a guide points to a page that no longer exists.
After changing any of them, run mise run render:usage.
For settings, edit settings.toml and run mise run render:schema as described
in AGENTS.md. The settings
page renders settings.toml when the site builds. Review generated diffs and
keep unrelated changes out of the patch.
Rebuild the LLM index with mise run render:llms after changing page titles,
introductory content, or the page list. It writes docs/public/llms.txt from the
source pages; do not maintain that index by hand. Regenerate it after rebasing
so it reflects the pages on the PR's base.
Check formatting with the repository's lint tools, build the site, and inspect
changed pages in the browser. Check narrow and wide layouts when changing the
homepage or theme. Follow the new-reader path and verify that commands, filenames,
and expected results agree across the README and website. Settings anchors keep
the dots and underscores of the setting name, such as #task.output, while
Markdown headings use VitePress's slug rules; the build's link check reports a
link to an anchor that does not exist.
The homepage plays a showreel under the hero when the build has one. It is
rendered, never committed: docs/public/showreel*.mp4 and
docs/public/showreel-poster.jpg are gitignored.
mise run docs:showreel # render it from the captures on this machine
mise run docs:showreel -- --capture # record the terminal captures first if they are out of dateRendering needs ffmpeg and Playwright's Chromium headless shell
(aube exec playwright-core install chromium-headless-shell); recording the
captures needs Docker. With a render in docs/public, mise run docs:build
adds the player and the homepage's og:video, and points "Watch the demo" at
it. To build the site without it, as the docs workflow does for pull requests,
delete docs/public/showreel*.mp4 and docs/public/showreel-poster.jpg. For a
draft of part of the reel, run aube run showreel:video --help. The storyboard,
art spec, and capture rig are in docs/.vitepress/theme/showreel/ and
docs/.vitepress/showreel-capture/.
You never need to commit or upload a render. The docs deploy renders the reel
itself and caches the result. It renders again when the reel's code, fonts,
song, renderer, or capture rig changes, or when the capture set's key changes
(the capture rig's README says what the key covers). To force a new recording
and render, run the docs workflow by hand with rerender-showreel.