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).
Top comments (0)