paulasilvatech Backstage TechDocs
Conventions
- Keep
mkdocs.ymlnavigation aligned with tracked source content; do not add entries for nonexistent root paths. - Use
backstage.io/techdocs-refwith a resolvable source location and a catalog owner responsible for publication. - Keep local and external builder or publisher modes consistent with the matching Backstage configuration overlay.
- Preserve portable relative links, stable headings, accessible image text, and fenced Mermaid syntax supported by the configured MkDocs extensions.
- Keep publication credentials in CI or workload identity, never in MkDocs, catalog, or app configuration.
- Keep examples portable and independent of this checkout's absolute paths.
Verification
- MkDocs strict build or the repository documentation check resolves navigation and links.
- TechDocs annotations resolve from the entity's source location.
- Publication configuration exposes no storage key or service credential.
Do / Do Not
| Do | Do not |
|---|---|
| Keep documentation portable and validate navigation, links, and entity annotations. | Depend on absolute checkout paths or unverified publication settings. |
| Use external credential providers for publication. | Commit storage keys or service credentials. |
Checklist Before Opening a PR
- The change matches this instruction's
applyToscope. - Strict documentation build or the repository documentation check passes.
- Entity annotations resolve from the source location.
- Publication configuration contains no literal credential.
- No unrelated edits or unresolved placeholders remain.