Cheat notes · Module 08 · Golden paths and docs

Docs next to the code with TechDocs

A five-minute review for when you have done this module and want it back in your head. Open the full module for the steps and the lab, or the full text to print.

The idea

Docs live in the repo, are built by MkDocs and shown on the entity page next to the owner and the API, so they change in the same pull request as the code. One annotation links the entity to its docs.

Remember

backstage.io/techdocs-ref: dir:. points at the folder with mkdocs.yml, relative to catalog-info.yaml. MkDocs then reads docs_dir (default docs).
Builder and generator: the backend fetches the repo and runs MkDocs. runIn: docker uses the spotify/techdocs image; runIn: local needs MkDocs installed.
Publisher: where built sites are stored: the local disk here, a bucket (S3, GCS, Azure) in production.
Recommended in production: build in each repo's CI with techdocs-cli generate and publish to a bucket; the portal only reads.
Templates give docs from day one: the skeleton includes mkdocs.yml and docs/.

Pitfalls

"Fixing" the annotation to dir:./docs because the Markdown is there: The path '/input/docs' isn't an existing directory. It must point at the mkdocs.yml folder.
Making docs builds the portal's problem: a broken build should fail the pull request in the repo's CI.

Commands

`curl -s -H "Authorization: Bearer $PORTAL_API_TOKEN" -N localhost:7007/api/techdocs/sync/default/component/checkout`	Rebuild one entity's docs now and stream the log
`docker images spotify/techdocs`	The image that built them

Test yourself

Answer in your head first, then open the answer.

What does backstage.io/techdocs-ref: dir:. point at?

The folder with mkdocs.yml, relative to catalog-info.yaml.

Why does the portal need Docker for docs on your laptop?

With runIn: docker the generator runs MkDocs in the spotify/techdocs image.

What is the recommended production setup?

Build in each repo's CI, publish to a bucket; the portal only reads.

Where module 08 leaves you: Both services have a TechDocs tab with their docs. You know where the build runs and what the annotation does.