4. Documentation by TechDocs

A very integrated way to document the applications and services of a company is provided by the TechDocs Core Feature of Backstage. It is included by default in a Backstage application.

TechDocs brings documentation directly into Backstage, making it easy for developers to find and read documentation alongside their services. The TechDocs plugin can be seen as a wrapper for MkDocs .

An other huge benefit is that the documentation lives, as Markdown files, beside the source code. This makes it “normal” for developers to update the docs together with the code changes.

Task 4.1: Setup TechDocs Plugin

TechDocs is already included by default, but let’s configure it properly and add documentation to a component.

Step 1: Configure TechDocs for local development

Make sure that your app-config.yaml is configured for TechDocs:

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

Step 2: Create documentation

In your my-sample-service directory (or any catalog component), create a docs/ folder:

mkdir -p examples/my-sample-service/docs

Add some content by creating the docs/index.md file:

# My Sample Service


## Overview

This is a sample microservice that demonstrates Backstage catalog integration.


## Architecture

The service is built with Node.js and provides a REST API for user management.


## Getting Started


### Prerequisites

* Node.js 22+
* PostgreSQL 14+


### Installation

```bash
npm install
npm start
```


## API Documentation

See the [API Reference](./api.md) for detailed endpoint documentation.

Step 3: Create MkDocs configuration

The mkdocs.yml files are used to configure the documentation for this component. Here you also define the structure / navigation of the documentation.

Create a mkdocs.yml file in the root of your service (side-by-side with catalog-info.yaml):

site_name: 'My Sample Service'
site_description: 'Documentation for My Sample Service'

nav:
  - Home: index.md

plugins:
  - techdocs-core

Step 4: Enable TechDocs in catalog

Update your catalog-info.yaml to enable TechDocs.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-sample-service
  description: A sample microservice for the Backstage catalog
  annotations:
    github.com/project-slug: your-org/my-sample-service
    backstage.io/techdocs-ref: dir:.
  tags:
    - nodejs
    - microservice
spec:
  type: service
  lifecycle: production
  owner: team-a
  system: my-system

Now your documentation will be available directly in Backstage in the “Docs” menu or on the “Techdocs” tab of your component!

Summary

In this chapter, you:

• ✅ Set up TechDocs for component documentation
• ✅ Documented one service

TechDocs integrate the developers documentation easily into Backstage. With the docs-as-code approach it is also convenient to the developers to document.

Congratulations! You now have the knowledge to document your apps in an easy way.