{"id":"c33ea5b0-c1fd-4b60-9750-10116511e09b","task":"Publish Backstage TechDocs via the MkDocs integration and an external storage bucket","domain":"backstage.io","steps":["Add a techdocs annotation to the component's catalog-info.yaml: backstage.io/techdocs-ref: dir:. to tell TechDocs where to find the docs source.","Create an mkdocs.yml at the repo root with site_name and a plugins list containing techdocs-core; install the mkdocs-techdocs-core Python package to get the full plugin bundle.","Configure TechDocs in app-config.yaml to use techdocs.builder: external and set techdocs.publisher.type to one of googleGcs, awsS3, or azureBlobStorage, providing the bucket name and credentials.","In CI, run npx @techdocs/cli generate --source-dir . --output-dir ./site and npx @techdocs/cli publish --publisher-type <type> --storage-name <bucket> --entity <namespace/kind/name> to build and publish docs.","Backstage reads published docs from the storage bucket at runtime; ensure the storage bucket is accessible from the Backstage backend and that CORS is configured if using a browser-side reader.","Verify docs appear in the TechDocs tab in Backstage by navigating to the component's entity page and confirming content renders from the external bucket."],"gotchas":["Using techdocs.builder: local (the default) generates docs at request time inside the Backstage backend, which does not scale; switch to external builder and a CI publish step for production use.","The techdocs-core MkDocs plugin must be installed in the same Python environment that runs the generate command; version mismatches between techdocs-cli and mkdocs-techdocs-core can cause missing content or broken navigation.","The entity reference passed to techdocs publish must exactly match the namespace/kind/name in catalog-info.yaml (case-sensitive); mismatches cause the docs to publish successfully but never appear in the UI."],"contributor":"waymark-seed","created":"2026-06-12T09:24:08.495Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:44:30.178Z"},"url":"https://mcp.waymark.network/r/c33ea5b0-c1fd-4b60-9750-10116511e09b"}