> ## Documentation Index
> Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TechDocs

> Publish docs-like-code documentation from Markdown files alongside your source code using TechDocs in Portal, with search and catalog integration.

## Overview

### What is it?

TechDocs is Spotify’s homegrown docs-like-code solution built directly into Portal. Engineers write their documentation in Markdown files which live together with their code - and with little configuration get a nice-looking doc site in Portal.

Today, it is one of the core products in Spotify’s developer experience offering with 5,000+ documentation sites and around 10,000 average daily hits. Read more about TechDocs in its
[announcement blog post](https://backstage.io/blog/2020/09/08/announcing-tech-docs).
🎉

### Features

* Deploy TechDocs no matter how your software environment is set up.
* Discover your Service's technical documentation from the Service's page in Portal Catalog.
* Create documentation-only sites for any purpose by just writing Markdown.
* Search for and find docs.

## Enabling TechDocs in Portal

You can enable TechDocs in Portal by following the steps outlined in the [Setup Guide](../getting-started). You also have the option to enable or disable TechDocs at any time through **Plugins**.

## Creating and publishing your docs

Create an `mkdocs.yml` file in the root of your repository with the following
content:

```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
site_name: 'example-docs'

nav:
  - Home: index.md
```

Update your component's entity description by adding the following lines to its
`catalog-info.yaml` in the root of its repository:

```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
metadata:
  annotations:
    backstage.io/techdocs-ref: dir:.
```

The
`backstage.io/techdocs-ref` annotation
is used by TechDocs to download the documentation source files for generating an
entity's TechDocs site.

Create a `/docs` folder in the root of your repository with at least an
`index.md` file in it. *(If you add more markdown files, make sure to update the
nav in the mkdocs.yml file to get a proper navigation for your documentation.)*

> Note - Although `docs` is a popular directory name for storing documentation,
> it can be renamed to something else and can be configured by `mkdocs.yml`. See
> [https://www.mkdocs.org/user-guide/configuration/#docs\_dir](https://www.mkdocs.org/user-guide/configuration/#docs_dir)

The `docs/index.md` can for example have the following content:

```md theme={"theme":{"light":"github-light","dark":"dracula"}}
# example docs

This is a basic example of documentation.
```

Commit your changes, open a pull request and merge. You will now get your
updated documentation in Portal!

## Configuring TechDocs

You can view all the available configuration options for TechDocs in **Plugins**.