Skip to main content

Enable documentation for your Component

Introduction​

Now that you have added your software components to the catalog, enabled plugins and created a scorecard it's time to include documentation. By default, the Docs tab in the catalog does not display documentation for new components. This tutorial will show you how to quickly publish Markdown documentation to the Docs tab.

info

Docs in Harness IDP is powered by TechDocs Backstage Plugin and which currently is using MkDocs to generate the documentation from source, so the files have to be in Markdown format with a mkdocs.yml file present in the path provided.

There are two ways to add documentation for your component in Backstage TechDocs:

  1. By adding the documentation in the same directory as the software component's source code. (Docs Available in the Root of Source Folder)
  2. By adding the documentation in a separate docs directory, distinct from the software component's source code directory. (Docs Available in Some Other Location)

Docs Available in the Root of Source Folder​

To add documentation:

  1. Create a docs directory next to where you have catalog-info.yaml.

The directory tree must look something like this:

├── catalog-info.yaml
└── docs
    └── index.md
  1. Inside the docs directory, create an index.md file with the following content.
# Welcome!

This is a basic example of documentation. It is intended to showcase some of the
features that TechDocs provides out of the box.

## Basic Markdown

Headings:

# h1

## h2

### h3

#### h4

##### h5

###### h6

Here is a bulleted list:

- Item one
- Item two
- Item Three

Check out the [Markdown Guide](https://www.markdownguide.org/) to learn more about how to
simply create documentation.

You can also learn more about how to configure and set up this documentation in Backstage,
[read the TechDocs Overview](https://backstage.io/docs/features/techdocs/).

## Table example

While this documentation isn't comprehensive, in the future it should cover the following
topics outlined in this example table:

| Topic   | Description                                                  |
| ------- | ------------------------------------------------------------ |
| Topic 1 | An introductory topic to help you learn about the component. |
| Topic 2 | A more detailed topic that explains more information.        |
| Topic 3 | A final topic that provides conclusions and lessons learned. |

## Learn more about MkDocs

TechDocs uses MkDocs as the static site generator. Visit https://www.mkdocs.org for more information about MkDocs.

  1. Edit the catalog-info.yaml and add the TechDocs annotation.

  2. In the metadata.annotations field, add backstage.io/techdocs-ref: dir:..

When you seedir:., you can translate it to mean:

  • That the documentation source code lives in the same location as the catalog-info.yaml file.
  • That, in particular, the docs folder is a sibling of catalog-info.yaml (meaning, it is in the same directory)
  1. Select the refresh button on the catalog component page.

  1. Navigate to the Docs tab to review the documentation, which should become available shortly.