Automated Documentation Sites with Backstage TechDocs

Overview

Backstage TechDocs enables engineering teams to maintain documentation alongside their code in the same repository. Instead of managing separate documentation platforms, TechDocs automatically converts Markdown into a fully browsable documentation site.

TechDocs

TechDocs is Backstage’s built-in documentation solution, following a “Docs-as-Code” model. All Markdown files live inside your service’s Git repository (either in the repo root or a docs/ folder). When a user opens the Documentation tab for an entity, Backstage fetches and renders those docs.

Although TechDocs uses MkDocs behind the scenes to generate a static HTML site, Backstage adds additional layers such as preparing content, storing generated files, and rendering them safely inside the UI.

TechDocs Pipeline

TechDocs works through three major stages:

1. Prepare Stage

This step retrieves the raw Markdown files (.md) and configuration (mkdocs.yml) from the Git repository.

• TechDocs identifies documentation source using the annotation:

backstage.io/techdocs-ref: dir:.

• It fetches the directory from GitHub/GitLab/Bitbucket/local Git.
• Only documentation source files are collected.

2. Generate Stage

In this stage, TechDocs converts Markdown into a static HTML website.

Internally, this uses:

• MkDocs
• mkdocs-techdocs-core plugin (adds TechDocs integrations)
• A generator environment (local binary or Docker)

The output of this step:

• html
• json
• json
• /assets folder containing CSS, JS, images

3. Publish Stage

The generated HTML is uploaded to a storage backend, allowing Backstage to serve it.

Supported publishers:

• Local filesystem
• Amazon S3
• Google Cloud Storage
• Azure Blob Storage
• Once published, Backstage serves the HTML directly from the storage backend, it doesn’t rebuild the docs unless necessary.

Two Ways to Build Documentation

1. Local Builder (Backstage Builds Everything)

Backstage performs:

• Prepare → fetch Markdown from repo
• Generate → run MkDocs locally or in Docker
• Publish → store output on disk or a bucket

Example configuration:

Notes:

• builder: local = Backstage handles prepare + generate + publish
• runIn: docker ensures builds use a consistent environment
• Backstage must have write access to the publishDirectory

This approach works for small installations or demos, but becomes slow for large orgs.

2. External / CI-Based Builder (Recommended for Production)

In this model, Backstage does not generate docs.
Instead, your CI/CD pipeline performs the Generate + Publish stages.

Workflow:

1. Developer pushes changes to Markdown
2. CI pipeline detects doc changes
3. CI installs TechDocs CLI + MkDocs
4. CI builds the HTML site
5. CI publishes to S3/GCS/Blob Storage
6. Backstage only reads the published HTML

Backstage Configuration:

When to use CI-based builds:

• Multiple teams
• Large documentation sites
• When the Backstage backend must stay lightweight
• For consistent builds across environments

Repository Requirements

Every service needs two files for TechDocs to work:

1. yml

Defines:

• site name
• navigation
• plugins
• theme

Example:

2. catalog-info.yaml

Registers the service in Backstage.

Example:

techdocs-ref tells Backstage where Markdown lives.

Storage

Documentation files are stored like:

Backstage leverages:

• publisher caching
• CDN caching
• browser caching – to deliver fast documentation loading times.

Security in TechDocs

TechDocs implements several security layers:

• Sanitizes HTML to remove dangerous scripts
• Renders documentation in an isolated iframe
• Uses IAM roles and restricted storage permissions
• Prevents documentation authors from breaking the UI

Extending TechDocs

You can customize multiple parts:

• MkDocs plugins (Material theme extensions)
• CI pipelines with custom Docker images
• Custom publishers for on‑prem storage
• Custom Backstage layouts or homepage sections

What Happens When You Update Your Documentation?

1. A change is made to .md files
2. CI rebuilds docs (or Backstage does if using local builder)
3. The new HTML overwrites the old version in the bucket
4. Backstage instantly serves updated docs on next page load

No restarts, redeploys, or manual steps are needed.

Conclusion

TechDocs simplifies the production, storage, and viewing of documentation in Backstage.

Drop a query if you have any questions regarding TechDocs and we will get back to you quickly.

About CloudThat