Backstage TechDocs "mkdocs: command not found" in CI

The local TechDocs generator shells out to mkdocs to build documentation. On a runner without python3 and the mkdocs-techdocs-core package, the generator cannot find mkdocs and fails.

What this error means

TechDocs generation fails with "mkdocs: command not found" or an error that the mkdocs executable could not be spawned.

backstage

Error: Failed to generate docs from /docs into /output;
caused by Error: spawn mkdocs ENOENT
/bin/sh: 1: mkdocs: not found

Common causes

mkdocs and its plugin are not installed

Local TechDocs generation needs python3 with mkdocs and mkdocs-techdocs-core, which a Node-only runner does not have.

No python3 on the runner

Without a Python interpreter, pip cannot install mkdocs and the generator cannot run it.

How to fix it

Install python3, mkdocs, and mkdocs-techdocs-core

Ensure python3 and pip are available.
Install mkdocs-techdocs-core with pip.
Re-run TechDocs generation.

Terminal

python3 -m pip install mkdocs-techdocs-core

Use the techdocs-cli Docker generator

Set the generator to run the techdocs container so mkdocs is provided by the image instead of the runner.

app-config.yaml

techdocs:
  generator:
    runIn: docker

How to prevent it

Install python3 and mkdocs-techdocs-core in the TechDocs runner.
Or run the generator in Docker so mkdocs ships with the image.
Pin the mkdocs-techdocs-core version for reproducible builds.