Setting up TechDocs for Workflows

Learn how to add documentation for Workflows using TechDocs.

The purpose of this how-to guide is to walk you through how to add the required configuration and some default markdown files to your new Workflows. You can use the react-ssr-workflow as a reference when walking through the steps.

Prerequisites:

• An existing software template including a workflow.yaml together with a skeleton folder including at least a catalog-info.yaml.

1. Update your component's entity description by adding the following lines to the catalog-info.yaml in your skeleton folder.

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.

1. Create a mkdocs.yml file in the root of your skeleton folder with the following content:

site_name: ${{values.component_id}}
site_description: ${{values.description}}

nav:
  - Introduction: index.md

plugins:
  - techdocs-core

1. Create a /docs folder in the skeleton folder with at least a index.md file in it.

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

# ${{ values.component_id }} <a href="#dollar-valuescomponentid" id="dollar-valuescomponentid"></a>

${{ values.description }}

## Getting started <a href="#getting-started" id="getting-started"></a>

Start writing your documentation by adding more markdown (.md) files to this
folder (/docs) or replace the content in this file.

The values of site_name, component_id and site_description depends on how you have configured your Workflow definition YAML.

Done! You now have support for TechDocs in your own Workflows!