Backstage Unable to use mkdocs to create Tech Docs for an existing component

Question

I have enabled Github actions to create Tech docs after a commit. Below is the workflow file written to create Md files. But "techdocs-cli generate --no-docker --verbose" command fails with the below error. Can someone please help with the issue?

Failed to generate docs from /home/runner/work/myapp3/myapp3 into /home/runner/work/myapp3/myapp3/site; caused by unknown error 'Command mkdocs failed, exit code: 1'

workflow file:

name: Publish TechDocs Site
on:
 push:
 branches: master

jobs:
 publish-techdocs-site:
  runs-on: ubuntu-latest
  env:
  TECHDOCS_S3_BUCKET_NAME: XXX
  AWS_ACCESS_KEY_ID: XXX
  AWS_SECRET_ACCESS_KEY: XXX
  AWS_REGION:  XXX
  ENTITY_NAMESPACE: 'default'
  ENTITY_KIND: 'Component'
  ENTITY_NAME: ‘XXX’

steps:
  - name: Checkout code
    uses: actions/checkout@v2

  - uses: actions/setup-node@v2
  - uses: actions/setup-python@v2

  - name: Install techdocs-cli
    run: sudo npm install -g @techdocs/cli

  - name: Install mkdocs and mkdocs plugins
    run: python -m pip install mkdocs-techdocs-core==1.*

  - name: Generate docs site
    run: techdocs-cli generate --no-docker --verbose

  - name: Publish docs site
    run: techdocs-cli publish --publisher-type awsS3 --storage-name $TECHDOCS_S3_BUCKET_NAME --entity $ENTITY_NAMESPACE/$ENTITY_KIND/$ENTITY_NAME

Answer 1

I had the same issue and it was resolved once you had the right folder structure where you have the mkdocs.yml file.

As long as you have a docs folder in the same root structure with the .md file that needs to be published.

The same .md file needs to be configured in the navigation section of the mkdocs.yml file as well