docs: update cookbook (jdx#3718)

docs/.vitepress/config.ts

@@ -127,7 +127,21 @@ export default defineConfig({
           { text: "FAQs", link: "/faq" },
           { text: "Troubleshooting", link: "/troubleshooting" },
           { text: "Tips & Tricks", link: "/tips-and-tricks" },
-          { text: "Cookbook", link: "/mise-cookbook" },
+          {
+            text: "Cookbook",
+            link: "/mise-cookbook",
+            collapsed: true,
+            items: [
+              { text: "C++", link: "/mise-cookbook/cpp" },
+              { text: "Docker", link: "/mise-cookbook/docker" },
+              { text: "Node", link: "/mise-cookbook/nodejs" },
+              { text: "Ruby", link: "/mise-cookbook/ruby" },
+              { text: "Terraform", link: "/mise-cookbook/terraform" },
+              { text: "Python", link: "/mise-cookbook/python" },
+              { text: "Presets", link: "/mise-cookbook/presets" },
+              { text: "Shell tricks", link: "/mise-cookbook/shell-tricks" },
+            ],
+          },
           { text: "Team", link: "/team" },
           { text: "Roadmap", link: "/roadmap" },
           { text: "Contributing", link: "/contributing" },

docs/mise-cookbook/cpp.md

@@ -0,0 +1,47 @@
+# Mise + C++ Cookbook
+
+Here are some tips on managing C++ projects with mise.
+
+## A C++ Project with CMake
+
+```toml [mise.toml]
+min_version = "2024.9.5"
+
+[env]
+# Project information
+PROJECT_NAME = "{{ config_root | basename }}"
+
+# Build directory
+BUILD_DIR = "{{ config_root }}/build"
+
+[tools]
+# Install CMake and make
+cmake = "latest"
+make = "latest"
+
+[tasks.configure]
+description = "Configure the project"
+run = "mkdir -p $BUILD_DIR && cd $BUILD_DIR && cmake .."
+
+[tasks.build]
+description = "Build the project"
+alias = "b"
+run = "cd $BUILD_DIR && make"
+
+[tasks.clean]
+description = "Clean the build directory"
+alias = "c"
+run = "rm -rf $BUILD_DIR"
+
+[tasks.run]
+alias = "r"
+description = "Run the application"
+run = "$BUILD_DIR/bin/$PROJECT_NAME"
+
+[tasks.info]
+description = "Print project information"
+run = '''
+echo "Project: $PROJECT_NAME"
+echo "Build Directory: $BUILD_DIR"
+'''
+```

docs/mise-cookbook/docker.md

@@ -0,0 +1,59 @@
+# Mise + Docker Cookbook
+
+Here are some tips on using Docker with mise.
+
+## Docker image with mise
+
+Here is an example Dockerfile showing how to install mise in a Docker image.
+
+```Dockerfile [Dockerfile]
+FROM debian:12-slim
+
+RUN apt-get update  \
+    && apt-get -y --no-install-recommends install  \
+        # install any other dependencies you might need
+        sudo curl git ca-certificates build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+SHELL ["/bin/bash", "-o", "pipefail", "-c"]
+ENV MISE_DATA_DIR="/mise"
+ENV MISE_CONFIG_DIR="/mise"
+ENV MISE_CACHE_DIR="/mise/cache"
+ENV MISE_INSTALL_PATH="/usr/local/bin/mise"
+ENV PATH="/mise/shims:$PATH"
+# ENV MISE_VERSION="..."
+
+RUN curl https://mise.run | sh
+```
+
+Build and run the Docker image:
+
+```shell
+docker build -t debian-mise .
+docker run -it --rm debian-mise
+```
+
+## Task to run mise in a Docker container
+
+This can be useful use if you need to reproduce an issue you're having with mise in a clean environment.
+
+```toml [mise.toml]
+[tasks.docker]
+run = "docker run --pull=always -it --rm --entrypoint bash jdxcode/mise:latest"
+```
+
+Example usage:
+
+```shell
+❯ mise docker
+[docker] $ docker run --pull=always -it --rm --entrypoint bash jdxcode/mise:latest
+# latest: Pulling from jdxcode/mise
+# Digest: sha256:eecc479b6259479ffca5a4f9c68dbfe8631ca62dc59aa60c9ab5e4f6e9982701
+# Status: Image is up to date for jdxcode/mise:latest
+root@75f179a190a1:/mise# eval "$(mise activate bash)"
+root@75f179a190a1:/mise# echo "" >/mise/config.toml
+root@75f179a190a1:/mise# mise prune --yes
+mise pruned configuration links
+mise python@3.13.1 ✓ remove /mise/cache/python/3.13.1
+# ...
+```

docs/mise-cookbook/index.md

@@ -0,0 +1,16 @@
+# Cookbook
+
+Here we are sharing a few mise setups that other people have found useful.
+
+- [C++](cpp.md)
+- [Docker](docker.md)
+- [Node.JS](nodejs.md)
+- [Python](python.md)
+- [Ruby](ruby.md)
+- [Terraform](terraform.md)
+
+Finally, here is how to create [presets](presets.md) and some [shell tricks](shell-tricks.md) you might find useful.
+
+## Contributing
+
+If you would like to share your setup, please share it in this [cookbook thread](https://github.com/jdx/mise/discussions/3645).

docs/mise-cookbook/nodejs.md

@@ -0,0 +1,109 @@
+# Mise + Node.js Cookbook
+
+Here are some tips on managing Node.js projects with mise.
+
+## Add node modules binaries to the PATH
+
+A nice trick you can use is to add the node modules binaries to the PATH. This will make CLIs installed with npm available without `npx`.
+
+```toml [mise.toml]
+[env]
+_.path = ['./node_modules/.bin']
+```
+
+Example:
+
+```shell
+npm install --save eslint
+eslint --version # works
+```
+
+## Example Node.js Project
+
+```toml [mise.toml]
+min_version = "2024.9.5"
+
+[env]
+_.path = ['{{config_root}}/node_modules/.bin']
+
+# Use the project name derived from the current directory
+PROJECT_NAME = "{{ config_root | basename }}"
+
+# Set up the path for node module binaries
+BIN_PATH = "{{ config_root }}/node_modules/.bin"
+
+NODE_ENV = "{{ env.NODE_ENV | default(value='development') }}"
+
+[tools]
+# Install Node.js using the specified version
+node = "{{ env['NODE_VERSION'] | default(value='lts') }}"
+
+# Install some npm packages globally if needed
+"npm:typescript" = "latest"
+"npm:eslint" = "latest"
+"npm:jest" = "latest"
+
+[tasks.install]
+alias = "i"
+description = "Install npm dependencies"
+run = "npm install"
+
+[tasks.start]
+alias = "s"
+description = "Start the development server"
+run = "npm run start"
+
+[tasks.lint]
+alias = "l"
+description = "Run ESLint"
+run = "eslint src/"
+
+[tasks.test]
+description = "Run tests"
+alias = "t"
+run = "jest"
+
+[tasks.build]
+description = "Build the project"
+alias = "b"
+run = "npm run build"
+
+[tasks.info]
+description = "Print project information"
+run = '''
+echo "Project: $PROJECT_NAME"
+echo "NODE_ENV: $NODE_ENV"
+'''
+```
+
+## Example with `pnpm`
+
+This example uses `pnpm` as the package manager. This will skip installing dependencies if the lock file hasn't changed.
+
+```toml [mise.toml]
+[tools]
+node = '22'
+
+[hooks]
+post_install = 'corepack enable'
+
+[env]
+_.path = ['./node_modules/.bin']
+
+[tasks.pnpmInstall]
+description = 'Installs dependencies with pnpm'
+run = 'pnpm install'
+sources = ['package.json', 'pnpm-lock.yaml', 'mise.toml']
+outputs = ['node_modules/.pnpm/lock.yaml']
+
+[tasks.dev]
+description = 'Calls your dev script in `package.json`'
+run = 'node --run dev'
+depends = ['pnpmInstall']
+```
+
+With this setup, getting started in a NodeJS project is as simple as running `mise dev`:
+
+- `mise` will install the correct version of NodeJS
+- `mise` will enable `corepack`
+- `pnpm install` will be run before `node --run dev`

docs/mise-cookbook/presets.md

@@ -0,0 +1,71 @@
+# Presets
+
+You can create your own presets by leveraging [mise tasks](../tasks/index.md) to reduce boilerplate and make it easier to set up new projects.
+
+## Example python preset
+
+Here is an example of how to create your python preset that creates a `mise.toml` file to work with `python` and `pdm`
+
+```shell [~/.config/mise/tasks/preset/python]
+#!/usr/bin/env bash
+#MISE dir="{{cwd}}"
+
+mise use pre-commit
+mise config set env._.python.venv.path .venv
+mise config set env._.python.venv.create true -t bool
+mise tasks add lint -- pre-commit run -a
+```
+
+```shell [~/.config/mise/tasks/preset/pdm]
+#!/usr/bin/env bash
+#MISE dir="{{cwd}}"
+#MISE depends=["preset:python"]
+#USAGE arg "<version>"
+
+mise use python@$usage_version
+mise use pdm@latest
+mise config set hooks.postinstall "pdm sync"
+```
+
+Then in any directory, you can run `mise preset:pdm 3.10` to scaffold a new project with `python` and `pdm`:
+
+```shell
+cd my-project
+mise preset:pdm 3.10
+# [preset:python] $ ~/.config/mise/tasks/preset/python
+# mise WARN  No untrusted config files found.
+# mise ~/my-project/mise.toml tools: pre-commit@4.0.1
+# [preset:pdm] $ ~/.config/mise/tasks/preset/pdm 3.10
+# mise WARN  No untrusted config files found.
+# mise ~/my-project/mise.toml tools: python@3.10.15
+# mise ~/my-project/mise.toml tools: pdm@2.21.0
+# mise creating venv with uv at: ~/my-project/.venv
+# Using CPython 3.10.15 interpreter at: /Users/simon/.local/share/mise/installs/python/3.10.15/bin/python
+# Creating virtual environment at: .venv
+# Activate with: source .venv/bin/activate.fish
+
+~/my-project via 🐍 v3.10.15 (.venv)
+# we are in the virtual environment ^
+```
+
+Here is the generated `mise.toml` file:
+
+```toml [mise.toml]
+[tools]
+pdm = "latest"
+pre-commit = "latest"
+python = "3.10"
+
+[hooks]
+postinstall = "pdm sync"
+
+[env]
+[env._]
+[env._.python]
+[env._.python.venv]
+path = ".venv"
+create = true
+
+[tasks.lint]
+run = "pre-commit run -a"
+```

docs/mise-cookbook/python.md

@@ -0,0 +1,46 @@
+# Mise + Python Cookbook
+
+Here are some tips on managing Python projects with mise.
+
+## A Python Project with virtualenv
+
+Here is an example python project with a `requirements.txt` file.
+
+```toml [mise.toml]
+min_version = "2024.9.5"
+
+[env]
+# Use the project name derived from the current directory
+PROJECT_NAME = "{{ config_root | basename }}"
+
+# Automatic virtualenv activation
+_.python.venv = { path = ".venv", create = true }
+
+[tools]
+python = "{{ get_env(name='PYTHON_VERSION', default='3.11') }}"
+ruff = "latest"
+
+[tasks.install]
+description = "Install dependencies"
+alias = "i"
+run = "uv pip install -r requirements.txt"
+
+[tasks.run]
+description = "Run the application"
+run = "python app.py"
+
+[tasks.test]
+description = "Run tests"
+run = "pytest tests/"
+
+[tasks.lint]
+description = "Lint the code"
+run = "ruff src/"
+
+[tasks.info]
+description = "Print project information"
+run = '''
+echo "Project: $PROJECT_NAME"
+echo "Virtual Environment: $VIRTUAL_ENV"
+'''
+```