search

backstage / mkdocs-techdocs-core

The core MkDocs plugin used by Backstage's TechDocs as a wrapper around multiple MkDocs plugins and Python Markdown extensions
Apache License 2.0
82 stars 61 forks source link

readme

mkdocs-techdocs-core

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.

Package on PyPI

Usage

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

Development

Running Locally

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.

Linting

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.

Testing Dependencies End-to-End

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

Release

  1. Update the Changelog.
  2. Bump up the version number in setup.py which triggers the release workflow on GitHub Actions to publish a new version in PyPI.

MkDocs plugins and extensions

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:

Other plugins and extensions

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).

Caveats

Theme

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.

Changelog

1.4.0

1.3.6

1.3.5

1.3.3

1.3.2

1.3.1

1.3

1.2.3

1.2.2

1.2.1

1.2.0

1.1.7

1.1.6

1.1.5

1.1.4

1.1.3

1.1.2

1.1.1

1.1.0

Note: Look the caveats section in readme about the Backstage theme consideration

1.0.2

1.0.1

Jinja2 pinned to v3.0.3.

1.0.0

Note: Going forward, this package will follow semver conventions.

0.2.3

0.2.2

0.2.1

0.2.0

0.1.2

0.1.1

0.1.0

0.0.16

0.0.15

0.0.14

0.0.13

0.0.12

0.0.11

0.0.10

0.0.9

0.0.8

    ```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)

### 0.0.7

- Fix an issue with configuration of emoji support

### 0.0.6

- Further adjustments to versions to find ones that are compatible

### 0.0.5

- Downgrade some versions of markdown extensions to versions that are more stable

### 0.0.4

- Added support for more mkdocs extensions
  - mkdocs-material
  - mkdocs-monorepo-plugin
  - plantuml-markdown
  - markdown_inline_graphviz_extension
  - pygments
  - pymdown-extensions

## License

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