Skip to main content

TechDocs

Overview​

What is it?​

TechDocs is Spotify’s homegrown docs-like-code solution built directly into Portal. Engineers write their documentation in Markdown files which live together with their code - and with little configuration get a nice-looking doc site in Portal.

Today, it is one of the core products in Spotify’s developer experience offering with 5,000+ documentation sites and around 10,000 average daily hits. Read more about TechDocs in its announcement blog post. 🎉

Features​

  • Deploy TechDocs no matter how your software environment is set up.
  • Discover your Service's technical documentation from the Service's page in Portal Catalog.
  • Create documentation-only sites for any purpose by just writing Markdown.
  • Search for and find docs.

Enabling TechDocs in Portal​

You can enable TechDocs in Portal by following the steps outlined in the Setup Guide. You also have the option to enable or disable TechDocs at any time through the Config Manager.

Creating and publishing your docs​

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

site_name: 'example-docs'

nav:
  - Home: index.md

Update your component's entity description by adding the following lines to its catalog-info.yaml in the root of its repository:

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

The backstage.io/techdocs-ref annotation is used by TechDocs to download the documentation source files for generating an entity's TechDocs site.

Create a /docs folder in the root of your repository with at least an index.md file in it. (If you add more markdown files, make sure to update the nav in the mkdocs.yml file to get a proper navigation for your documentation.)

Note - Although docs is a popular directory name for storing documentation, it can be renamed to something else and can be configured by mkdocs.yml. See https://www.mkdocs.org/user-guide/configuration/#docs_dir

The docs/index.md can for example have the following content:

# example docs

This is a basic example of documentation.

Commit your changes, open a pull request and merge. You will now get your updated documentation in Portal!

Configuring TechDocs​

You can view all the available configuration options for TechDocs in the Config Manager in Portal.