changelog-slugs¶

changelog-slugs provides changelog-aware heading slugs for Python-Markdown’s toc extension.

It is designed for Keep a Changelog style changelogs in projects following Semantic Versioning, where repeated subsection headings like Added and Fixed would otherwise receive unstable, order-dependent anchors. As new releases are added above older ones, those anchors can change, causing existing permalinks to become obsolete. changelog-slugs instead scopes subsection slugs to their containing release, producing stable anchors such as v1-2-3-fixed.

Installation¶

pipuv

pip install changelog-slugs

uv add changelog-slugs

Usage¶

Pythonzensical.tomlmkdocs.yml

import markdown

from changelog_slugs import Slugifier

changelog = ...  # e.g., the contents of your changelog file

html = markdown.markdown(
    changelog,
    extensions=["toc"],
    extension_configs={
        "toc": {
            "slugify": Slugifier(),
        },
    },
)

[project.markdown_extensions.toc.slugify]
object = "changelog_slugs.Slugifier"

markdown_extensions:
  - toc:
      slugify: !!python/name:changelog_slugs.slugify