search

johanneswuerbach / backstage-plugin-techdocs-addon-mermaid

Backstage TechDocs Mermaid Addon
MIT License
46 stars 20 forks source link

Make it work when served locally using techdocs-cli #11

Open stephane-mori opened 1 year ago

stephane-mori commented 1 year ago

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 commented 1 year ago

As far as I know this is still not possible yet in backstage itself https://github.com/backstage/backstage/issues/4123#issuecomment-1131801187.

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

axdotl commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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.