Backstage TechDocs
Tags: backstage
Published: 2021-04-05 21:44:34

Originally published on [mccricardo.com](https://mccricardo.com/backstage-techdocs/).

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](https://www.mkdocs.org/) although there are [plans](https://backstage.io/docs/features/techdocs/architecture#future-work) 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

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/5pm4fty1hf5f2j2e3sip.png)
<sub>(image source: Backstage official documentation)</sub>

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.

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/oskvew6taukxxstfa4bv.png)

## 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](https://www.docker.com/).

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/212guvxag1j1fz39sesr.png)
<sub>(image source: Backstage official documentation)</sub>

We well reuse our [repository](https://gitlab.com/mccricardo-blog-demos/gitops-flux-helm) from the [Flux CD](https://mccricardo.com/gitops-fluxcd/) post. We'll add a few files and edit another. We'll start by creating a `mkdocs.yaml` file.

```yaml
site_name: 'gitops-flux-helm-docs'

nav:
  - Home: index.md

plugins:
  - techdocs-core

```

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

# Example

This is a basic example of documentation.
```

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

```yaml
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.

```yaml
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).

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2se4qayfoibqtyb4l46q.png)

![Alt Text](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9d7m434aq0xwk4kq4hg0.png)