Backstage TechDocs "mkdocs: command not found" in CI

By Daniel Zoghalchali·Latchkey

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.

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

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

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.

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.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation