paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 45 Packages Projects Releases Wiki Activity

add how to section for using other mkdocs plugins

Browse Source 
Signed-off-by: Morgan Bentell <mbentell@spotify.com>
This commit is contained in:
Morgan Bentell
2023-08-25 17:28:54 +02:00
parent dbc4b61f6d
commit 3b97f2212f
1 changed files with 29 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/features/techdocs/how-to-guides.md
+29
View File
@@ -675,3 +675,32 @@ entity. If the value of this annotation is `'local'`, the TechDocs backend will
and publish the documentation for them. If the value of the `company.com/techdocs-builder`
annotation is anything other than `'local'`, the user is responsible for publishing
documentation to the appropriate location in the TechDocs external storage.
## How to use other mkdocs plugins?
The default plugin [mkdocs-techdocs-core](https://github.com/backstage/mkdocs-techdocs-core) provides a set of plugins that can be viewed as the minimum required plugins to enable TechDocs. Your organization might have needs beyond the core set though, here is the recommended way to enable other plugins.
### Install the plugin
#### With CI generation
If you generate the HTML files in CI using `@techdocs/cli`, you need to install the desired mkdocs plugin in the runtime where the cli is being executed. This might be e.g. a docker image or a Jenkins node. Use the `--no-docker` flag with the cli to pick up the plugin you just installed.
#### With local generation
Create a new Docker image that extends [spotify/techdocs](https://github.com/backstage/techdocs-container), roughly:
```Dockerfile
FROM spotify/techdocs:<version>
pip install <the_plugin_you_want>
...
```
Then publish the image and use it in your config under the `techdocs.generator.dockerImage` [key](https://github.com/backstage/techdocs-container).
### Specify the plugin in the mkdocs config
To use the plugin, it has to be listed in the `mkdocs.yaml` file. You can either add the plugin to your applicable files, or specify defaults.
To make a mkdocs plugin available for all your TechDocs components you can either list it in the `techdocs.generator.mkdocs.defaultPlugins` [config](https://github.com/backstage/backstage/blob/master/plugins/techdocs-backend/config.d.ts#L64C14-L64C14), or use the `--defaultPlugin` [cli option](https://backstage.io/docs/features/techdocs/cli#generate-techdocs-site-from-a-documentation-project) depending on your setup.