backstage-techdocs

Backstage TechDocs

Wire the docs-like-code pipeline correctly, and tell apart the four places it breaks: the entity annotation, the mkdocs source, the generator, and the publisher.

Preconditions

• Release line from backstage.json; TechDocs packages resolved with yarn why @backstage/plugin-techdocs-backend and yarn why @techdocs/cli.
• Backend generation: backend.add(import('@backstage/plugin-techdocs-backend')) in packages/backend/src/index.ts is the new backend system; a createRouter in packages/backend/src/plugins/techdocs.ts is legacy — migrate it (backstage-plugin-migrate) before adding a build-strategy module.
• Frontend generation: NFS (default since v1.49) registers TechDocs and its addon modules as features from /alpha exports; legacy has TechDocsIndexPage/TechDocsReaderPage inside <FlatRoutes> and an EntityTechdocsContent tab in EntityPage.tsx.
• The effective merged config, not app-config.yaml alone: yarn backstage-cli config:print --lax. Production almost always overrides techdocs.* in app-config.production.yaml.
• Whether the runtime has Docker (for runIn: docker) or Python with mkdocs-techdocs-core (for runIn: local).

Procedure

1. Read the triple before anything else. techdocs.builder, techdocs.generator.runIn, techdocs.publisher.type determine which failures are even possible.
   • builder: 'local' — the backend generates and publishes on demand when a user opens the docs tab. Out-of-the-box default.
   • builder: 'external' — the backend only reads pre-built docs from storage. It will never build, no matter what is wrong with the source. This is the recommended production architecture.
   • publisher.type: 'local' | 'awsS3' | 'googleGcs' | 'azureBlobStorage'. local writes to techdocs.publisher.local.publishDirectory, defaulting to a static dir at the backend root — pod-local, lost on restart, and invisible to sibling replicas.
2. Check the entity side second. In catalog-info.yaml, metadata.annotations['backstage.io/techdocs-ref'] is the only thing that points TechDocs at source:
   • dir:. — docs live beside catalog-info.yaml; dir:./sub-folder for a subdirectory.
   • url:https://github.com/org/repo/tree/<branch> (GitLab url:https://host/org/repo, Bitbucket .../src/<branch>, Azure .../_git/<repo>). Suffix a subdirectory path with / so relative paths resolve.
   • An entity with no techdocs-ref gets no docs tab content. A monorepo child that should show a parent's docs uses backstage.io/techdocs-entity: <kind>:<namespace>/<name> (plus backstage.io/techdocs-entity-path to deep-link), not a duplicate techdocs-ref.
   • A url: target must be reachable by an integrations.* credential in the backend's config, not just yours (backstage-repo-discovery).
3. Check the source layout third. At the root of whatever techdocs-ref resolves to: mkdocs.yml (or mkdocs.yaml) plus a docs/ directory containing at minimum index.md. Minimum config: