How can I setup a standalone techdocs documentation?

Question

I just setup a local backstage instance with create-app and the first thing I'm trying to do is create a standalone techdocs component, for a "getting started" type of docs.

In the backstage docs, it says:

Your Backstage instance should by default have a documentation template added. If not, copy the catalog locations from the create-app template to add the documentation template.

Unfortunately, the standard setup created by create-app doesn't seem to include the docs template, just a Node.js example. And the catalog locations in the create-app template also don't have it.

I tried setting it up manually - this is my folder structure. I created the catalog folder in the same folder where all the backstage files are:

backstage/
    catalog/
        techdocs/
            docs/
                index.md
            catalog-info.yaml
            mkdocs.yml
    app-config.yaml
    // the rest of the backstage files

catalog-info.yaml:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: "getting-started-docs"
  backstage.io/techdocs-ref: dir:.
spec:
  type: documentation
  lifecycle: experimental

mkdocs.yml:

site_name: "getting-started-docs"
site_description: "How to get started with this portal"

app-config.yaml (the relevant parts, the rest is the default stuff create-app generated):

techdocs:
  builder: 'local'
  generator:
    runIn: 'docker'
  publisher:
    type: 'local'
locations:
    - type: file
      target: ../../catalog/techdocs/catalog-info.yaml

I see the component in the software catalog, but on the detail page the "View Techdocs" button isn't working and the "Docs" page also says it has "No documents to show". I didn't change any of the techdocs configuration in app-config.yaml.

When I run yarn dev I see the following relevant logs, which don't sound good:

[1] 2023-12-08T09:41:21.994Z search info Collating documents for techdocs via DefaultTechDocsCollatorFactory type=plugin documentType=techdocs
[1] 2023-12-08T09:41:22.079Z backstage info ::ffff:127.0.0.1 - - [08/Dec/2023:09:41:22 +0000] "GET /api/catalog/entities?filter=metadata.annotations.backstage.io%2Ftechdocs-ref&offset=0&limit=500 HTTP/1.1" 200 2 "-" "node-fetch/1.0 (+https://github.com/bitinn/node-fetch)" type=incomingRequest
[1] 2023-12-08T09:41:22.085Z search warn Index for techdocs was not created: indexer received 0 documents type=plugin documentType=techdocs
[1] 2023-12-08T09:41:22.086Z search info Collating documents for techdocs succeeded type=plugin documentType=techdocs

I also tried running npx @techdocs/cli serve --verbose but it fails with:

verbose: [docker/mkdocs] ERROR    -  Config value 'docs_dir': The path 'docs' isn't an existing directory.

Can someone point me in the right direction here? What do I need to do to get a standalone techdocs documentation?

Answer 1

I found the problem. The clue was in the startup logs:

"GET /api/catalog/entities?filter=metadata.annotations.backstage.io%2Ftechdocs-ref&offset=0&limit=500 HTTP/1.1" 200
search warn Index for techdocs was not created: indexer received 0 documents type=plugin documentType=techdocs

I tried the GET request against http://localhost:7007/api/catalog/entities?filter=metadata.annotations.backstage.io%2Ftechdocs-ref&offset=0&limit=500 and there really were no results, which gave me the clue that something is wrong with the backstage.io/techdocs-ref annotation. The docs for the techdocs-ref annotation show that the structure should have been:

metadata:
  name: "getting-started-docs"
  annotations:
    backstage.io/techdocs-ref: dir:.

I also updated the backstage docs with a little guide.