Skip to content

Previewing Backstage TechDocs Locally

A practical guide for rendering and sharing the Asurion Command Center documentation without waiting for a real Backstage instance.

Adapted from the canonical guide in CHIP (sdlc-agent-swarms/docs/guides/backstage-techdocs-local-preview.md). The toolchain and commands are intentionally identical so the same muscle memory works across both repos.

Context

Backstage is the open-source developer portal framework (Spotify → CNCF, Apache 2.0). When the Asurion Command Center docs land in a real Backstage instance, the source of truth will be:

  • catalog-info.yaml — Backstage Software Catalog descriptors (Domain / System / Component / API)
  • mkdocs.yml — TechDocs navigation and config (uses techdocs-core plugin)
  • docs/**/*.md — actual markdown content
  • redocly.yaml + docs/api/openapi.yaml — API entity contract for Backstage's /api-docs plugin

You can render the exact same content locally, with the same Backstage chrome, without running a Backstage instance. Useful for:

  • Sharing screenshots / a static HTML bundle / a PDF with stakeholders
  • Validating doc changes before a real Backstage instance is wired up
  • Spinning up TechDocs for review on a laptop with zero Python / Backstage setup

Spotify ships a standalone CLI that renders TechDocs using the same pipeline as a real Backstage instance, with full Backstage UI chrome. Perfect for screenshots and stakeholder previews.

It uses the mkdocs.yml + docs/ structure already in this repo.

Quick start (zero local Python setup — uses Docker under the hood)

1
2
3
4
cd /Users/praveengottala/Documents/personal-projects/2026-hackathon

make docs-serve
# equivalent to: npx --yes @techdocs/cli serve

Opens http://localhost:3000 with the full Backstage TechDocs UI. First run takes ~60 s while npm fetches @techdocs/cli and Docker pulls spotify/techdocs:latest; subsequent runs are instant.

Stop with Ctrl-C.

Static HTML (shareable as a zip)

1
2
3
make docs-validate
# wraps: npx --yes @techdocs/cli generate --source-dir . --output-dir ./site
#        + redocly lint docs/api/openapi.yaml

Produces a static site/ folder you can zip and email, or upload to any web host / S3 bucket / SharePoint. Recipients just open index.html in any browser.

Without Docker (if you have Python locally)

1
2
pip install mkdocs-techdocs-core
npx --yes @techdocs/cli serve --no-docker

Reference: https://github.com/backstage/backstage/tree/master/packages/techdocs-cli

Option 2 — Plain MkDocs (fastest, but no Backstage chrome)

If you only need the content and don't care about Backstage's look:

1
2
3
pip install mkdocs mkdocs-techdocs-core
mkdocs serve   # http://localhost:8000
mkdocs build   # outputs ./site/

Faster to start, but renders with the default MkDocs theme, not Backstage's. Fine for content validation.

Option 3 — PDF export

TechDocs / Backstage don't ship a built-in PDF export, but MkDocs plugins fill the gap.

Plugin-based (one PDF per build)

Add to mkdocs.yml:

1
2
3
4
5
6
plugins:
  - techdocs-core
  - with-pdf:
      output_path: pdf/command-center-docs.pdf
      cover_title: "Asurion Command Center"
      cover_subtitle: "TechDocs"

Install and build:

1
2
3
pip install mkdocs-with-pdf
mkdocs build
# → ./site/pdf/command-center-docs.pdf

Alternatives

  • mkdocs-print-site-plugin — combines all pages into one HTML page; use the browser's Print → Save as PDF. Cleaner output than with-pdf for some content.
  • Browser print — run make docs-serve, navigate each page, Print → Save as PDF. Zero plugin setup, but tedious for many pages.

⚠️ Don't commit the PDF plugin to the shared mkdocs.yml if techdocs-core is the only plugin supported by the org's publish workflow. Keep it on a local branch or in a separate mkdocs.pdf.yml you only use ad-hoc.

Option 4 — Run real Backstage locally (overkill for this use case)

1
npx @backstage/create-app@latest

Spins up a full Backstage app you can run with yarn dev. You'd then register catalog-info.yaml and point TechDocs at this repo.

Heavy setup — auth config, Postgres for catalog persistence, plugin install, etc. Only worth it if you also want to demo the Software Catalog + Scaffolder, not just render docs. CHIP keeps a full Backstage app under sdlc-agent-swarms/backstage/ for this purpose; it's not in scope for the hackathon prototype.

Goal Command Output
Take Backstage-styled screenshots make docs-serve Live preview at http://localhost:3000
Send a self-contained HTML bundle make docs-validate Zip ./site/ and share via email / Slack / SharePoint
Validate docs + OpenAPI before merge make docs-validate Exits 0 on success; warnings visible inline
Generate a PDF Add mkdocs-with-pdf ./site/pdf/command-center-docs.pdf
Quick content review (no Backstage UI) mkdocs serve Live preview at http://localhost:8000

Prerequisites cheat sheet

Tool Required for Install
Node.js (20.x or later) @techdocs/cli (the make docs-* targets) already required by frontend/
Docker @techdocs/cli default mode Docker Desktop / colima / rancher
Python 3.x + pip --no-docker mode, plain mkdocs, PDF brew install python
mkdocs-techdocs-core Backstage-faithful rendering without Docker pip install mkdocs-techdocs-core
mkdocs-with-pdf PDF export pip install mkdocs-with-pdf

How the Makefile targets map to the commands above

```startLine:endLine:Makefile docs-serve: npx --yes @techdocs/cli serve

docs-validate: npx --yes @techdocs/cli generate --source-dir . --output-dir ./site docker run --rm \ -v $(PWD):/spec \ -w /spec \ redocly/cli:latest \ lint --config /spec/redocly.yaml docs/api/openapi.yaml ```

This is the same pattern CHIP uses (sdlc-agent-swarms/Makefile + the linked guide). The @techdocs/cli pulls spotify/techdocs:latest under the hood — that image has mkdocs-techdocs-core and friends preinstalled, so any plugin declared in mkdocs.yml Just Works.

Registering the catalog entries in real Backstage

When a real Backstage instance comes online, registration is a one-time manual step:

  1. In the Backstage UI: Create → Register Existing Component
  2. Point it at the URL of catalog-info.yaml on the default branch: https://github.com/<org>/2026-hackathon/blob/main/catalog-info.yaml
  3. Backstage will ingest all four entities: Domain: command-center, System: asurion-command-center, Component: command-center-api, API: command-center-api + the external API: databricks-sql-warehouse.
  4. TechDocs picks up the backstage.io/techdocs-ref: dir:. annotation on the Component and renders this site automatically. The TechDocs publish pipeline is normally orchestrated by a CI workflow in the org's Backstage automation repo (CHIP uses asurion-private/pse-github-actions/.github/workflows/backstageDocPush.yaml; the equivalent target for this repo is TBD).