TechDocs - DDOS itself if not built with techdocs-cli

[veenarm]

📜 Issue Labels

• [x] Please familiarize yourself with the issue labels used in this project: LABELS.md

🔎 Search Terms

techdocs not found

🗃️ Project Area

TechDocs

🔗 External Integration

N/A

📝 Description & Context

Started moving from local build to external however our CI used mkdocs instead of the techdocs-cli.

This caused a file (techdocs_json) can't remember top of my head the name, to not exist.

When attempting to access the docs via the entity in docs, the docs seemed to load ok however the entire page just flickers constantly, and repeatedly ddossing itself trying to find that missing techdocs file.

👍 Expected Behavior

I'd expect it to only attempt to find the file once or twice, not constantly ddos.

OR

Display a page saying the documents may not of been generated properly and to look at the techdocs-cli

(We've since fixed all our CI/CD and it now works properly)

📦 Reproduction Repo

No response

🥾 Reproduction steps

Generate mkdocs with mkdocs, and publish with cli (don't generate with techdocs cli).

Access the docs via backstage/docs.

Have you read the Code of Conduct?

• [x] I have read the Code of Conduct

Are you willing to submit PR?

Yes, but I would like some more guidance

[awanlin]

Hi @veenarm, thanks for logging this. Though TechDocs doesn't support the results from running MkDocs directly it should fail fast for cases like this and not get stuck in a loop. It would be really helpful if you could share what file was causing the issue though.

Also, you marked this needing more guidance, what additional details do you need?

[veenarm]

File: techdocs_metadata.json

If not found it just continuously loops trying to find it.

I guess what's the expected behavior? Should it send to an error page that advises to use tech docs cli not medics vanilla? Or could it possibly work with just using mkdocs vanilla?

It seems to render the content just fine except for that file causing the flashing loop.

Looks like it's here: https://github.com/backstage/backstage/blob/master/plugins/techdocs-react/src/context.tsx#L126

with line 140

@awanlin this enough?