The core MkDocs plugin used by Backstage's TechDocs as a wrapper around multiple MkDocs plugins and Python Markdown extensions
This is the base Mkdocs plugin used when using Mkdocs with Spotify's TechDocs. It is written in Python and packages all of our Mkdocs defaults, such as theming, plugins, etc in a single plugin.
Requires Python version >= 3.8
$ pip install mkdocs-techdocs-core
Once you have installed the mkdocs-techdocs-core
plugin, you'll need to add it to your mkdocs.yml
.
site_name: Backstage Docs
nav:
- Home: index.md
- Developing a Plugin: developing-a-plugin.md
plugins:
- techdocs-core
You can install this package locally using pip
and the --editable
flag used for making developing Python packages.
pip install --editable .
You'll then have the techdocs-core
package available to use in Mkdocs and pip
will point the dependency to this folder.
We use black as our linter. Please run it against your code before submitting a pull request.
pip install black
black .
Note: This will write to all Python files in src/
with the formatted code. If you would like to only check to see if it passes, simply append the --check
flag.
If you have made changes to the plugin itself, or updated a dependency it's strongly recommended to test the plugin.
To build a version of the spotify/techdocs
docker image with your changes,
run the below script in this repository:
./build-e2e-image.sh
The script is only tested on OSX
The script assumes that you have the image repository cloned in a sibling directory to this repository (or you can specify its location).
It will build an image called mkdocs:local-dev
including the changes you
have made locally. To test the image in backstage, edit the config (e.g.
app-config.yaml
) with the following:
techdocs:
generator:
runIn: "docker"
dockerImage: "mkdocs:local-dev"
pullImage: false
setup.py
which triggers the release workflow on GitHub Actions to publish a new version in PyPI.The TechDocs Core MkDocs plugin comes with a set of extensions and plugins that mkdocs supports. Below you can find a list of all extensions and plugins that are included in the TechDocs Core plugin:
Plugins:
Extensions:
admonition: Admonitions, also known as call-outs, are an excellent choice for including side content without significantly interrupting the document flow. Material for MkDocs provides several different types of admonitions and allows for the inclusion and nesting of arbitrary content.
toc: The Table of Contents extension generates a Table of Contents from a Markdown document and adds it into the resulting HTML document. This extension is included in the standard Markdown library.
pymdown: PyMdown Extensions is a collection of extensions for Python Markdown. All extensions are found under the module namespace of pymdownx.
markdown_inline_graphviz: A Python Markdown extension replaces inline Graphviz definitions with inline SVGs or PNGs. Activate the inline_graphviz extension using the usage instructions.
plantuml_markdown: This plugin implements a block extension which can be used to specify a PlantUML diagram which will be converted into an image and inserted in the document.
svg_object
is not supported for rendering diagrams. Read more in the TechDocs troubleshooting section.mdx_truly_sane_lists: An extension for Python-Markdown that makes lists truly sane. Features custom indents for nested lists and fix for messy linebreaks and paragraphs between lists.
Note that the above set of plugins and extensions represents an opinionated
list providing a core set of functionality necessary for most technical
documentation needs (hence: techdocs-core
). PRs introducing new plugins or
extensions are welcome, but they are not guaranteed to be accepted.
In order to solve your organization's specific needs, you're encouraged to
install any necessary extensions/plugins in your own environment on top of
techdocs-core
(be it the TechDocs backend container, or a custom TechDocs
build container).
We only use material-mkdocs
as base styles because Backstage also uses the Material UI
on the client-side. We don't expect people to use themes other than Material UI
to maintain consistency across all Backstage pages (in other words, documentation pages have the same look and feel as any other Backstage page) and so we use the BackstageTheme
configured in Front-end application as the source of truth for all application design tokens like colors, typography and etc. So here you can see that some styles will always be overridden regardless of the mkdocs-material
plugin theme settings and this can cause unexpected behavior for those who override the theme setting in a mkdocs.yaml
file.
pymdown-extensions
to 10.3.1
which add material.extensions supportPython
version 3.7
pygments
to 2.17.2
which includes JSX support.mkdocs-material
(and its dependencies) from 9.1.3
to 9.2.7
causing a few changes:
1.5
theme.palette
is now hardcoded to {}
instead of ""
which caused some issues with some Material pluginspygments
to 2.16.1
, which also fixes a vulnerability.plantuml-markdown
to 3.9.2
.pymdownx.snippets
for security. restrict_base_path
will always be true
. If you currently use snippets with files outside of the directory, those files will no longer be included.pymdown-extensions
which contains security fixes.mkdocs-material
(and its dependencies) from 8.1.11
to 9.1.3
causing a few changes:
mkdocs-material
features were made opt-in v9. In order to preserve compatibility, they are now hardcoded as enabled by mkdocs-techdocs-core
. The features are
navigation.footer
content.action.edit
theme.palette
is now hardcoded to ""
to preserve previous behavior. Without hardcoding the palette, it gets the value default
, causing unwanted visual changes.@backstage/plugin-techdocs
which compensates these changes.mkdocs-monorepo-plugin
to 1.0.4
, which includes a compatibility
fix for mkdocs
versions 1.4.0
and newer.pyparsing
and Jinja2
dependencies, which are no
longer needed.mkdocs-monorepo-plugin
and markdown_inline_graphviz_extension
to
specific (latest) releases to improve stability. Going forward, these (along
with all other feature-related deps) will be bumped regularly and any changes
will be reflected in this changelog.1.1.4
that prevented sites from
being built under certain circumstances.plantuml-markdown
to 3.5.1
, which removes uuid
as a dependency.AttributeError: 'Theme' object has no attribute 'copy'
Note: Look the caveats section in readme about the Backstage theme consideration
pymdown-extensions
to 9.3 and enabled pygments_lang_class
to allow easier targeting of codeblocks by language in TechDocs Addons.Jinja2
pinned to v3.0.3.
Note: Going forward, this package will follow semver conventions.
plantuml-markdown
version to 3.5.0 for image maps supportmodule 'pyparsing' has no attribute 'downcaseTokens'
error as
a result of shifting python dependencies.mkdocs-monorepo-plugin
, which allows use of .yaml
file
extensions and non-slug-like site_name
s in monorepos.1.2.x
.1.2.2
requirements.txt
file in install_requires
of setup.py
. #24 ```java tab="java 2"
public void function() {
....
}
```
as well as the new
=== "Java"
```java
public void function() {
....
}
```
The pymdownx extension will be bumped too 8.0.0 in the near future.
pymdownx.tabbed is added to support tabs to group markdown content, such as codeblocks.
"PyMdown Extensions includes three extensions that are meant to replace their counterpart in the default Python Markdown extensions." Therefore some extensions has been taken away in this version that comes by default from pymdownx.extra which is added now (https://facelessuser.github.io/pymdown-extensions/usage_notes/#incompatible-extensions)
Copyright 2020-2023 © The Backstage Authors. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our Trademark Usage page: https://www.linuxfoundation.org/trademark-usage
Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0