TechDocs: documentation next to the code
Documentation in a wiki rots, because nobody updates a wiki in the same merge request as the code. TechDocs is Backstage's "docs like code" system: the docs are Markdown files in the service's repository, built with MkDocs into a static site and shown on the entity's Docs tab. A change to the runbook goes through the same review as the change to the code it describes.
Three things make a repository's docs appear in Backstage:
orders/
├── catalog-info.yaml annotations: backstage.io/techdocs-ref: dir:.
├── mkdocs.yml site_name, nav, plugins: [techdocs-core]
└── docs/
├── index.md the home page
└── runbook.md
site_name: orders
site_description: How the orders service works and how to run it
nav:
- Home: index.md
- Runbook: runbook.md
plugins:
- techdocs-core
backstage.io/techdocs-ref: dir:.on the entity says "the docs source is in this directory" (relative to thecatalog-info.yaml). Without the annotation the entity has no Docs tab.mkdocs.ymlconfigures MkDocs. Thetechdocs-coreplugin (themkdocs-techdocs-corePython package) bundles the theme and the Markdown extensions Backstage expects; the generator adds it if it is missing.docs/index.mdis the first page. Without it the site has no home page (--legacyCopyReadmeMdToIndexMdmakes the generator copy aREADME.mdthere instead - a crutch for old repositories).
Building the site
The @techdocs/cli builds exactly what Backstage would build. By default it runs MkDocs inside the spotify/techdocs container (v1.2.8 for CLI 1.13.0), so the only local requirement is Docker:
$ npx @techdocs/cli generate
info: Using engine: mkdocs (binary: mkdocs)
info: Using source dir /home/learner/xp
info: Will output generated files in /home/learner/xp/site
info: Generating documentation...
info: Successfully generated docs from /home/learner/xp into /home/learner/xp/site using techdocs-container
info: Computed generated site content hash: 9a0a26bac120e6b5284f815a74f410d3702a1cf624a3d642e90a223a2e4ce9ab
info: Done!
$ cat mkdocs.yml
site_name: orders
nav:
- Home: index.md
plugins:
- techdocs-core
Look at mkdocs.yml afterwards: the generator wrote the techdocs-core plugin into your file (it patches the source directory, not a copy). Commit that line yourself so the file in git is the file that builds; --omitTechdocsCoreMkdocsPlugin turns the patching off.
With --legacyCopyReadmeMdToIndexMd and no docs/index.md, the generator warns and copies the first README it finds into docs/index.md - also in your source directory:
$ npx @techdocs/cli generate --legacyCopyReadmeMdToIndexMd
...
warn: docs/index.md not found.
warn: docs/README.md not found.
warn: docs/readme.md not found.
info: Successfully generated docs from /home/learner/xp into /home/learner/xp/site using techdocs-container
...
Commit a real docs/index.md instead.
--verbose (-v) also prints MkDocs' own log, which is where the real reason for a failed build is (the non-verbose error is only Docker container returned a non-zero exit code (1)):
$ npx @techdocs/cli generate --verbose
...
verbose: INFO - Cleaning site directory
verbose: INFO - Building documentation to directory: /output
verbose: INFO - Documentation built in 0.54 seconds
...
The output in ./site/ is a static website plus techdocs_metadata.json (site name, description, the list of files and an etag, a hash of the generated content Backstage uses to decide whether its copy is stale).
--no-docker runs a locally installed mkdocs (pip install mkdocs-techdocs-core) instead.
Basic and recommended setups
Where does Backstage build the docs?
| Setup | Who builds | Where the site is stored |
|---|---|---|
| Basic | the Backstage backend, the first time someone opens the Docs tab (and again when the source changed) | local disk of the backend |
| Recommended | CI, on every merge: techdocs-cli generate, then techdocs-cli publish | object storage: S3, GCS, Azure Blob |
The recommended setup keeps MkDocs (and Docker) out of the Backstage pods and makes the docs available the moment CI finishes. In app-config.yaml: techdocs.builder: external and techdocs.publisher.type: awsS3, with a bucket - which you can, of course, create with a Crossplane StorageBucket.
The Kubernetes plugin
The Kubernetes tab of an entity shows what is running for it: Deployments, Pods, their status and recent errors, across clusters. The backend plugin asks each configured cluster for objects that carry a label matching the entity's annotation:
# catalog-info.yaml
metadata:
annotations:
backstage.io/kubernetes-id: orders
# the Deployment (and its pod template)
metadata:
labels:
backstage.io/kubernetes-id: orders
spec:
template:
metadata:
labels:
backstage.io/kubernetes-id: orders
Label the pod template too: Pods are found by their own labels, not their owner's. backstage.io/kubernetes-namespace limits the lookup to a namespace; backstage.io/kubernetes-label-selector replaces the id with any selector (app=orders,tier=backend).
The backend needs to reach the clusters: kubernetes.clusterLocatorMethods in app-config.yaml lists them (a fixed config list, or discovered from the catalog or a cloud API), each with an auth provider (serviceAccount, aws, google...). The ServiceAccount needs read access (get/list/watch) to the kinds the plugin shows. A missing label is the most common "Kubernetes tab is empty" ticket.
In an interview: TechDocs builds Markdown from the service's repository with MkDocs (techdocs-core plugin) into a static site shown on the entity; the entity points at it with backstage.io/techdocs-ref; in the recommended setup CI runs techdocs-cli generate and publish to object storage. The Kubernetes plugin finds workloads by the backstage.io/kubernetes-id label, on the Deployment and its pod template.