fix: bootstrap mkdocs for TechDocs generation

Dockerfile

@@ -99,6 +99,11 @@ RUN curl -fsSL https://mise.run | sh
 COPY mise.toml ./
 RUN mise trust && mise install
 
+# TechDocs generates docs by spawning the mkdocs CLI (techdocs.generator.runIn: 'local').
+# User install puts it in /root/.local/bin, which is first on PATH above.
+RUN mise exec python -- python -m pip install --no-cache-dir --user mkdocs mkdocs-techdocs-core \
+    && mkdocs --version
+
 # Enable Corepack; Yarn version is selected via package.json "packageManager"
 ENV COREPACK_ROOT=/root/.corepack
 ENV PATH=$COREPACK_ROOT:$PATH

docs/development.md

@@ -55,7 +55,11 @@ npm install -g @backstage/cli
 
 ### TechDocs Local Development
 
-Ensure you have the following installed:
+TechDocs generates docs by spawning the `mkdocs` CLI (`techdocs.generator.runIn: 'local'`),
+so `mkdocs` must be on your `PATH`. `mise run install` bootstraps it into
+`~/.local/share/backstage-techdocs-venv` and links it into `~/.local/bin` when missing.
+
+To install it manually:
 
 ```bash
 pip install mkdocs mkdocs-techdocs-core
@@ -64,9 +68,12 @@ pip install mkdocs mkdocs-techdocs-core
 Then run the following command to start the local development server:
 
 ```bash
-make dev
+mise run dev
 ```
 
+If doc builds fail with `spawn mkdocs ENOENT`, the backend cannot find `mkdocs`.
+Ensure `~/.local/bin` is on your `PATH` and restart the dev server.
+
 To quickly test the TechDocs site, run the following command in the respective component directory that contains the `mkdocs.yml` file:
 
 ```bash

scripts/install

@@ -6,4 +6,19 @@ if [ "${CI:-false}" = "true" ]; then
   yarn install --immutable
 else
   yarn install
+fi
+
+# TechDocs generates docs by spawning the mkdocs CLI (techdocs.generator.runIn: 'local').
+# Install it into a dedicated venv and link it into ~/.local/bin when missing.
+if [ "${CI:-false}" != "true" ] && ! command -v mkdocs >/dev/null 2>&1; then
+  techdocs_venv="${XDG_DATA_HOME:-$HOME/.local/share}/backstage-techdocs-venv"
+  echo "mkdocs not found; installing mkdocs + techdocs-core into ${techdocs_venv}"
+  python3 -m venv "${techdocs_venv}"
+  "${techdocs_venv}/bin/pip" install --quiet mkdocs mkdocs-techdocs-core
+  mkdir -p "${HOME}/.local/bin"
+  ln -sf "${techdocs_venv}/bin/mkdocs" "${HOME}/.local/bin/mkdocs"
+  case ":${PATH}:" in
+    *":${HOME}/.local/bin:"*) ;;
+    *) echo "Add ${HOME}/.local/bin to PATH so the backend can spawn mkdocs." ;;
+  esac
 fi