TechDocs Basics

In this guide, you’ll learn how to power your documentation alongside your code using TechDocs in Backstage. Backstage is an open platform for building developer portals, giving your team a single place to discover, manage, and maintain software and its documentation.

Each service or component in Backstage features a Documentation tab that renders Markdown files stored alongside the code.

When you click Documentation, TechDocs fetches and displays your site in one unified view.

How TechDocs Works Under the Hood

TechDocs relies on MkDocs to transform Markdown into a static HTML site. The three core stages are:

1. Prepare – Retrieve Markdown files from your Git repository.
2. Generate – Run MkDocs to convert those .md files into HTML.
3. Publish – Store the generated site in a location Backstage can serve (local disk, AWS S3, GCS, etc.).

TechDocs Pipeline Stages

When a user views the docs, Backstage serves the pre-published HTML directly.

Local Builder Configuration

By default, Backstage can handle all TechDocs stages using the local builder. Configure this in your app-config.yaml:

techdocs:
  builder: local
  generator:
    runIn: docker
    dockerImage: spotify/techdocs
  publisher:
    type: local
    local:
      publishDirectory: /var/backstage/techdocs

• builder: local enables Backstage to run prepare, generate, and publish phases.
• generator options:
  • runIn: docker uses the specified dockerImage.
  • runIn: local executes MkDocs via a binary on the host.
• publisher defines where to store static HTML (here, a local directory).

Offloading Builds to CI/CD

For larger teams or heavy documentation sites, you can offload generate and publish steps to your CI/CD pipeline. This approach uses the external builder in Backstage:

1. A commit to docs/** or mkdocs.yml triggers your CI/CD workflow.
2. CI/CD installs the TechDocs CLI and MkDocs dependencies.
3. Run techdocs-cli generate then techdocs-cli publish to an S3 bucket.
4. Configure Backstage to use the external builder and fetch published HTML from that bucket.

Example: GitHub Actions Workflow

name: Publish TechDocs Site
on:
  push:
    branches:
      - main
    paths:
      - 'docs/**'
      - 'mkdocs.yml'

jobs:
  publish-techdocs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.9'
      - name: Install TechDocs CLI
        run: sudo npm install -g @techdocs/cli
      - name: Install MkDocs
        run: pip install mkdocs-techdocs-core==1.*
      - name: Generate site
        run: techdocs-cli generate --no-docker --verbose
      - name: Publish site to S3
        run: |
          techdocs-cli publish \
            --publisher-type awsS3 \
            --storage-name $TECHDOCS_S3_BUCKET_NAME \
            --entity $ENTITY_NAMESPACE/$ENTITY_KIND/$ENTITY_NAME

Update app-config.yaml in Backstage:

techdocs:
  builder: external
  publisher:
    type: awsS3
    awsS3:
      bucketName: $TECHDOCS_S3_BUCKET_NAME
      region: us-east-1

Repository Setup

Every service repository needs two configuration files:

1. mkdocs.yml at the project root:

   site_name: 'example-docs'
   nav:
     - Home: index.md
   plugins:
     - techdocs-core
   

2. catalog-info.yaml with a TechDocs reference:

   apiVersion: backstage.io/v1beta1
   kind: Component
   metadata:
     name: shopping-cart
     description: shopping cart API
     annotations:
       backstage.io/techdocs-ref: dir:.
     tags:
       - javascript
   spec:
     type: service
     lifecycle: production
     owner: shopping-team
   

The annotation backstage.io/techdocs-ref: dir:. tells TechDocs where to find your Markdown files (adjust dir: if using a docs/ subfolder).

Once configured, Backstage will automatically surface your up-to-date documentation alongside the service catalog.

Links and References

• Backstage Documentation
• MkDocs Official Site
• TechDocs CLI
• AWS S3 Storage
• Google Cloud Storage