[Techdocs] README.md index page fallback does not work during `techdocs-cli generate` without `--techdocs-ref`

Relates to #7080. Relates to #6057.

The feature implemented in #7080 provides a fallback to a README.md file in case docs/index.md is not found. This doesn’t appear to work when generating docs in a CI/CD pipeline with the techdocs-cli generate command.

Expected Behavior

Docs generation should attempt to use a README.md in the source directory in case docs/index.md is not found.

Current Behavior

Docs generation is not using theREADME.md in the source directory when docs/index.md is not found.

Workaround

After some debugging, I found that providing a bogus value to the --techdocs-ref argument when generating from the root of my repository was enough to get the feature working:

# Fallback is not invoked
npx @techdocs/cli generate --no-docker -v

# Fallback works when providing a --techdocs-ref argument
npx @techdocs/cli generate --no-docker -v --techdocs-ref .

This seems to be because the patchIndexPreBuild method that provides the README.md fallback in techdocs-common is gated by the presence of a non-empty --techdocs-ref argument (represented by the parsedLocationAnnotation option): https://github.com/backstage/backstage/blob/986a5d869ea976fee71844c2aadd777907fde082/packages/techdocs-common/src/stages/generate/techdocs.ts#L95-L103

Possible Solution

I can’t see why patchIndexPreBuild needs to be called from within the conditional block. If it sounds like a reasonable path forward, I can PR a change that moves it outside so that it happens regardless of if a --techdocs-ref argument is provided during generation.

Your Environment

• techdocs version: latest (using npx for invocation)
• NodeJS Version: v16.13.10
• Operating System and Version: MacOS Big Sur 11.6

[ngeegoh]

Hi @ctrombley ,

I have the same issue but thanks to your workaround I can get it generated now. However, I have a question, when Backstage displays readme.md contents in techdocs, all the images attached to README.md cant be rendered and displayed. It looks like this Do you know whats the fix for this? or Backstage techdocs just cannot display images? (FYI: techdocs generates and publishs techdocs files to Azure storage account)

[soapraj]

Closing this issue for now. Please feel free to reopen if you have more inputs on this.