Create standalone documentation in TechDocs

You can create standalone documentation in TechDocs for content that is not tied to a specific codebase, such as onboarding guides, architecture overviews, or team runbooks.

Before you begin

  • An administrator has configured the TechDocs plugin.
  • You have the catalog.entity.create and catalog.location.create permissions.

Procedure

  1. Create a directory for your documentation project with the following structure:
    my-documentation/
      catalog-info.yaml
      mkdocs.yml
      docs/
        index.md
  2. Create a catalog-info.yaml file that defines a documentation entity:
    apiVersion: backstage.io/v1alpha1
    kind: Component
    metadata:
      name: my-documentation
      description: Onboarding guide for new team members
      annotations:
        backstage.io/techdocs-ref: dir:.
    spec:
      type: documentation
      lifecycle: production
      owner: group:default/my-team
  3. Create an mkdocs.yml file to configure the documentation site:
    site_name: My Documentation
    nav:
      - Home: index.md
    plugins:
      - techdocs-core
  4. Create a docs/ directory containing at least an index.md file with your documentation content in Markdown.
  5. Commit and push the directory to a Git repository.
  6. In your Developer Hub instance, register the documentation entity:
    1. Click Catalog > Self-service > Register Existing Component.
    2. In the Select URL box, enter the URL to the catalog-info.yaml file in your repository.
    3. Click Analyze, then click Finish.

Results

  1. In the Developer Hub navigation menu, click Docs.
  2. Verify that your standalone documentation appears in the table on the Documentation page. Note

    The documentation might not appear immediately. Developer Hub refreshes catalog entities periodically, which can take up to 45 minutes. To trigger a refresh sooner, navigate to the entity in the software catalog and click the refresh button on the Overview tab.