Creating and publishing your docs

This section will guide you through how to:

• Create a basic documentation setup
  • Use any software template
  • Enable documentation for an already existing entity
  • Create a standalone documentation
• Writing and previewing your documentation

Prerequisites

• A working Backstage instance with TechDocs installed (see TechDocs getting started)

Create a basic documentation setup

TechDocs uses the following artifacts to generate the documentation for a component:

• mkdocs.yml - A file created at the root of your component repository that provides the name of your documentation site, as well as the navigation for the documentation.
• docs - A folder at the root of your component repository that holds your documentation markdown files. You can call this folder anything you want, but docs will be used for the examples that follow. At a minimum, it should include an index.md file.
• docs/index.md - The entry point for your documentation.

For example:

   your-great-component/
     docs/
       index.md
     catalog-info.yaml
     mkdocs.yml

If you have an existing repository that you'd like to add documentation to, skip to the Enable documentation for an already existing entity setup section below. Otherwise, continue reading to create a new software entity including documentation from scratch.

Use any software template

TechDocs is built on top of the docs like code approach. This, in short, means that you should keep documentation close to the code.

Your Backstage app has a set of software templates added by default. All of these software templates include everything you need to get your TechDocs site up and running and to start writing your documentation.

If you have created software templates that do not include documentation by default, we highly recommend you to set that up. Follow our how-to guide How to add documentation setup to your software templates to get started.

Enable documentation for an already existing entity

Prerequisites:

• An existing entity registered in backstage (e.g. via a catalog-info.yaml file).

To add documentation to an existing entity:

1. Create a mkdocs.yml file in the root of your repository with the following content:

   site_name: 'example-docs'
   
   nav:
     - Home: index.md
   
   plugins:
     - techdocs-core

   note

   The plugins section above is optional. Backstage automatically adds the techdocs-core plugin to the mkdocs file if it is missing. This functionality can be turned off with a configuration option in Backstage.

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

   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.

3. 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

4. Create a docs/index.md file, as a minimum. For example:

   # example docs
   
   This is a basic example of documentation.

5. Commit your changes, open a pull request and merge. You will now get your updated documentation next time you run Backstage!

Create a standalone documentation

There could be some situations where you don't want to keep your docs close to your code, but still want to publish documentation - for example, an onboarding tutorial. For this case, you can create a documentation component, which will be published as a standalone part of TechDocs.

1. Create an entity for your documentation. A minimal example could look like this:

   catalog-info.yaml

   apiVersion: backstage.io/v1alpha1
   kind: Component
   metadata:
     name: a-unique-name-for-your-docs
     annotations:
       # this could also be `url:<url>` if the documentation isn't in the same location
       backstage.io/techdocs-ref: dir:.
   spec:
     type: documentation
     lifecycle: experimental
     owner: user-or-team-name

2. Create the config file for mkdocs, which will be used to parse your docs:

   mkdocs.yml

   site_name: a-unique-name-for-your-docs
   site_description: An informative description
   plugins:
     - techdocs-core
   nav:
     - Getting Started: index.md

3. Add your index.md Markdown file, in a folder named docs/ with your desired documentation in Markdown. Your file structure should now look like this:

   your-great-documentation/
     docs/
       index.md
     catalog-info.yaml
     mkdocs.yml

4. Register your component in the software catalog using one of several options.

Writing and previewing your documentation

Using the techdocs-cli you can preview your docs inside a local Backstage instance and get live reload on changes. This is useful when you want to preview your documentation while writing.

To do this you can run:

cd /path/to/docs-repository/
npx @techdocs/cli serve