Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/glennmatthews/markdown-version-annotations
MkDocs plugin to add custom admonitions for documenting version differences
https://github.com/glennmatthews/markdown-version-annotations
mkdocs mkdocs-plugin
Last synced: 2 months ago
JSON representation
MkDocs plugin to add custom admonitions for documenting version differences
- Host: GitHub
- URL: https://github.com/glennmatthews/markdown-version-annotations
- Owner: glennmatthews
- License: mit
- Created: 2022-09-14T15:06:14.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-06T16:44:29.000Z (8 months ago)
- Last Synced: 2024-10-08T00:42:06.824Z (3 months ago)
- Topics: mkdocs, mkdocs-plugin
- Language: Python
- Homepage:
- Size: 43 KB
- Stars: 5
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Markdown Version Annotations
This is a simple [Markdown](https://python-markdown.github.io/) plugin that adds a few simple macros to make it quicker and easier to add self-consistent annotations to your documentation about differences between project versions.
This plugin was originally developed for use with the [Nautobot](https://docs.nautobot.com/) project's documentation but should be reusable.
## Usage
Install this plugin with `pip install markdown_version_annotations` and enable it as a plugin in your `mkdocs.yml`. You also should enable the [`admonition`](https://python-markdown.github.io/extensions/admonition/) Markdown extension *after* this plugin:
```yaml
markdown_extensions:
- "markdown_version_annotations"
- "admonition"
```
In your documentation, you can then use any of the following macros at the start of any line (or with leading whitespace as appropriate, e.g for indentation or nesting of admonitions within one another):
- `+++ 1.0.0` as an annotation that something was added in version 1.0.0 of your project
- `+/- 1.0.0` as a annotation that something was changed in version 1.0.0 of your project
- `--- 1.0.0` as a annotation that something was removed in version 1.0.0 of your project
Because these macros will be transformed into Markdown ["admonitions"](https://python-markdown.github.io/extensions/admonition/), you can optionally include a summary in quotes at the end of this line, and further details of the change as text on the following line(s) with a four-space indent, such as:
```markdown
+++ 1.0.0 "Added more parameters"
Added the following parameters:
- "mass"
- "spin"
- "flavor"
```
which would render in the Markdown-generated HTML as:
```html
Added in version 1.0.0 — Added more parameters
Added the following parameters:
...
```
## Plugin Configuration
By default, these macros will render as the following admonitions, which are suitable for use with [`mkdocs-material`](https://squidfunk.github.io/mkdocs-material/) or similar themes that allow for [custom admonition styling](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#custom-admonitions):
```markdown
!!! version-added "Added in version — "
```
```markdown
!!! version-changed "Changed in version — "
```
```markdown
!!! version-removed "Removed in version — "
```
This can be fully customized via configuration, if desired! The following configuration keys can be specified in `mkdocs.yml` under the `markdown_version_annotations` entry:
| Configuration | Default Value |
| ---------------------------- | -------------------------- |
| `admonition_tag` | `"!!!"` |
| `version_added_admonition` | `"version-added"` |
| `version_added_title` | `"Added in version \\1"` |
| `version_changed_admonition` | `"version-changed"` |
| `version_changed_title` | `"Changed in version \\1"` |
| `version_removed_admonition` | `"version-removed"` |
| `version_removed_title` | `"Removed in version \\1"` |
In the `_title` configs, the `\1` (backslash-escaped in YAML as `"\\1"`) corresponds to the version number specified in any given usage of the macro.
So for example, you could configure:
```yaml
markdown_extensions:
- markdown_version_annotations:
admonition_tag: "???"
version_added_admonition: "info"
version_added_title: "New in version \\1"
```
in which case a `+++ 1.2.3` macro would now be rendered as a default-collapsed "info" admonition:
```markdown
??? info "New in version 1.2.3"
```
## Styling with `mkdocs-material`
If using [`mkdocs-material`](https://squidfunk.github.io/mkdocs-material/), you might want to add something like the following to the `extra.css` for your project documentation in order to have custom styling for each of these three custom admonition types. (If you don't add this, or use a different theme, they should still render nonetheless, most likely using the same styling as generic "info" admonitions.)
```css
:root {
/* Icon for "version-added" admonition: Material Design Icons "plus-box-outline" */
--md-admonition-icon--version-added: url('data:image/svg+xml;charset=utf-8,');
/* Icon for "version-changed" admonition: Material Design Icons "delta" */
--md-admonition-icon--version-changed: url('data:image/svg+xml;charset=utf-8,');
/* Icon for "version-removed" admonition: Material Design Icons "minus-circle-outline" */
--md-admonition-icon--version-removed: url('data:image/svg+xml;charset=utf-8,');
}
/* "version-added" admonition in green */
.md-typeset .admonition.version-added,
.md-typeset details.version-added {
border-color: rgb(0, 200, 83);
}
.md-typeset .version-added > .admonition-title,
.md-typeset .version-added > summary {
background-color: rgba(0, 200, 83, .1);
}
.md-typeset .version-added > .admonition-title::before,
.md-typeset .version-added > summary::before {
background-color: rgb(0, 200, 83);
-webkit-mask-image: var(--md-admonition-icon--version-added);
mask-image: var(--md-admonition-icon--version-added);
}
/* "version-changed" admonition in orange */
.md-typeset .admonition.version-changed,
.md-typeset details.version-changed {
border-color: rgb(255, 145, 0);
}
.md-typeset .version-changed > .admonition-title,
.md-typeset .version-changed > summary {
background-color: rgba(255, 145, 0, .1);
}
.md-typeset .version-changed > .admonition-title::before,
.md-typeset .version-changed > summary::before {
background-color: rgb(255, 145, 0);
-webkit-mask-image: var(--md-admonition-icon--version-changed);
mask-image: var(--md-admonition-icon--version-changed);
}
/* "version-removed" admonition in red */
.md-typeset .admonition.version-removed,
.md-typeset details.version-removed {
border-color: rgb(255, 82, 82);
}
.md-typeset .version-removed > .admonition-title,
.md-typeset .version-removed > summary {
background-color: rgba(255, 82, 82, .1);
}
.md-typeset .version-removed > .admonition-title::before,
.md-typeset .version-removed > summary::before {
background-color: rgb(255, 82, 82);
-webkit-mask-image: var(--md-admonition-icon--version-removed);
mask-image: var(--md-admonition-icon--version-removed);
}
```
## Development
The development environment for this plugin is based on [`invoke`](http://www.pyinvoke.org/) and [`Poetry`](https://python-poetry.org/). After installing Poetry itself, you can run `poetry shell` followed by `poetry install` to set up a Python virtual environment populated with this plugin's development tool dependencies. You can then use the installed `invoke` command to execute various development tasks:
```
$ invoke --list
Available tasks:
bandit Run bandit to validate basic static code security analysis.
black Run black to check that Python files are consistently formatted.
flake8 Run flake8 code analysis.
pydocstyle Run pydocstyle to validate docstring formatting adheres to standards.
pylint Run pylint code static analysis.
tests Run all linters and tests for this repository.
```
After making any code change, it is recommended to run `invoke tests` before committing your code.