> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/internal-developer-portal/use-idp/software-catalog/integrate-tools/techdocs/enable-docs.md).
# Setup TechDocs for Catalog
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](https://backstage.io/docs/features/techdocs/) 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
{% hint style="info" %}
**REQUIREMENTS**
Your documentation files must be in **Markdown format** with an `mkdocs.yml` file present in the specified path.
{% endhint %}
***
### 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
{% tabs %}
{% tab title="Co-located with Source Code" %}
### 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:
```sh
├── catalog-info.yaml
└── docs
└── index.md
```
#### Step 2: Create documentation content
Inside the `docs` directory, create an `index.md` file with your documentation content. Here is a basic example:
```
# 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 is not 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.
```
#### Step 3: Add TechDocs annotation
Edit your `catalog-info.yaml` and add the TechDocs annotation in the `metadata.annotations` field:
```yaml
metadata:
annotations:
backstage.io/techdocs-ref: dir:.
```
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)
{% endtab %}
{% tab title="Separate Location" %}
### 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/~/`
{% hint style="info" %}
**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).
{% endhint %}
**Examples for different scenarios**
**Monorepo (docs in subdirectory):**
When your documentation is in a subdirectory like `docs/` within your repository:
```yaml
metadata:
annotations:
backstage.io/techdocs-ref: url:https://app.harness.io/ng/account/account_id/module/code/orgs/org_id/projects/project_id/repos/repo_name/files/master/~/docs
```
**Non-monorepo (docs at root):**
When your documentation (`mkdocs.yml` and `docs/` folder) is at the repository root:
```yaml
metadata:
annotations:
backstage.io/techdocs-ref: url:https://app.harness.io/ng/account/account_id/module/code/orgs/org_id/projects/project_id/repos/repo_name/files/main/~/
```
**Non-default branch:**
When your documentation is on a branch other than the default branch:
```yaml
metadata:
annotations:
backstage.io/techdocs-ref: url:https://app.harness.io/ng/account/account_id/module/code/orgs/org_id/projects/project_id/repos/repo_name/files//~/
```
{% hint style="info" %}
**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
{% endhint %}
**Third-Party Git Providers:**
* **GitHub**: `url:https://githubhost.com/org/repo/tree/`
* **GitLab**: `url:https://gitlabhost.com/org/repo/tree/`
* **Azure**: `url:https://azurehost.com/organization/project/_git/repository`
* **Bitbucket**: `url:https://bitbuckethost.com/project/repo/src/`. If you are using Bitbucket, go to [Prerequisites for Bitbucket connector](/internal-developer-portal/use-idp/scorecards/create-scorecards/data-sources.md#prerequisites-for-bitbucket-connector) to configure the required connector settings.
{% hint style="info" %}
**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`
{% endhint %}
#### Add TechDocs annotation
Edit your `catalog-info.yaml` and add the TechDocs annotation with the URL reference:
```yaml
metadata:
annotations:
backstage.io/techdocs-ref: url:https://github.com/backstage/backstage/tree/master/plugins/techdocs-backend/examples/documented-component
```
{% endtab %}
{% endtabs %}
***