From 3b97f2212f1c47405665026b1fe598ffc921a174 Mon Sep 17 00:00:00 2001
From: Morgan Bentell <mbentell@spotify.com>
Date: Fri, 25 Aug 2023 17:28:54 +0200
Subject: [PATCH] add how to section for using other mkdocs plugins

Signed-off-by: Morgan Bentell <mbentell@spotify.com>
---
 docs/features/techdocs/how-to-guides.md | 29 +++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md
index b78a1a55af..2a842cd73f 100644
--- a/docs/features/techdocs/how-to-guides.md
+++ b/docs/features/techdocs/how-to-guides.md
@@ -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.