TechDocs in Backstage

What is TechDocs?

TechDocs is Spotify’s in-house solution for documentation-as-code, seamlessly integrated into Backstage. It aligns with the “docs like code” philosophy, where documentation is authored and managed alongside the source code of the underlying software. You write documentation in Markdown files, and with minimal configuration, you can create a beautifully formatted documentation site in Backstage. TechDocs utilizes mkdocs under the hood to build project documentation.

Incorporating TechDocs into Backstage

The first step is to add the TechDocs plugin to your Backstage application. You will need to include the @backstage/plugin-techdocs and @backstage/plugin-techdocs-backend packages and make some modifications to the configuration files. Detailed steps are provided in the Backstage documentation.

Setting the configuration

In the app-config.yaml file, there are primarily three flags that we configure. For a comprehensive reference, you can find more information here.

  
techdocs:
  builder: 'local'
  publisher:
    type: 'local'
  generator:
    runIn: local

builder:: The value can be either local or external. This flag determines whether the documents should be built locally or not. If set to external, Backstage assumes that the documents will be generated as part of the CI/CD process and readily available in some cloud storage. In that case techdocs-backend will only fetch the docs and will NOT attempt to generate and publish them.
publisher:: The values can be local or googleGcs or awsS3 or azureBlobStorage. Depending on the value used the Backstage will determine whee to store the generated files.
generator:: This can be set to either docker or local. It determines how to run the generator, specifically whether to run it using a Docker container or locally. When you run Backstage in Docker, this must be set to ‘local’ to avoid a Docker-in-Docker situation.

While the local setup will work to get the setup running quickly, it is not recommended for production usage. If you have a distributed Backstage setup, with multiple pods running in Kubernetes, using local configuration may lead to page duplication or data loss. On the other hand, if you are using cloud storage, you may need to restrict access to the storage and only allow techdocs-backend to fetch files to ensure security.

Enable documentation for an entity

Create an mkdocs.yml file in the root of your repository with the following content:

  
site_name: 'example-docs'

nav:
  - Home: index.md

plugins:
  - techdocs-core

Update your component’s catalog-info.yaml in the root of its repository:

  
metadata:
  annotations:
    backstage.io/techdocs-ref: dir:.

If the techdocs source content is in a remote location, you can specify a URL location reference. You can also provide a path to a non-root directory which contains the mkdocs.yml and /docs directory.

Create a /docs folder in the root of your repository with at least an index.md file in it.

The folder /docs can be renamed to something else if you would like. See mkdocs documentation

Commit and merge the changes and you should be able to see the docs in Backstage.

Previewing your documentation

Using tech-docs cli you can preview the documentation from your CLI. To do this:

Install techdocs-cli npm install -g @techdocs/cli
Navigate to the directory where your mkdocs.yaml is located.
Run npx @techdocs/cli serve

The command starts two local servers - An mkdocs preview server on port 8000 and a Backstage app server on port 3000. Head over to localhost:8000 if you want to browse thorough the mkdocs view.