Ctrlk
Sign UpGet a DemoContact Us
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Setup TechDocs for Catalog

Learn how to enable TechDocs to display Markdown documentation on the Docs tab of your catalog entities.

This document will take you through detailed steps to enable and publish Markdown documentation for your Software Catalog using TechDocs.

What is TechDocs?

TechDocs enables a docs-as-code approach where documentation lives alongside your source code in Git. Write docs in Markdown, commit them alongside your source code, and publish automatically. Your team can discover and access documentation instantly through the Docs tab in the Catalog; no more outdated wikis or scattered knowledge.

TechDocs is powered by the TechDocs Backstage Plugin and uses MkDocs as the static site generator to transform your Markdown files into beautiful, searchable documentation.

Key benefits

  • Docs-as-code: Version control your documentation alongside source code

  • Automatic publishing: Documentation updates automatically when you commit changes

  • Centralized discovery: All docs accessible through the Software Catalog

  • Markdown-based: Simple, developer-friendly format

  • Always up-to-date: Documentation evolves with your codebase

Setup TechDocs for catalog

To enable TechDocs for your component, you will need to:

  1. Enable the TechDocs plugin for your entity in your catalog entity's YAML file

  2. Create documentation in Markdown format with an mkdocs.yml file

  3. Add the TechDocs annotation to specify where your documentation is located

REQUIREMENTS

Your documentation files must be in Markdown format with an mkdocs.yml file present in the specified path.

Documentation location options

You can add documentation for your component in two ways:

  1. Co-located with source code: Documentation lives in the same repository as your component's source code

  2. Separate location: Documentation is stored in a different repository or directory

Option 1: Co-located with source code

When your documentation lives in the same repository as your component's source code:

Step 1: Create documentation structure

Create a docs directory next to your catalog-info.yaml file:

Step 2: Create documentation content

Inside the docs directory, create an index.md file with your documentation content. Here is a basic example:

Step 3: Add TechDocs annotation

Edit your catalog-info.yaml and add the TechDocs annotation in the metadata.annotations field:

The dir:. annotation indicates that:

  • Documentation source code lives in the same location as the catalog-info.yaml file

  • The docs folder is a sibling of catalog-info.yaml (in the same directory)

Option 2: Separate location

When your TechDocs source content is managed in a location separate from your catalog-info.yaml, specify a URL location reference using the url: prefix instead of dir:. Ensure the specified path contains the mkdocs.yml file.

Supported Git providers

Harness Code Repository:

  • Account scope: url:https://app.harness.io/ng/account/account_id/module/code/repos/repo_name/~/

  • Organization scope: url:https://app.harness.io/ng/account/account_id/module/code/orgs/org_id/repos/repo_name/~/

  • Project scope: url:https://app.harness.io/ng/account/account_id/module/code/orgs/org_id/projects/project_id/repos/repo_name/~/

URL FORMATTING

If you are copying the URL directly from the browser and adding it in techdocs-ref, ensure to reformat the URL and add ~ at the end of the path (before any file paths).

Examples for different scenarios

Monorepo (docs in subdirectory):

When your documentation is in a subdirectory like docs/ within your repository:

Non-monorepo (docs at root):

When your documentation (mkdocs.yml and docs/ folder) is at the repository root:

Non-default branch:

When your documentation is on a branch other than the default branch:

KEY POINTS

  • The ~ character is required and acts as a separator between the repository path and file path

  • For subdirectories, add the path after ~/ (e.g., ~/docs)

  • For root-level docs, end with ~/

  • For non-default branches, specify the branch name in the URL path

Third-Party Git Providers:

  • GitHub: url:https://githubhost.com/org/repo/tree/<branch_name>

  • GitLab: url:https://gitlabhost.com/org/repo/tree/<branch_name>

  • Azure: url:https://azurehost.com/organization/project/_git/repository

  • Bitbucket: url:https://bitbuckethost.com/project/repo/src/<branch_name>. If you are using Bitbucket, go to Prerequisites for Bitbucket connector to configure the required connector settings.

SUBDIRECTORY SUPPORT

You can provide a path to a non-root directory inside the repository that contains the mkdocs.yml file and docs/ directory.

Example: url:https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend/examples/documented-component

Add TechDocs annotation

Edit your catalog-info.yaml and add the TechDocs annotation with the URL reference:

PreviousTechDocs
NextTechDocs Plugins

Last updated

Was this helpful?