Recent changes to bugs

#518 id_prefix removes footnote prefix from

Günter Milde — Fri, 17 Apr 2026 08:48:40 -0000

status: open --> closed-fixed

#518 id_prefix removes footnote prefix from

miketheman — Fri, 10 Apr 2026 13:22:06 -0000

I think those changes make it clearer, thanks!

#518 id_prefix removes footnote prefix from

Günter Milde — Fri, 10 Apr 2026 07:43:14 -0000

Is there something to change in SF classification to make this a documentation issue vs bug?

Classing the report as bug report is IMO correct, defining the problem as a documentation issue should help to address it.

Would the changes in [r10310] and [10311] have prevented the "wrong feeling"?
(It will take some time to get them into the published documentation at https://docutils.sourceforge.io/docs/.)

#518 id_prefix removes footnote prefix from

miketheman — Sat, 28 Mar 2026 20:10:32 -0000

Thanks for looking into it. It felt wrong enough to raise it here.

Is there something to change in SF classification to make this a documentation issue vs bug?

#518 id_prefix removes footnote prefix from

Günter Milde — Tue, 24 Mar 2026 17:23:00 -0000

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.

id_prefix removes footnote prefix from

miketheman — Sun, 22 Mar 2026 00:40:03 -0000

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!

id_prefix removes footnote prefix from

miketheman — Sun, 22 Mar 2026 00:40:03 -0000

Ticket 518 has been modified: id_prefix removes footnote prefix from
Edited By: Günter Milde (milde)
Status updated: 'open' => 'closed-fixed'

#516 FAQ says MIME type for rst is text/x-rst but its source page is served as text/prs.fallenstein.rst

Günter Milde — Sun, 11 Jan 2026 19:54:47 -0000

Commit [r10290] updates the FAQ answer to document the 3rd party entry "text/prs.fallenstein.rst"

#516 FAQ says MIME type for rst is text/x-rst but its source page is served as text/prs.fallenstein.rst

Günter Milde — Fri, 09 Jan 2026 17:40:56 -0000

The author/change controller writes in the registration:

If anybody more intimately involved with ReStructuredText
wants to take it over, it will be surrendered gladly.

We may consider taking over as "change controller" and

keep the name as text/prs.fallenstein.rst
(never touch a running system),
change the name to text/prs.docutils.rst
(simple registration in the Personal Registration Tree), or
try to register as text/rst
(official registry, requires publication of an RFC)

#517 content_offset in directives inside grid/simple tables are off

Felix Fontein — Wed, 07 Jan 2026 20:23:31 -0000

Thanks for fixing this, I can confirm that with the latest commit it works fine (except tables lists, as you mentioned - but these are not very common, at least the ones with code blocks in them :) )!

I'm using the line numbers to try to identify the exact position of the code block (including its column offset), mainly for two use-cases:
1. Being able to show more precise error locations when linting code in code blocks;
2. To be able to replace code block content's with output (extracted from running the code in other code blocks or somewhere else) to make sure that the output shown in documentation is correct. (Obviously this only works if the exact position can be located and replacing the content is easy, which is usually the case for code blocks in list tables or outside of tables.)

If you're interested in it, the location code is here: https://github.com/felixfontein/antsibull-docutils/blob/main/src/antsibull_docutils/rst_code_finder.py (it's a bit more involved than the example code for this issue).
A use (of that code) for calling yamllint in code blocks is here: https://github.com/ansible/ansible-documentation/blob/devel/tests/checkers/rst-yamllint.py
And another use of that code for replacing code block contents is here: https://github.com/ansible-community/antsibull-docs/tree/main/src/antsibull_docs/ansible_output (documentation with examples: https://docs.ansible.com/projects/antsibull-docs/ansible-output/)