[Docutils-develop] [docutils:bugs] #518 id_prefix removes footnote prefix from

[Günter M. <mi...@us...>]

Thank you for the report.
I'd classify the problem as a documentation issue rather than a bug.

The problem is the difference between an *reference name* and an *identifier* .
Identifiers are derived from reference names via the [identifier normalization](https://docutils.sourceforge.io/docs/ref/rst/directives.html#identifier-normalization). Due to identifier restriction in HTML4, a reference name consisting of only digits "vanishes completely" unless prefixed. (cf. https://sourceforge.net/p/docutils/feature-requests/66/).

This is why the reference-name "5" is replaced by the auto-generated ID "footnote-1" (with 1 just be a running number to disambiguate all "footnote" IDs). A similar problem happens to, e.g. section headings consiting of just a date.
However, prefixing the ID with "user-content" allows the "1" to be appended.

You may play with the attached test script.


Attachments:

- [ids.py](https://sourceforge.net/p/docutils/bugs/_discuss/thread/8a618f0801/b4e5/attachment/ids.py) (832 Bytes; text/x-python)


---

**[bugs:#518] id_prefix removes footnote prefix from **

**Status:** open
**Created:** Sun Mar 22, 2026 12:40 AM UTC by miketheman
**Last Updated:** Sun Mar 22, 2026 12:40 AM UTC
**Owner:** nobody


I was recently working on adding an `id_prefix` string to enable the behavior as described in https://docutils.sourceforge.io/docs/user/config.html#id-prefix

It works pretty consistently, however when I came across a footnote, it removed the `footnote-` prefix from the rendered ID, but not the associated `href` value, leaving the rendered links a little more confusing than before.

Here's a reproduction example:

```python
import sys
from difflib import unified_diff

from docutils.core import publish_parts


INPUT_RST_WITH_FOOTNOTES = """
Footnote reference, like [5]_.

Some Text

.. [5] A numerical footnote.
"""


def render_body(rst: str, settings: dict) -> str:
    return publish_parts(rst, writer="html5", settings_overrides=settings)["body"]


settings = {"output_encoding": "unicode"}
basic = render_body(INPUT_RST_WITH_FOOTNOTES, settings)

settings["id_prefix"] = "user-content-"
prefixed = render_body(INPUT_RST_WITH_FOOTNOTES, settings)

sys.stdout.writelines(
    unified_diff(
        basic.splitlines(keepends=True),
        prefixed.splitlines(keepends=True),
        fromfile="basic.html",
        tofile="prefixed.html",
    )
)
```

Output with Docutils 0.22.4:

    :::udiff
    --- basic.html
    +++ prefixed.html
    @@ -1,8 +1,8 @@
    -<p>Footnote reference, like <a class="brackets" href="#footnote-1" id="footnote-reference-1" role="doc-noteref"><span class="fn-bracket">[</span>5<span class="fn-bracket">]</span></a>.</p>
    +<p>Footnote reference, like <a class="brackets" href="#user-content-5" id="user-content-footnote-reference-1" role="doc-noteref"><span class="fn-bracket">[</span>5<span class="fn-bracket">]</span></a>.</p>
     <p>Some Text</p>
    <aside class="footnote-list brackets">
    -<aside class="footnote brackets" id="footnote-1" role="doc-footnote">
    -<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#footnote-reference-1">5</a><span class="fn-bracket">]</span></span>
    +<aside class="footnote brackets" id="user-content-5" role="doc-footnote">
    +<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#user-content-footnote-reference-1">5</a><span class="fn-bracket">]</span></span>
    <p>A numerical footnote.</p>
    </aside>
    </aside>

The things that are different:

- the footnote reference changes from `1` to `5` - which is more accurate than before - yay!
- the footnote id/href value loses it's `footnote-` prefix in the reference part, the backlinks have the prefix + `footnote-`

Both link and backlink work, it's more about the inconsistent naming of the `id` and associated `href` values, and ther output behavior not matching the expectation from the documentation.

Hope this makes sense!


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.