Metadata-Version: 2.4
Name: changelog-slugs
Version: 0.2.0
Summary: Changelog-aware heading slugs for Python-Markdown’s toc extension
Keywords: changelog,keep-a-changelog,markdown,anchors,slugify
Author: Johann Philipp Gorzny
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Dist: markdown>=3.4.2
Requires-Python: >=3.11
Project-URL: Homepage, https://jo-phil.github.io/changelog-slugs/
Project-URL: Repository, https://github.com/jo-phil/changelog-slugs
Project-URL: Issues, https://github.com/jo-phil/changelog-slugs/issues
Project-URL: Changelog, https://jo-phil.github.io/changelog-slugs/changelog/
Description-Content-Type: text/markdown

# changelog-slugs

[![CI](https://github.com/jo-phil/changelog-slugs/actions/workflows/ci.yml/badge.svg)](https://github.com/jo-phil/changelog-slugs/actions/workflows/ci.yml "View workflow runs")
[![PyPI - Version](https://img.shields.io/pypi/v/changelog-slugs)](https://pypi.org/project/changelog-slugs/ "View latest release on PyPI")
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/changelog-slugs)](https://pypi.org/project/changelog-slugs/ "View supported Python versions on PyPI")
[![Docs](https://github.com/jo-phil/changelog-slugs/actions/workflows/docs.yml/badge.svg)](https://jo-phil.github.io/changelog-slugs/ "Read the documentation")

[//]: # (--8<-- [start:opener])

`changelog-slugs` provides changelog-aware heading slugs for
[Python-Markdown](https://python-markdown.github.io/)’s
[`toc` extension](https://python-markdown.github.io/extensions/toc/).

It is designed for [Keep a Changelog](https://keepachangelog.com) style
changelogs in projects following [Semantic Versioning](https://semver.org),
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`.

[//]: # (--8<-- [end:opener])

## Installation

```bash
pip install changelog-slugs
```

## Usage

**Python**

```python
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(),
        },
    },
)
```

**zensical.toml**

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

**mkdocs.yml**

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

## License

This project is licensed under the terms of the MIT license.
