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 🙂

[multimeric]

I think a reasonable short term solution is just to allow custom slugifying functions without bothering with the two-pass system. For the typical use case, you won't have ID collisions, and the highest priority is just getting working internal hyperlinks.

[rafalkrupinski]

Same problem with astro, seems a common thing

[pawamoy]

I just published a new release which allows configuring griffe2md via a config file. Therefore it just got easier to add a config item for the slugify function, if someone wants to send a PR 🙂

[rafalkrupinski]

Could you do something with the CI pipelines? Feels like a red tape set purposefully to deter contributions, which is exactly the opposite vibe i got from you :)

The amount of changes you had to make in my PR to code I didn't touch isn't a good sign

[pawamoy]

Hmmm wrong issue @rafalkrupinski? Are you referring to #10? I maintain quite a lot of projects and don't always have the energy/bandwidth to be super disciplined about atomic changes / Git history 😕 Also the Python ecosystem moves fast, things break often, and I'm really not a fan of tracking lock files + setting up Renovate or similar, which I find extremely noisy. What changes would you like to see in the CI pipelines?