Demo TechDocs Basics

In this lesson we’ll walk through Backstage TechDocs — the built-in documentation system that lets each catalog component expose and render documentation directly inside Backstage. You’ll learn the minimal configuration and repository layout required to enable TechDocs for a component, how Backstage builds and serves the docs, and recommendations for production deployments.

A screenshot of the Backstage catalog showing the "shopping-cart" service page with an About panel, tabs (Overview, CI/CD, API, Dependencies, Docs), and a warning about missing related entities. On the right is a relations graph linking the shopping-cart to auth-api and auth-service.

What is TechDocs?

TechDocs is a Backstage plugin (backend + frontend) that generates and displays static documentation for catalog entities.
It typically uses MkDocs (often with the mkdocs-material theme) to render Markdown into a static site that Backstage can serve or publish to object storage.

Overview — high-level steps

Step	Goal	Where to configure
1	Ensure TechDocs backend plugin is enabled	Backstage backend bootstrap file
2	Configure builder/generator/publisher behavior	`app-config.yaml`
3	Add MkDocs config and documentation files to the repository	`mkdocs.yml` and `docs/`
4	Annotate the catalog entity with TechDocs location	`catalog-info.yaml`
5	Import the component into Backstage and view TechDocs	Backstage catalog UI

Backstage backend: enable the TechDocs backend plugin Open your backend bootstrap (where backend plugins are wired) and confirm TechDocs backend is added. Example:

// backend/index.js
import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();

backend.add(import('@backstage/plugin-app-backend'));
backend.add(import('@backstage/plugin-proxy-backend'));
backend.add(import('@backstage/plugin-scaffolder-backend'));
backend.add(import('@backstage/plugin-scaffolder-backend-module-github'));
backend.add(import('@backstage/plugin-techdocs-backend'));

// auth plugin
backend.add(import('@backstage/plugin-auth-backend'));
backend.add(import('@backstage/plugin-auth-backend-module-guest-provider'));

// catalog plugin
backend.add(import('@backstage/plugin-catalog-backend'));

Repository integrations (example) Backstage typically stores Git host integrations in app-config.yaml. Use environment variables for secrets — never hardcode tokens.

integrations:
  github:
    - host: github.com
      # Use an environment variable for the token, do not hardcode secrets.
      token: ${GITHUB_TOKEN}

TechDocs configuration in app-config.yaml Configure the TechDocs builder, generator, and publisher. For experimentation you can use local options; for production prefer CI-built artifacts and cloud storage.

# Reference: https://backstage.io/docs/features/techdocs/
techdocs:
  builder: 'local'         # Alternatives: 'external'
  generator:
    runIn: 'docker'       # Alternatives: 'local'
  publisher:
    type: 'local'         # Alternatives: 'googleGcs' or 'awsS3'

TechDocs options at a glance

Option	Typical values	Notes
`builder`	`local`, `external`	`local` runs the build inside the backend; `external` delegates to an external builder (recommended for CI workflows).
`generator.runIn`	`docker`, `local`	`docker` uses the TechDocs Docker image; `local` requires installing the TechDocs binary on the host.
`publisher.type`	`local`, `googleGcs`, `awsS3`	Use `googleGcs` or `awsS3` for production (object storage) to serve static builds at scale.

Project repository layout Place MkDocs config and Markdown documentation alongside your code so documentation is versioned with the project.

File / Folder	Purpose
`package.json`	Project dependencies / build scripts (if applicable)
`catalog-info.yaml`	Backstage entity definition and annotations
`mkdocs.yml`	MkDocs site configuration (nav, theme, plugins)
`docs/`	Markdown files to be rendered by MkDocs (e.g., `index.md`)

Example package.json (trimmed):

{
  "name": "recommendation-service",
  "version": "1.0.0",
  "main": "index.js",
  "type": "module",
  "dependencies": {
    "express": "^4.21.2"
  }
}

.gitignore (example):

node_modules/

MkDocs configuration Place mkdocs.yml (or mkdocs.yaml) at repo root. TechDocs commonly uses mkdocs-material.

site_name: 'example-docs'

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - API Reference: api.md

theme:
  name: material

plugins:
  - techdocs-core

If you store your docs in a non-default directory, set docs_dir:

# Example to use a directory named "documentation" instead of "docs"
# docs_dir: documentation

Documentation content example Create Markdown under docs/. Example docs/index.md:

## Getting Started

Welcome to the docs for the recommendation service.

### Examples

- Step 1
- Step 2

Catalog entity annotation Point Backstage to the repository location containing mkdocs.yml and the docs/ folder by adding the TechDocs annotation to catalog-info.yaml. Quote the annotation value to avoid YAML parsing issues.

apiVersion: backstage.io/v1beta1
kind: Component
metadata:
  name: recommendation-service
  description: Recommendation service api
  annotations:
    'backstage.io/techdocs-ref': 'dir:.'
  tags:
    - javascript
  links:
    - url: https://google.com
      title: Admin Dashboard
      icon: dashboard
      type: admin-dashboard
spec:
  type: service

'backstage.io/techdocs-ref': 'dir:.' tells Backstage to read mkdocs.yml from the repository root and use the default docs/ folder.
To point to a subfolder, update the dir: path (for example 'dir:docs/subfolder') or set docs_dir in mkdocs.yml.

Build and publish behavior How the docs get built and served depends on your techdocs config:

Backstage fetches the repository referenced by the catalog entity.
The generator runs MkDocs (inside Docker or locally) to produce a static site.
The publisher stores the generated site (local storage or cloud object storage) and the frontend serves it when you click “View TechDocs”.

Example developer workflow:

Push repository changes (include catalog-info.yaml, mkdocs.yml, and docs/) to your Git host.
Import or refresh the component in the Backstage catalog.
Open the component page and click “View TechDocs” (or the Docs tab). Backstage will generate and display the documentation according to your configured builder/generator/publisher.

A screenshot of a Backstage documentation page titled "example-docs" showing a large heading "This is the documentation for my app!" with example h1–h6 headings. A dark left sidebar displays navigation items like Home, APIs, Docs, and Create.

Production considerations

For production, Backstage recommends generating TechDocs artifacts in CI and publishing the generated static site to cloud storage (Google Cloud Storage or AWS S3) instead of using the local publisher. This improves scalability, reduces on-demand build latency, and allows serving docs from highly-available object storage.

Best practices and tips

Never commit secrets or tokens to app-config.yaml. Use environment variables or secret management.
Prefer CI-based builds and cloud publishers (googleGcs or awsS3) for production workloads.
Use mkdocs-material for a polished default theme that integrates well with TechDocs.
If using generator runIn: docker, ensure your backend host can run Docker, or switch to CI-based generation for environments where Docker isn’t available.

Summary

TechDocs integrates MkDocs with Backstage to render component docs inside the catalog.
Enable the TechDocs backend plugin and configure builder/generator/publisher in app-config.yaml.
Add mkdocs.yml and a docs/ folder to your repository and annotate the entity with 'backstage.io/techdocs-ref'.
For production, build docs in CI and publish to cloud storage for scalability and faster page loads.

Links and references

Backstage TechDocs docs: https://backstage.io/docs/features/techdocs/
MkDocs: https://www.mkdocs.org/
mkdocs-material theme: https://squidfunk.github.io/mkdocs-material/
Google Cloud Storage: https://cloud.google.com/storage
AWS S3: https://aws.amazon.com/s3/

Introduction

Backstage Basics

Catalog

Templates

TechDocs & Search

Customization & Plugins

Production Backstage

Demo TechDocs Basics

Watch Video

Practice Lab