Skip to main content

Enable documentation for your Component

Now that you have added your Software Components in the Catalog, we need to add the documentation. By default, the Docs tab in your catalog does not include documentation for a new software component. However, you can 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.

To add documentation:

  1. Create a docs directory next to where you have catalog-info.yaml.
  2. Inside the docs directory, create a index.md file with the following contents.
# 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. Now add an mkdocs.yaml next to where you have the catalog-info.yaml, mkdocs.yml file is a sibling of catalog-info.yaml

Here's the content for mkdocs.yaml:

site_name: 'Example Documentation'
repo_url: https://github.com/your_org/your_repo
edit_uri: url to your index.md

nav:
  - Home: index.md

plugins:
  - techdocs-core

  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 mkdocs.yml file is a sibling of catalog-info.yaml (meaning, it is in the same directory)
  • And that all the source content of the documentation would be available if one were to download the directory containing those two files (as well as all subdirectories).

The directory tree of the entity would look something like this:

├── catalog-info.yaml
├── mkdocs.yml
└── docs
    └── index.md

If, for example, you wanted to keep a lean root directory, you could place your mkdocs.yml file in a subdirectory and update the backstage.io/techdocs-ref annotation value accordingly, e.g. to dir:./sub-folder:

├── catalog-info.yaml
└── sub-folder
    ├── mkdocs.yml
    └── docs
        └── index.md
warning

Please note dir:../. does not work in the above use case due to security reasons.

  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.