Backstage TechDocs "techdocs generate" failed in CI

techdocs-cli generate runs mkdocs build. A failure means mkdocs itself errored: a missing plugin, a config it does not understand, or a docs directory that does not exist. The mkdocs error above the summary is the real cause.

What this error means

The generate step fails with "Failed to generate docs" and an mkdocs error such as "Config value: 'plugins'. ... plugin not installed" or "The docs_dir does not exist".

backstage

INFO - Building documentation...
ERROR - Config value: 'plugins'. Error: The "techdocs-core" plugin is not installed
Aborted with a configuration error!
Error: Failed to generate docs

Common causes

A referenced mkdocs plugin is not installed

mkdocs.yml lists a plugin (techdocs-core) that mkdocs-techdocs-core provides, but it is not installed in the environment.

A bad docs_dir or mkdocs config

The docs directory does not exist or the config has an invalid value, so mkdocs aborts before building.

How to fix it

Install the plugin and read the mkdocs error

Install mkdocs-techdocs-core so the techdocs-core plugin resolves.
Read the first mkdocs ERROR line for the real cause.
Fix the config or docs_dir it names.

Terminal

python3 -m pip install mkdocs-techdocs-core
npx @techdocs/cli generate --source-dir . --output-dir ./site

Point docs_dir at real content

Ensure mkdocs.yml docs_dir matches the directory that holds your Markdown.

mkdocs.yml

docs_dir: docs
plugins:
  - techdocs-core

How to prevent it

Install mkdocs-techdocs-core before generating.
Keep docs_dir pointed at the actual docs directory.
Generate TechDocs in CI so config errors fail the pull request.