{"id":15283787,"url":"https://github.com/glennmatthews/markdown-version-annotations","last_synced_at":"2025-07-06T14:06:12.079Z","repository":{"id":59319588,"uuid":"536634476","full_name":"glennmatthews/markdown-version-annotations","owner":"glennmatthews","description":"MkDocs plugin to add custom admonitions for documenting version differences","archived":false,"fork":false,"pushed_at":"2024-05-06T16:44:29.000Z","size":44,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-06-21T18:18:40.564Z","etag":null,"topics":["mkdocs","mkdocs-plugin"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/glennmatthews.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-09-14T15:06:14.000Z","updated_at":"2025-03-13T11:02:25.000Z","dependencies_parsed_at":"2024-05-06T17:07:48.153Z","dependency_job_id":null,"html_url":"https://github.com/glennmatthews/markdown-version-annotations","commit_stats":null,"previous_names":["glennmatthews/markdown-version-annotations","glennmatthews/mkdocs-version-annotations"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/glennmatthews/markdown-version-annotations","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glennmatthews%2Fmarkdown-version-annotations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glennmatthews%2Fmarkdown-version-annotations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glennmatthews%2Fmarkdown-version-annotations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glennmatthews%2Fmarkdown-version-annotations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/glennmatthews","download_url":"https://codeload.github.com/glennmatthews/markdown-version-annotations/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glennmatthews%2Fmarkdown-version-annotations/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263914457,"owners_count":23529078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mkdocs","mkdocs-plugin"],"created_at":"2024-09-30T14:47:38.629Z","updated_at":"2025-07-06T14:06:12.057Z","avatar_url":"https://github.com/glennmatthews.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Markdown Version Annotations\n\nThis 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.\n\nThis plugin was originally developed for use with the [Nautobot](https://docs.nautobot.com/) project's documentation but should be reusable.\n\n## Usage\n\nInstall 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:\n\n```yaml\nmarkdown_extensions:\n  - \"markdown_version_annotations\"\n  - \"admonition\"\n```\n\nIn 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):\n\n- `+++ 1.0.0` as an annotation that something was added in version 1.0.0 of your project\n- `+/- 1.0.0` as a annotation that something was changed in version 1.0.0 of your project\n- `--- 1.0.0` as a annotation that something was removed in version 1.0.0 of your project\n\nBecause 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:\n\n```markdown\n+++ 1.0.0 \"Added more parameters\"\n    Added the following parameters:\n\n    - \"mass\"\n    - \"spin\"\n    - \"flavor\"\n```\n\nwhich would render in the Markdown-generated HTML as:\n\n```html\n\u003cdiv class=\"admonition version-added\"\u003e\n\u003cp class=\"admonition-title\"\u003eAdded in version 1.0.0 — Added more parameters\u003c/p\u003e\n\u003cp\u003eAdded the following parameters:\u003c/p\u003e\n\u003cul\u003e...\u003c/ul\u003e\n\u003c/div\u003e\n```\n\n## Plugin Configuration\n\nBy 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):\n\n```markdown\n!!! version-added \"Added in version \u003cversion\u003e — \u003csummary\u003e\"\n```\n\n```markdown\n!!! version-changed \"Changed in version \u003cversion\u003e — \u003csummary\u003e\"\n```\n\n```markdown\n!!! version-removed \"Removed in version \u003cversion\u003e — \u003csummary\u003e\"\n```\n\nThis can be fully customized via configuration, if desired! The following configuration keys can be specified in `mkdocs.yml` under the `markdown_version_annotations` entry:\n\n| Configuration                | Default Value              |\n| ---------------------------- | -------------------------- |\n| `admonition_tag`             | `\"!!!\"`                    |\n| `version_added_admonition`   | `\"version-added\"`          |\n| `version_added_title`        | `\"Added in version \\\\1\"`   |\n| `version_changed_admonition` | `\"version-changed\"`        |\n| `version_changed_title`      | `\"Changed in version \\\\1\"` |\n| `version_removed_admonition` | `\"version-removed\"`        |\n| `version_removed_title`      | `\"Removed in version \\\\1\"` |\n\nIn the `_title` configs, the `\\1` (backslash-escaped in YAML as `\"\\\\1\"`) corresponds to the version number specified in any given usage of the macro.\n\nSo for example, you could configure:\n\n```yaml\nmarkdown_extensions:\n  - markdown_version_annotations:\n      admonition_tag: \"???\"\n      version_added_admonition: \"info\"\n      version_added_title: \"New in version \\\\1\"\n```\n\nin which case a `+++ 1.2.3` macro would now be rendered as a default-collapsed \"info\" admonition:\n\n```markdown\n??? info \"New in version 1.2.3\"\n```\n\n## Styling with `mkdocs-material`\n\nIf 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.)\n\n```css\n:root {     \n    /* Icon for \"version-added\" admonition: Material Design Icons \"plus-box-outline\" */\n    --md-admonition-icon--version-added: url('data:image/svg+xml;charset=utf-8,\u003csvg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"\u003e\u003cpath d=\"M19 19V5H5v14h14m0-16a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h14m-8 4h2v4h4v2h-4v4h-2v-4H7v-2h4V7Z\"/\u003e\u003c/svg\u003e');\n    /* Icon for \"version-changed\" admonition: Material Design Icons \"delta\" */\n    --md-admonition-icon--version-changed: url('data:image/svg+xml;charset=utf-8,\u003csvg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"\u003e\u003cpath d=\"M12 7.77 18.39 18H5.61L12 7.77M12 4 2 20h20\"/\u003e\u003c/svg\u003e');\n    /* Icon for \"version-removed\" admonition: Material Design Icons \"minus-circle-outline\" */\n    --md-admonition-icon--version-removed: url('data:image/svg+xml;charset=utf-8,\u003csvg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"\u003e\u003cpath d=\"M12 20c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8m0-18A10 10 0 0 0 2 12a10 10 0 0 0 10 10 10 10 0 0 0 10-10A10 10 0 0 0 12 2M7 13h10v-2H7\"/\u003e\u003c/svg\u003e');\n}\n\n/* \"version-added\" admonition in green */\n.md-typeset .admonition.version-added,\n.md-typeset details.version-added {\n    border-color: rgb(0, 200, 83);\n}\n.md-typeset .version-added \u003e .admonition-title,\n.md-typeset .version-added \u003e summary {\n    background-color: rgba(0, 200, 83, .1);\n}\n.md-typeset .version-added \u003e .admonition-title::before,\n.md-typeset .version-added \u003e summary::before {\n    background-color: rgb(0, 200, 83);\n    -webkit-mask-image: var(--md-admonition-icon--version-added);\n    mask-image: var(--md-admonition-icon--version-added);\n}\n\n/* \"version-changed\" admonition in orange */\n.md-typeset .admonition.version-changed,\n.md-typeset details.version-changed {\n    border-color: rgb(255, 145, 0);\n}\n.md-typeset .version-changed \u003e .admonition-title,\n.md-typeset .version-changed \u003e summary {\n    background-color: rgba(255, 145, 0, .1);\n}\n.md-typeset .version-changed \u003e .admonition-title::before,\n.md-typeset .version-changed \u003e summary::before {\n    background-color: rgb(255, 145, 0);\n    -webkit-mask-image: var(--md-admonition-icon--version-changed);\n    mask-image: var(--md-admonition-icon--version-changed);\n}\n\n/* \"version-removed\" admonition in red */\n.md-typeset .admonition.version-removed,\n.md-typeset details.version-removed {\n    border-color: rgb(255, 82, 82);\n}\n.md-typeset .version-removed \u003e .admonition-title,\n.md-typeset .version-removed \u003e summary {\n    background-color: rgba(255, 82, 82, .1);\n}\n.md-typeset .version-removed \u003e .admonition-title::before,\n.md-typeset .version-removed \u003e summary::before {\n    background-color: rgb(255, 82, 82);\n    -webkit-mask-image: var(--md-admonition-icon--version-removed);\n    mask-image: var(--md-admonition-icon--version-removed);\n}\n```\n\n## Development\n\nThe 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:\n\n```\n$ invoke --list\nAvailable tasks:\n\n  bandit       Run bandit to validate basic static code security analysis.\n  black        Run black to check that Python files are consistently formatted.\n  flake8       Run flake8 code analysis.\n  pydocstyle   Run pydocstyle to validate docstring formatting adheres to standards.\n  pylint       Run pylint code static analysis.\n  tests        Run all linters and tests for this repository.\n```\n\nAfter making any code change, it is recommended to run `invoke tests` before committing your code.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglennmatthews%2Fmarkdown-version-annotations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglennmatthews%2Fmarkdown-version-annotations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglennmatthews%2Fmarkdown-version-annotations/lists"}