[techdocs] Use `gh-admonitions` plugin everywhere

[iainlane]

The gh-admonitions plugin was added to the shared workflow in 7973f46

It's not ideal that individual repositories have to add this to their config. This ought to be something that works out ouf the box.

The @techdocs/cli script has a flag:

Usage: techdocs-cli generate|build [options]

Generate TechDocs documentation site using MkDocs.

Options:
  ...
  --defaultPlugin [defaultPlugins...]  Plugins which should be added automatically to the mkdocs.yaml file (default: [])
  ...

which might be able to be used for this purpose, if it works like it sounds.

[iainlane]

I got asked for some more info on this - replying here instead of in a DM so it's preserved.

An admonition is a callout which is supported by GitHub, but it's not standard Markdown.

Note

It's one of these things

A few of our docs use this. I had used it in deployment_tools and then we noticed that the rendering in EngHub was messed up because it didn't support the syntax.

In 7973f46 we added the required mkdocs plugin to the container. This enabled repositories to opt in to getting the support, because the container they use to generate their docs now contained the required code. You would opt in by adding this to your mkdocs.yml:

plugins:
  - gh-admonitions

My position in general is that as far as possible we should make things work without needing to configure them. For docs, it's surprising when something works on GitHub and then doesn't work on EngHub. It makes EngHub feel less good to use.

The issue here is suggesting that we find a way to enable that plugin automatically, so that repositories don't have to update their configuration.

[iamrajiv]

hi @iainlane i can try this can you assign me?