Repository navigation
Backstage: catalog-info.yaml + TechDocs mirroring doc/ - #95
Merged
Merged
Conversation
…ation Annotate the repo for the freundcloud Backstage instance and publish the existing GitHub docs as Backstage TechDocs without duplicating them. - catalog-info.yaml — Component (service/production), owner olafkfreund, domain public, techdocs-ref dir:., project-slug, tags, repo link. Validated against the live catalog (isValid: true). - mkdocs.yml — techdocs-core, docs_dir: doc so TechDocs renders the existing doc/ guides directly (single source of truth; README links unchanged). - doc/index.md — TechDocs landing page mirroring the README overview. - .github/workflows/techdocs.yml — on doc/catalog/mkdocs changes: validate catalog-info.yaml (RoadieHQ entity validator) and strict-build TechDocs with techdocs-core, so the GitHub docs and Backstage portal never drift. - README — note the Backstage TechDocs/catalog integration. Verified: mkdocs build --strict renders all 5 pages + 11 images clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
olafkfreund
force-pushed
the
backstage-techdocs
branch
from
June 5, 2026 19:13
449b514 to
41f6e14
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
The freundcloud Backstage bot had already done a minimal onboard of this repo (merged #93/#94 earlier today): a terse
catalog-info.yaml, and amkdocs.ymlpointing at a single seededdocs/index.md. None of the real documentation (doc/onboarding.md,doc/starting.md,doc/development.md) was in TechDocs.This PR (rebased on top of that onboard) makes TechDocs actually mirror the GitHub docs and adds a sync guarantee.
Changes
catalog-info.yaml— enriched: real description,tags, and a repolink; keeps the bot's provenance note. Validated against the live catalog via the Backstage MCP (isValid: true).mkdocs.yml— switcheddocs_dir: docs→docs_dir: docso TechDocs renders the existingdoc/guides directly (single source of truth; README'sdoc/links stay valid), with an explicitnavandscripts/excluded.docs/index.md; the canonical landing page is nowdoc/index.md(mirrors the README overview)..github/workflows/techdocs.yml— on changes todoc/**,mkdocs.yml, orcatalog-info.yaml: validates the entity (RoadieHQ entity validator) and strict-builds TechDocs with the realtechdocs-coreplugin. The GitHub docs and the Backstage portal can't drift.README.md— note the Backstage TechDocs/catalog integration.How the sync works
Backstage's GitHub org provider auto-discovers this repo and rebuilds TechDocs on-demand from
mainon every view — no push step needed. This workflow guarantees that whatever lands onmainis always valid Backstage format.Verification
mkdocs build --strict(withtechdocs-core) renders all 5 pages + 11 images; no "not in nav"/broken-link warnings.TechDocs & Catalogjob green (entity validated, strict build, artifact uploaded).🤖 Generated with Claude Code