From 5b126abcce67cc70fd96ce16cde8fb4de7a22b8a Mon Sep 17 00:00:00 2001 From: Alexandre Frigon Date: Mon, 7 Sep 2026 00:52:59 -0400 Subject: [PATCH] standardize documentation code blocks - sh for commands, without a prompt; text for output and synopses; kdl for manifests - convention recorded in CLAUDE.md Closes #16 --- CLAUDE.md | 2 ++ docs/src/commands/add.md | 6 +++--- docs/src/commands/allow.md | 8 ++++---- docs/src/commands/backup.md | 6 +++--- docs/src/commands/ban.md | 14 +++++++------- docs/src/commands/completions.md | 12 ++++++------ docs/src/commands/help.md | 6 +++--- docs/src/commands/init.md | 8 ++++---- docs/src/commands/java.md | 13 ++++++++----- docs/src/commands/minecraft.md | 6 +++--- docs/src/commands/op.md | 10 +++++----- docs/src/commands/remove.md | 4 ++-- docs/src/commands/restore.md | 16 +++++++++++----- docs/src/commands/tunnel.md | 20 +++++++++++++------- docs/src/commands/update.md | 6 +++--- docs/src/first-steps.md | 10 +++++----- docs/src/guides/backups.md | 12 +++++++++--- docs/src/guides/mods.md | 12 ++++++------ docs/src/guides/players.md | 10 +++++----- docs/src/guides/systemd.md | 13 ++++++------- docs/src/guides/tunnel.md | 7 +++++-- docs/src/installation.md | 20 ++++++++++---------- docs/src/introduction.md | 8 ++++---- 23 files changed, 127 insertions(+), 102 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index dc652f3..3f6a4b5 100644 --- 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 index 0ded73d..606d3b7 100644 --- 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 index 30c1d67..cdcb47a 100644 --- 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] ... 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 index 59d0d93..09e3c91 100644 --- 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 index c2c9162..d5f9c53 100644 --- 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
... 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 index 97516bd..04e1808 100644 --- a/docs/src/commands/completions.md +++ b/docs/src/commands/completions.md @@ -9,10 +9,10 @@ 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 @@ -20,6 +20,6 @@ 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 index c87a68c..e06d10e 100644 --- a/docs/src/commands/help.md +++ b/docs/src/commands/help.md @@ -7,7 +7,7 @@ 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 ``` diff --git a/docs/src/commands/init.md b/docs/src/commands/init.md index 120a93f..fd31965 100644 --- 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 index ea16fcf..4b1ba6d 100644 --- 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 index bd79b2d..3d38e36 100644 --- 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 index 7ce67e0..ee90eab 100644 --- 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] ... 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 index 3652e15..cbf7e4e 100644 --- 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 index 3f836eb..81ea997 100644 --- 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 index 7e70743..8da1237 100644 --- 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 index 72f54d5..966b344 100644 --- 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 index 102b1ef..9ffd76b 100644 --- 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 index 018dccd..28d78ca 100644 --- a/docs/src/guides/backups.md +++ b/docs/src/guides/backups.md @@ -117,11 +117,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 index a4d1dd9..2bea8fa 100644 --- a/docs/src/guides/mods.md +++ b/docs/src/guides/mods.md @@ -29,9 +29,9 @@ 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 @@ -39,9 +39,9 @@ $ mc remove sodium [`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 index a643d46..7f9cff7 100644 --- 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 index 12a9675..76492a4 100644 --- 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 diff --git a/docs/src/guides/tunnel.md b/docs/src/guides/tunnel.md index deca318..b50ab6e 100644 --- a/docs/src/guides/tunnel.md +++ b/docs/src/guides/tunnel.md @@ -26,8 +26,11 @@ Adding the section is enough — a bare `tunnel` node also works; see Start the instance from a terminal: -```console -$ mc run +```sh +mc run +``` + +```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 Creating a Minecraft tunnel for port 25565 diff --git a/docs/src/installation.md b/docs/src/installation.md index 8b19255..ffcb530 100644 --- a/docs/src/installation.md +++ b/docs/src/installation.md @@ -5,8 +5,8 @@ [mise](https://mise.jdx.dev) installs the latest release binary and puts it on your `PATH`: -```console -$ mise use -g github:afrigon/mc +```sh +mise use -g github:afrigon/mc ``` ## Pre-built binaries @@ -21,20 +21,20 @@ Every release publishes pre-built binaries on the Download the archive for your platform, extract it, and place the `mc` binary somewhere on your `PATH`: -```console -$ tar -xzf mc-linux-x86_64.tar.gz -$ install -m 755 mc /usr/local/bin/mc -$ mc --version +```sh +tar -xzf mc-linux-x86_64.tar.gz +install -m 755 mc /usr/local/bin/mc +mc --version ``` ## Building from source mc is written in Rust and builds with a recent stable toolchain: -```console -$ git clone https://github.com/afrigon/mc -$ cd mc -$ cargo build --release +```sh +git clone https://github.com/afrigon/mc +cd mc +cargo build --release ``` The binary is produced at `target/release/mc`. diff --git a/docs/src/introduction.md b/docs/src/introduction.md index 303d251..7bb8497 100644 --- a/docs/src/introduction.md +++ b/docs/src/introduction.md @@ -17,10 +17,10 @@ If you have used a package manager, the workflow will feel familiar: a declarative manifest, a generated lockfile, and a small set of commands that operate on them. -```console -$ mc init myserver --eula -$ cd myserver -$ mc run +```sh +mc init myserver --eula +cd myserver +mc run ``` ## Sections