Backstage tech-docs configuration returning "Error: spawn mkdocs ENOENT"

Question

When I try to run Backstage locally, and visiting the Project documentation, I'm getting the following error:

error: Failed to build the docs page: Failed to generate docs from /tmp/backstage-5lZR3i into /tmp/techdocs-tmp-hvh4yi; caused by Error: spawn mkdocs ENOENT {"timestamp":"2022-06-02T18:02:06.573Z"}

Does anyone have a clue?

I'm trying to config my Backstage tech docs. I have an external Gitlab repo and I put the following files in the repo root directory:

mkdocs.yml

site_name: ${{values.component_id}}
site_description: ${{values.description}}

nav:
  - Home: index.md

plugins:
  - techdocs-core

docs/index.md

# example docs

This is a basic example of documentation.

In Backstage, my component yaml looks like this

packages/catalog-model/components/my-site.yaml

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: My-Site
  description: This is a component.
  annotations:
    argocd/app-name: 'my-site'
    gitlab.com/project-id: '007'
    backstage.io/view-url: https://some.website/catalog-info.yaml
    backstage.io/edit-url: https://git.my-company.net/my-company/backstage/blob/main/packages/catalog-model/components/my-site-component.yaml
    backstage.io/source-location: url:https://git.my-company.net/my-company/my-site
    backstage.io/techdocs-ref: url:https://git.my-company.net/my-company/my-site/
spec:
  type: component
  lifecycle: experimental
  owner: Dream
  system: Platform

Answer 1

Backstage suggest to modify the Dockerfile for solving this problem.

https://backstage.io/docs/features/techdocs/getting-started#disabling-docker-in-docker-situation-optional

# Dockerfile
RUN apt-get update && apt-get install -y python3 python3-pip
RUN pip3 install mkdocs-techdocs-core==1.0.1

Edit: This docker script should be into packages/backend/Dockerfile. Because the entire file generate running in the backend

Answer 2

I think this error happens when mkdocs is not installed locally. You can refer to these installation guidelines, and the issue should be solved