TechDocs

TechDocs in Venue.sh publishes technical documentation from your catalog Components. Each TechDocs site is built from Markdown in a connected Git repository and rendered in the Venue.sh portal under Tech Docs, where developers can browse, search, and read documentation alongside catalog metadata, API specs, and the Assistant.

Venue.sh follows Backstage TechDocs conventions: you author content with MkDocs, and Venue.sh reads the published documentation bundle for each entity.

Key Capabilities

• Catalog-linked docs - Attach documentation to Components so service owners maintain docs next to their code.
• MkDocs navigation - Define a left-side navigation tree in mkdocs.yml for each repository.
• Organization-wide discovery - Browse all TechDocs-enabled entities from Tech Docs in the sidebar.
• Assistant integration - The Assistant can search and read TechDocs when answering questions about your services.

Enabling TechDocs on a Component

TechDocs is enabled through the entity annotation on the Component that owns the documentation. By default, Venue.sh will look for mkdocs.yml at the repository root. The documentation directory is docs/.

Prerequisites

• The repository is imported into your organization's catalog with a valid source location.
• Your role includes catalog entity Read permission to view TechDocs.
• For full MkDocs syntax, plugins, and theming, see the MkDocs documentation and Backstage TechDocs authoring guide.

Repository Layout

A minimal TechDocs repository contains:

my-service/
├── mkdocs.yml
└── docs/
    └── index.md

A typical mkdocs.yml declares the site name, documentation directory, and navigation:

site_name: My Service
plugins:
  - techdocs-core
nav:
  - Home: index.md
  - Guides:
      - Overview: guides/overview.md
      - Local Setup: guides/local-setup.md

Use the nav section to control which pages appear in the TechDocs sidebar and in what order. Pages not listed in nav may still be reachable through links, but they will not appear as top-level navigation entries.

Authoring Navigation

When you add or rename Markdown files, keep mkdocs.yml in sync with the files that actually exist in the repository.

Use one landing page per folder. MkDocs and Backstage treat these paths as the same route for a folder:

• my-topic/index.md
• my-topic/README.md

Both resolve to the same URL segment (my-topic). If you list both in nav as separate pages, Venue.sh keeps the first entry and skips the duplicate. You may see fewer sidebar items than lines in nav, even though both files exist in the repository.

Prefer distinct filenames for distinct pages. If you need a separate "Local setup" page under a topic that already has an overview, use a dedicated file such as local-setup.md instead of a second README.md in the same folder:

nav:
  - Development Insights:
      - Overview: development-insights/index.md
      - Local Setup: development-insights/local-setup.md

Match nav paths to real files. If you rename README.md to local-setup.md, update the corresponding nav entry. A path that points to a missing file produces a navigation item that does not load content correctly.

Use unique heading text within a page. Venue.sh builds an on-page table of contents from Markdown headings. Headings that differ only by capitalization or punctuation can produce the same anchor id (e.g., ### Email/password sign-in and ### Email/Password Sign-In). Venue.sh assigns unique ids when duplicates are detected, but clear, distinct headings make the table of contents easier to read and avoid confusing anchor links.

Viewing TechDocs in Venue.sh

1. Open Tech Docs from the left-side navigation to see all TechDocs-enabled entities in your organization.
2. Click an entity to open its documentation site with the navigation tree on the left and page content in the main panel.
3. Use the in-page table of contents to jump to headings on long pages.
4. From the global shortcut, search for Tech Docs or a specific entity name to navigate quickly.

Troubleshooting

Situation	What to do
A nav entry is missing in the sidebar	Check for duplicate routes. Two entries that resolve to the same path (e.g., index.md and README.md in the same folder) cause the later entry to be skipped. Remove the duplicate or rename one file to a distinct path.
A sidebar link opens the wrong page or no content	Verify the path in mkdocs.yml matches the file in docs/. Update nav after renames or moves.
Table of contents links behave unexpectedly	Review headings on the page for near-duplicate titles. Rename headings so each section has a distinct title.
Documentation changes are not visible yet	Wait for the TechDocs build for that repository to finish after your merge, then refresh the page in Venue.sh.
Cannot access Tech Docs	Your role may not include catalog entity Read permission. Contact your Venue administrator.

See Also

• Importing Repos - Bring repositories into the catalog so TechDocs annotations take effect.
• Developer Portal - Overview of catalog, templates, and repository workflows.
• Assistant - Ask questions about TechDocs and other catalog content in natural language.
• Navigating Venue.sh - Use the global shortcut and sidebar to reach Tech Docs quickly.