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.
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
- Publish - upload the generated files to storage
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 can be created as a standalone project and our local setup already has a template that we can play with.
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.
site_name: 'gitops-flux-helm-docs' nav: - Home: index.md plugins: - techdocs-core
Next we create an
index.md inside a
# Example This is a basic example of documentation.
We'll now edit
catalog-info.yaml and add the following annotation under
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).