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.7
$ 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.
Much of the value of this plugin lies in its dependencies, on which there are implicit dependencies upstream in the Backstage TechDocs frontend plugin. Each time you update a pinned dependency, it's important to test that generated documentation can be loaded and parsed as expected in the Backstage frontend. The recommended way to do so is the following:
- Make the expected dependency change locally in
requirements.txt
. - Clone the techdocs-container
image and, within the cloned directory, copy the entire contents of your
local version of
mkdocs-techdocs-core
, e.g. namedlocal-mkdocs-techdocs-core
. - Just before the
RUN pip install
command intechdocs-container
's Dockerfile, add aCOPY
command that copies the contents of your modifiedmkdocs-techdocs-core
directory into the container's file system. Something like:COPY ./local-mkdocs-techdocs-core/ /local-mkdocs-techdocs-core/
- Modify the
RUN pip install
... command to install an editable version of the copied local plugin, rather than the specific version. Something like...RUN pip install --upgrade pip && pip install -e /local-mkdocs-techdocs-core
- Build the modified image:
docker build -t mkdocs:local-dev .
- Modify your local Backstage instance to use your locally built
techdocs-container
instead of using the published image by setting the following configuration:
techdocs:
generator:
runIn: "docker"
dockerImage: "mkdocs:local-dev"
- Update the Changelog.
- Bump up the version number in
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:
- search: A search plugin is provided by default with MkDocs which uses lunr.js as a search engine.
- mkdocs-monorepo-plugin: This plugin enables you to build multiple sets of documentation in a single MkDocs project. It is designed to address writing documentation in Spotify's largest and most business-critical codebases (typically monoliths or monorepos).
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.
- caret: Caret is an extension that is syntactically built around the ^ character. It adds support for inserting superscripts and adds an easy way to place text in an <ins> tag.
- critic: Critic adds handling and support of Critic Markup.
- details: Details creates collapsible elements with <details> and <summary> tags.
- emoji: Emoji makes adding emoji via Markdown easy 😄.
- superfences: SuperFences is like Python Markdown's fences, but better. Nest fences under lists, admonitions, and other syntaxes. You can even create special custom fences for content like UML.
- inlinehilite: InlineHilite highlights inline code: from module import function as func.
- magiclink: MagicLink linkafies URL and email links without having to wrap them in Markdown syntax. Also, shortens repository issue, pull request, and commit links automatically for popular code hosting providers. You can even use special shorthand syntax to link to issues, diffs, and even mention people
- mark: Mark allows you to mark words easily.
- smartsymbols: SmartSymbols inserts commonly used Unicode characters via simple ASCII representations: =/= → ≠.
- highlight: Highlight allows you to configure the syntax highlighting of SuperFences and InlineHilite. Also passes standard Markdown indented code blocks through the syntax highlighter.
- extra: Extra is just like Python Markdown's Extra package except it uses PyMdown Extensions to substitute similar extensions.
- tabbed: Tabbed allows for tabbed Markdown content.
- tasklist: Tasklist allows inserting lists with check boxes.
- tilde: Tilde is syntactically built around the ~ character. It adds support for inserting subscripts and adds an easy way to place text in a <del> tag.
-
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.
- Note that the format
svg_object
is not supported for rendering diagrams. Read more in the TechDocs troubleshooting section.
- Note that the format
-
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.
- Updated
mkdocs-monorepo-plugin
to1.0.4
, which includes a compatibility fix formkdocs
versions1.4.0
and newer.
- Removed pins on the
pyparsing
andJinja2
dependencies, which are no longer needed. - Pinned
mkdocs-monorepo-plugin
andmarkdown_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.
- Added support for Python 3.10 #73
- Resolved a run-time error introduced in
1.1.4
that prevented sites from being built under certain circumstances.
- Support markdown version >3.2,<4
- Use markdown_inline_graphviz_extension 1.1.1 which supports svg rendering for markdown >=3.3
- Upgraded
plantuml-markdown
to3.5.1
, which removesuuid
as a dependency.
- Simplify theme code to update only the attribute necessary by backstage.
- Fix run-time
AttributeError: 'Theme' object has no attribute 'copy'
- Add new capability to override mkdocs theme attributes
Note: Look the caveats section in readme about the Backstage theme consideration
- Bumped
pymdown-extensions
to 9.3 and enabledpygments_lang_class
to allow easier targeting of codeblocks by language in TechDocs Addons.
Jinja2
pinned to v3.0.3.
- This package has been promoted to v1.0!
Note: Going forward, this package will follow semver conventions.
- Upgrade mkdocs-material and its dependencies
- Update
plantuml-markdown
version to 3.5.0 for image maps support
- Fix run-time
module 'pyparsing' has no attribute 'downcaseTokens'
error as a result of shifting python dependencies. - Update to latest
mkdocs-monorepo-plugin
, which allows use of.yaml
file extensions and non-slug-likesite_name
s in monorepos.
- Add mdx_truly_sane_lists for dealing with the very annoying bullet differences in mkdocs vs commonmark / gf markdown. See backstage/backstage#6057 (comment)
- Fix the dependency version of Markdown to ensure GraphViz SVG rendering works.
- Ensure required mkdocs-monorepo-plugin is compatible with Mkdocs
1.2.x
.
- Improved dependency compatibility with other mkdocs plugins.
- Upgraded mkdocs minimum to
1.2.2
- Reused data from
requirements.txt
file ininstall_requires
ofsetup.py
. #24
- Upgrade monorepo to track latest patch, includes various bug fixes. #22
- Upgrade plantuml-markdown to 3.4.2 with support for external file sources. #18
- Fixed issue where the whole temp directory could be included in the built site output. #7
- Updated home repository to be the new https://github.com/backstage/mkdocs-techdocs-core
- Any MkDocs plugin configurations from mkdocs.yml will now work and override the default configuration. See backstage/backstage#3017
- Pin Markdown version to fix issue with Graphviz
- Change development status to 3 - Alpha
- Superfences and Codehilite doesn't work very well together (squidfunk/mkdocs-material#1604) so therefore the codehilite extension is replaced by pymdownx.highlight
- Uses pymdownx extensions v.7.1 instead of 8.0.0 to allow legacy_tab_classes config. This makes the techdocs core plugin compatible with the usage of tabs for grouping markdown with the following syntax:
```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)
- Fix an issue with configuration of emoji support
- Further adjustments to versions to find ones that are compatible
- Downgrade some versions of markdown extensions to versions that are more stable
- Added support for more mkdocs extensions
- mkdocs-material
- mkdocs-monorepo-plugin
- plantuml-markdown
- markdown_inline_graphviz_extension
- pygments
- pymdown-extensions
Copyright 2020-2021 © 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