bug: Header link IDs are wrong

[jayqi]

Description of the bug

The automatically generated internal header link IDs don't match what common markdown processors (e.g., GitHub, GitLab) produce. In particular, markdown processors strip punctuation like periods, which griffe2md currently keeps.

Here is the relevant documentation about how header link IDs are generated:

• GitHub docs
• GitLab docs

(They seem use roughly the same logic.)

To Reproduce

griffe2md is producing this functions list:

**Functions:**

- [**format_version**](#vspect.format_version) – Format a version using a format string.
- [**get_package_version**](#vspect.get_package_version) – Get the version of a package.
- [**read_version_from_pyproject_toml**](#vspect.read_version_from_pyproject_toml) – Read the version from a pyproject.toml file. Requires the version to be statically defined.

Full output

Expected behavior

However, these are the actual header link IDs that GitHub creates:

• #vspectformat_version
• #vspectget_package_version
• #vspectread_version_from_pyproject_toml

Environment information

• System: macOS-14.7.2-x86_64-i386-64bit-Mach-O
• Python: cpython 3.13.0 (/Users/jqi/vspect/.venv/bin/python3)
• Environment variables:
• Installed packages:
  • griffe2md v1.1.0

[pawamoy]

Thanks for the reports @jayqi!

The issue with slugified ids/anchors is that they lose information and create collisions. Consider these two ids, corresponding to two distinct Python objects: package.namespace.function and package.NamespaceFunction. They both get slugified to packagenamespacefunction according to what you describe. When rendered on GitHub, the second one will be suffixed with _1. Next ones, if any, will continue being incremented.

To support that in griffe2md, we will have to keep track, in order, of which id was slugified to which (incremented) anchor. Then we'll have to use this map to fix links with a regular expression. This means we'll have to proceed in two steps, like in mkdocstrings(-python), by first rendering temporary "autoref" elements (or similar), and later fixing them.

Since griffe2md does not target GitHub specifically, we'll also have to support choosing a slugify function.

For these reasons, I'll mark this as a feature request rather than a bug 🙂