How to Publish Docs as Code With TechDocs

TechDocs builds a service Markdown docs from an mkdocs.yml and shows them in the portal next to the service.

Add an mkdocs.yml and a docs/ folder, annotate the catalog entity with backstage.io/techdocs-ref, and build docs in CI. Documentation lives with the code and surfaces in the portal.

Steps

Add mkdocs.yml and docs/index.md to the repo.
Add the backstage.io/techdocs-ref: dir:. annotation to catalog-info.yaml.
Build and publish docs in CI (or let the portal build them).
Verify the Docs tab appears on the entity page.

mkdocs config

mkdocs.yml

site_name: payments-api
nav:
  - Home: index.md
  - Runbook: runbook.md
plugins:
  - techdocs-core

CI publish

.github/workflows/techdocs.yml

- run: pip install mkdocs-techdocs-core
- run: npx @techdocs/cli generate --no-docker
- run: npx @techdocs/cli publish --publisher-type awsS3 --entity default/component/payments-api

Gotchas

The techdocs-ref annotation must match where the docs live (dir:. for in-repo).
Use the techdocs-core plugin; a plain mkdocs build will miss the required rendering.