#518 id_prefix removes footnote prefix from

[miketheman]

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:

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:

--- 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!

[Günter Milde]

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. 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.