Make it work when served locally using techdocs-cli

[stephane-mori]

Hi,

I am looking for a way to make this addon work serving the documentation localy in a Backstage app-like environment using "techdocs-cli serve" command.

Is it something possible ?

Regards,
Stéphane

[johanneswuerbach]

As far as I know this is still not possible yet in backstage itself backstage/backstage#4123 (comment).

Could you create an issue in the backstage project and link it here?

[axdotl]

You can build a custom container based on the techdocs-container:

FROM spotify/techdocs:v1.1.1

RUN pip install --no-cache-dir mkdocs-mermaid2-plugin==0.6.0

ENTRYPOINT [ "mkdocs" ]

And serve it like

techdocs-cli serve:mkdocs -i my-custom-techdocs-container:latest

[michaelfeinbier]

Hey @axdotl thats a nice approach but at least for me it does not work :(
However, following the discussion in the backstage tickets linked above and according to the comment from @johanneswuerbach we should think here how to solve that properly. In general I like the approach to provide a special docker image which you can then use in the techdocs-cli command which has the plugin somehow loaded already there as well. Not sure how to achieve this but happy to dig into that a bit if you'd agree on the proposal

[jedelson-pagerduty]

The working approach is to use the --preview-app-bundle-path argument to techdocs-cli serve. IIRC, this was added in version 1.3.0 of the CLI.

General steps:

1. Create a new project based on the code in https://github.com/backstage/backstage/tree/master/packages/techdocs-cli-embedded-app.
2. Add this add on (and whatever other techdocs addons you want) to that project using the normal installation methods.
3. Build the project
4. Pass the path to the project's dist path as the value of the --preview-app-bundle-path arg.

Optionally, distribute the project (make sure to include the dist directory in the tarball) via an npm registry.

The -i argument is for the build container, not the backstage app.