error generating documentation my component

Question

I have created a backstage scaffolding template to create a Spring boot rest service deployed to AWS EKS. When a component is created from it in backstage the component builds using github actions, is deployed to AWS EKS and is registered in backstage. However clicking on docs for the component fails with the following error

1 info: Step 1 of 3: Preparing docs for entity component:default/stephendemo16 {"timestamp":"2022-04-28T22:36:54.963Z"}
2 info: Prepare step completed for entity component:default/stephendemo16, stored at /tmp/backstage-EjxBxi {"timestamp":"2022-04-28T22:36:56.663Z"}
3 info: Step 2 of 3: Generating docs for entity component:default/stephendemo16 {"timestamp":"2022-04-28T22:36:56.663Z"}
4 error: Failed to build the docs page:
Could not read MkDocs YAML config file mkdocs.yml or mkdocs.yaml for validation; caused by Error: ENOENT: no such file or directory,
open '/tmp/backstage-EjxBxi/mkdocs.yml' {"timestamp":"2022-04-28T22:36:56.664Z"}

ERROR 404: T: Page not found. This could be because there is no index.md file in the root of the docs directory of this repository.

Looks like someone dropped the mic!

Catalog-info registers the docs subdirectory

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: "stephendemo16"
  description: "try using template"
  annotations:
    github.com/project-slug: xxxx/stephendemo16
    backstage.io/techdocs-ref: dir:docs

The docs subdirectory contains index.md which contains

## stephendemo16

try using template

## Getting started

Start write your documentation by adding more markdown (.md) files to this folder (/docs) or replace the content in this file.

## Table of Contents

The Table of Contents on the right is generated automatically based on the hierarchy
of headings. Only use one H1 (`#` in Markdown) per file.
...

What have I missed?

Answer 1

Having an index.md alone is not sufficient.

Internally, TechDocs is currently using MkDocs. Mkdocs has a config file called mkdocs.yaml that defines some metadata, plugins, and your file structure (table of contents).

Place an mkdocs.yaml inside your root directory. Mkdocs expects that all markdown files are located inside a /docs sub directory. It references your index.md file relative to that folder:

# You can pass the custom site name here
site_name: 'example-docs'

nav:
  # relative reference to your Markdown file and an optional title
  - Home: index.md

plugins:
  - techdocs-core

The location of your mkdocs.yaml is the root folder of your documentation. Therefore you have to adjust your backstage.io/techdocs-ref annotation to dir:. (means the same folder as your catalog info file).

You can find more details about using the TechDocs setup in the Backstage docs.