Backstage TechDocs

Originally published on mccricardo.com.

Documentation, that thing everyone complains about but few want to create or maintain. However, good documentation is priceless, and the less painful it is to create, maintain and access the more valuable it becomes.

TechDocs is Backstages’s docs-as-code built-in solution and this basically means we can write our documentation in files that live together with our code. It's based on MkDocs although there are plans to support other types of sources. TechDocs enables documentation to be found from a service page in Backstage's Catalog and be built with good old Markdown.

How TechDocs works

Backstage generates documentation in a three-step process:

• Prepare - fetch the source files from the source code and pass them to the generator
• Generate - run the build phase (through a container or mkdocs cli)
• Publish - upload the generated files to storage

_{(image source: Backstage official documentation)}

As shown above, for a production deployment, this process should be decoupled from the Backstage deployment. Backstage would only be responsible for fetching and presenting the generated documentation.

Documentation template

Documentation can be created as a standalone project and our local setup already has a template that we can play with.

Add TechDocs to our setup

For our demo, we'll go with a simpler setup (as shown below) and let Backstage do all the heavy lifting. To make things even easier will need Docker.

_{(image source: Backstage official documentation)}

We well reuse our repository from the Flux CD post. We'll add a few files and edit another. We'll start by creating a mkdocs.yaml file.

site_name: 'gitops-flux-helm-docs'

nav:
  - Home: index.md

plugins:
  - techdocs-core

Next we create an index.md inside a docs folder.

# Example

This is a basic example of documentation.

We'll now edit catalog-info.yaml and add the following annotation under metadata.

metadata:
  annotations:
    backstage.io/techdocs-ref: url:https://gitlab.com/mccricardo-blog-demos/gitops-flux-helm

From the repository side, we're done. We've added the necessary configuration that will allow Backstage to find docs/index.md and generate the documentation. We now turn our attention to Backstage. On app-config.yaml we'll add the following code.

techdocs:
  builder: 'local'
  generators:
    techdocs: 'docker'
  publisher:
    type: 'local'

And that's it. We'll let Backstage do all the heavy lifting (with a bit of help of Docker).