afrigon · Sep 7, 2026 · Sep 7, 2026 · Sep 7, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -14,6 +14,8 @@ Tools and tasks are defined in `mise.toml`: `mise run build`, `mise run test`, `
 
 The mdBook under `docs/` is the user-facing documentation. Every change to commands, the manifest format, environment variables, or user-visible runtime behavior must update the affected pages under `docs/src/` in the same change. The book documents behavior, not internals: keep prose generic (instance, Minecraft binary, mod loader, mod registry) and name concrete implementations (`fabric`, `modrinth`, `graal@25`) only where a reference page lists accepted values.
 
+Fenced code blocks in the book use exactly these languages: `kdl` for manifest and lockfile excerpts, `sh` for commands the reader types (no `$` prompt, one command per line), `ini` for systemd unit files, and `text` for everything else (command synopses, program output, directory trees, file contents). A command and its output never share a block: the output goes in a `text` block right after the `sh` block.
+
 ## Operational model
 
 - **One server per directory.** Each instance is a directory with `mc.kdl` at its root; the process CWD is always that root, and all cwd-relative paths in the code are correct by design (the scattered "fix this path / use a data path" TODOs are won't-fix under this model).

diff --git a/docs/src/commands/add.md b/docs/src/commands/add.md
@@ -22,7 +22,7 @@ any required dependencies — see [Managing Mods](../guides/mods.md).
 
 ## Examples
 
-```console
-$ mc add lithium
-$ mc add carpet servux
+```sh
+mc add lithium
+mc add carpet servux
 ```
diff --git a/docs/src/commands/allow.md b/docs/src/commands/allow.md
@@ -23,8 +23,8 @@ The list is still edited when `allow-list` in the `server` section is
 `#false`, but a warning points out that anyone can join until it is
 turned back on.
 
-```console
-$ mc allow add Notch jeb_
+```sh
+mc allow add Notch jeb_
 ```
 
 ### Options
@@ -41,8 +41,8 @@ mc allow remove [OPTIONS] <NAME>...
 Removes players from the allow list. Fails if a player is not on it. On a
 running instance, a removed player who is online is disconnected.
 
-```console
-$ mc allow remove Notch
+```sh
+mc allow remove Notch
 ```
 
 ### Options

diff --git a/docs/src/commands/backup.md b/docs/src/commands/backup.md
@@ -42,7 +42,7 @@ run.
 
 ## Examples
 
-```console
-$ mc backup
-$ mc backup --name pre-update
+```sh
+mc backup
+mc backup --name pre-update
 ```
diff --git a/docs/src/commands/ban.md b/docs/src/commands/ban.md
@@ -24,10 +24,10 @@ reported with a warning.
 Every player and address named in one command shares the same reason and
 expiry.
 
-```console
-$ mc ban add Griefer --reason "stole the beacon"
-$ mc ban add Griefer1 Griefer2 --for 7d
-$ mc ban add --ip 203.0.113.7 --ip 203.0.113.8 --until 2026-12-31T00:00:00Z
+```sh
+mc ban add Griefer --reason "stole the beacon"
+mc ban add Griefer1 Griefer2 --for 7d
+mc ban add --ip 203.0.113.7 --ip 203.0.113.8 --until 2026-12-31T00:00:00Z
 ```
 
 ### Options
@@ -51,9 +51,9 @@ mc ban remove [OPTIONS] --ip <ADDRESS>...
 Lifts bans on players, or with `--ip`, addresses. A player or address that
 is not banned is skipped with a warning.
 
-```console
-$ mc ban remove Griefer1 Griefer2
-$ mc ban remove --ip 203.0.113.7
+```sh
+mc ban remove Griefer1 Griefer2
+mc ban remove --ip 203.0.113.7
 ```
 
 ### Options

diff --git a/docs/src/commands/completions.md b/docs/src/commands/completions.md
@@ -9,17 +9,17 @@ shells: `bash`, `elvish`, `fish`, `powershell`, `zsh`.
 
 Install it wherever the shell loads completions from. For example:
 
-```console
-$ mc completions fish > ~/.config/fish/completions/mc.fish
-$ mc completions bash > ~/.local/share/bash-completion/completions/mc
-$ mc completions zsh > ~/.zfunc/_mc
+```sh
+mc completions fish > ~/.config/fish/completions/mc.fish
+mc completions bash > ~/.local/share/bash-completion/completions/mc
+mc completions zsh > ~/.zfunc/_mc
 ```
 
 The script describes the commands and options of the binary that generated
 it; regenerate it after upgrading mc.
 
 ## Examples
 
-```console
-$ mc completions fish > ~/.config/fish/completions/mc.fish
+```sh
+mc completions fish > ~/.config/fish/completions/mc.fish
 ```
diff --git a/docs/src/commands/help.md b/docs/src/commands/help.md
@@ -7,9 +7,9 @@ mc help [COMMAND]
 Prints help for `mc` or for the given command. Equivalent to passing
 `--help`:
 
-```console
-$ mc help init
-$ mc init --help
+```sh
+mc help init
+mc init --help
 ```
 
 The top-level help, `mc help` or `mc --help`, ends with a link to this

diff --git a/docs/src/commands/init.md b/docs/src/commands/init.md
@@ -34,8 +34,8 @@ not a fixed template.
 
 ## Examples
 
-```console
-$ mc init myserver
-$ mc init --preset technical --eula
-$ mc init myserver --name "smp" --preset vanilla
+```sh
+mc init myserver
+mc init --preset technical --eula
+mc init myserver --name "smp" --preset vanilla
 ```
diff --git a/docs/src/commands/java.md b/docs/src/commands/java.md
@@ -12,8 +12,11 @@ Lists the runtimes mc can install, as `vendor@version` descriptors. The one
 marked `(recommended)` is the default used when the manifest does not
 configure `version` under `java`.
 
-```console
-$ mc java list
+```sh
+mc java list
+```
+
+```text
 graal@25 (recommended)
 graal@21
 ...
@@ -41,7 +44,7 @@ command exists to provision one ahead of time.
 
 ### Examples
 
-```console
-$ mc java install graal@25
-$ mc java install corretto@21
+```sh
+mc java install graal@25
+mc java install corretto@21
 ```
diff --git a/docs/src/commands/minecraft.md b/docs/src/commands/minecraft.md
@@ -58,7 +58,7 @@ command exists to provision one ahead of time.
 
 ### Examples
 
-```console
-$ mc minecraft install
-$ mc minecraft install --loader fabric
+```sh
+mc minecraft install
+mc minecraft install --loader fabric
 ```
diff --git a/docs/src/commands/op.md b/docs/src/commands/op.md
@@ -21,9 +21,9 @@ next restart, which is reported with a warning.
 
 Every player named in one command gets the same settings.
 
-```console
-$ mc op add Notch
-$ mc op add jeb_ Dinnerbone --level 2 --bypass-player-limit
+```sh
+mc op add Notch
+mc op add jeb_ Dinnerbone --level 2 --bypass-player-limit
 ```
 
 ### Options
@@ -44,8 +44,8 @@ mc op remove [OPTIONS] <NAME>...
 Removes operators. A player who is not an operator is skipped with a
 warning.
 
-```console
-$ mc op remove Notch
+```sh
+mc op remove Notch
 ```
 
 ### Options

diff --git a/docs/src/commands/remove.md b/docs/src/commands/remove.md
@@ -18,6 +18,6 @@ lockfile and is uninstalled along with it.
 
 ## Examples
 
-```console
-$ mc remove carpet
+```sh
+mc remove carpet
 ```
diff --git a/docs/src/commands/restore.md b/docs/src/commands/restore.md
@@ -38,12 +38,18 @@ undoing again swaps back.
 
 ## Examples
 
-```console
-$ mc restore --list
+```sh
+mc restore --list
+```
+
+```text
 myserver_pre-update.tar.gz
 myserver_2026-07-15_15-00-00.tar.gz (latest)
 myserver_2026-07-14_15-00-00.tar.gz
-$ mc restore
-$ mc restore --backup myserver_pre-update.tar.gz
-$ mc restore --undo
+```
+
+```sh
+mc restore
+mc restore --backup myserver_pre-update.tar.gz
+mc restore --undo
 ```
diff --git a/docs/src/commands/tunnel.md b/docs/src/commands/tunnel.md
@@ -14,8 +14,11 @@ Lists the tunnel agent versions mc can install, most recent first. The one
 marked `(latest)` is what `provider` under `tunnel` resolves to when its version
 half is omitted or set to `latest`.
 
-```console
-$ mc tunnel list
+```sh
+mc tunnel list
+```
+
+```text
 1.0.10 (latest)
 1.0.9
 ...
@@ -48,9 +51,9 @@ command exists to provision one ahead of time.
 
 ### Examples
 
-```console
-$ mc tunnel install
-$ mc tunnel install playit@1.0.9
+```sh
+mc tunnel install
+mc tunnel install playit@1.0.9
 ```
 
 ## mc tunnel claim
@@ -78,8 +81,11 @@ or to replace an existing secret.
 
 ### Examples
 
-```console
-$ mc tunnel claim
+```sh
+mc tunnel claim
+```
+
+```text
     Claiming tunnel agent, approve it at https://playit.gg/claim/... with your playit.gg account
      Claimed tunnel agent secret saved to .tunnel/playit.toml
 ```
diff --git a/docs/src/commands/update.md b/docs/src/commands/update.md
@@ -18,7 +18,7 @@ The new versions are installed the next time the instance starts.
 
 ## Examples
 
-```console
-$ mc update
-$ mc update lithium carpet
+```sh
+mc update
+mc update lithium carpet
 ```
diff --git a/docs/src/first-steps.md b/docs/src/first-steps.md
@@ -7,9 +7,9 @@ This walkthrough creates a new instance and runs it.
 Each instance lives in its own directory, with a `mc.kdl` manifest at its
 root. [`mc init`](./commands/init.md) creates both:
 
-```console
-$ mc init myserver
-$ cd myserver
+```sh
+mc init myserver
+cd myserver
 ```
 
 The generated manifest looks like this:
@@ -65,8 +65,8 @@ You can also pass `--eula` to `mc init` to do this at creation time.
 
 ## Run it
 
-```console
-$ mc run
+```sh
+mc run
 ```
 
 On first run, mc downloads a Java runtime, the Minecraft binary, the mod

diff --git a/docs/src/guides/backups.md b/docs/src/guides/backups.md
@@ -118,11 +118,17 @@ notification never fails the backup itself.
 
 List the available backups, then restore one:
 
-```console
-$ mc restore --list
+```sh
+mc restore --list
+```
+
+```text
 myserver_2026-07-15_15-00-00.tar.gz (latest)
 myserver_2026-07-14_15-00-00.tar.gz
-$ mc restore --backup myserver_2026-07-14_15-00-00.tar.gz
+```
+
+```sh
+mc restore --backup myserver_2026-07-14_15-00-00.tar.gz
 ```
 
 Without `--backup`, the most recent backup is restored. The instance must be

diff --git a/docs/src/guides/mods.md b/docs/src/guides/mods.md
@@ -29,19 +29,19 @@ the `modrinth` group for you. `mc add` looks the mod up on the registry and pins
 the latest version compatible with the configured Minecraft version and
 loader:
 
-```console
-$ mc add sodium lithium
-$ mc remove sodium
+```sh
+mc add sodium lithium
+mc remove sodium
 ```
 
 ## Updating mods
 
 [`mc update`](../commands/update.md) re-pins mods to the latest compatible
 version — every mod in the manifest, or only the ones you name:
 
-```console
-$ mc update
-$ mc update lithium
+```sh
+mc update
+mc update lithium
 ```
 
 Mods fetched from a direct URL have no version to compare and are skipped.

diff --git a/docs/src/guides/players.md b/docs/src/guides/players.md
@@ -32,11 +32,11 @@ of the allow list.
 [`mc op`](../commands/op.md) edit the section for you. Each has `add`,
 `remove`, and `list` subcommands:
 
-```console
-$ mc allow add Notch jeb_
-$ mc ban add Griefer --reason "stole the beacon" --for 7d
-$ mc op add Notch
-$ mc op list
+```sh
+mc allow add Notch jeb_
+mc ban add Griefer --reason "stole the beacon" --for 7d
+mc op add Notch
+mc op list
 ```
 
 Names are looked up when added, so a typo fails at the command rather

diff --git a/docs/src/guides/systemd.md b/docs/src/guides/systemd.md
@@ -28,8 +28,8 @@ WantedBy=multi-user.target
 
 Then enable and start it:
 
-```console
-$ systemctl enable --now myserver
+```sh
+systemctl enable --now myserver
 ```
 
 `WorkingDirectory` must be the instance root — the directory containing
@@ -39,10 +39,9 @@ $ systemctl enable --now myserver
 
 Environment variables such as `MC_RCON_PASSWORD` or a notification webhook
 are best kept out of the unit file, in an `EnvironmentFile` readable only by
-root:
+root, such as `/etc/minecraft/myserver.env`:
 
-```console
-$ cat /etc/minecraft/myserver.env
+```text
 MC_RCON_PASSWORD=...
 MC_DISCORD_WEBHOOK=...
 ```
@@ -68,8 +67,8 @@ With `--server-logs`, the instance's console output goes to standard output,
 which systemd captures in the journal (add `--tunnel-logs` to capture the
 tunnel agent as well):
 
-```console
-$ journalctl -u myserver -f
+```sh
+journalctl -u myserver -f
 ```
 
 mc's own log verbosity is controlled by the global `--verbose` flag; the