docutils-develop Mailing List for Docutils: Documentation Utilities

- **status**: open --> closed-fixed
- **Comment**:

Fine.
The updates are now also at https://docutils.sourceforge.io/docs/, so I'll close this issue.
Thanks again for reporting.



---

**[bugs:#518] id\_prefix removes footnote prefix from **

**Status:** closed-fixed
**Created:** Sun Mar 22, 2026 12:40 AM UTC by miketheman
**Last Updated:** Fri Apr 10, 2026 01:22 PM 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.

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



---

**[bugs:#518] id\_prefix removes footnote prefix from **

**Status:** open
**Created:** Sun Mar 22, 2026 12:40 AM UTC by miketheman
**Last Updated:** Sat Mar 28, 2026 08:10 PM 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.

I'd like to finalise/close this issue and apply the proposed API definition and backwards policy Commit	[r10309]  updated the proposal [EP 10](https://docutils.sourceforge.io/docs/eps/ep-010.html). Unless someone objects, I'd apply the attached patch in 4 weeks to ship with Docutils 0.23. After this, Docutils will switch "semantic versioning".


Attachments:

- [0001-Define-public-API-and-backwards-compatible-policy.patch](https://sourceforge.net/p/docutils/feature-requests/_discuss/thread/c3485acc56/a268/attachment/0001-Define-public-API-and-backwards-compatible-policy.patch) (10.2 kB; text/x-patch)


---

**[feature-requests:#89] Public API, versioning, and deprecation**

**Status:** open
**Group:** Default
**Created:** Sun Jan 16, 2022 01:39 AM UTC by Adam  Turner
**Last Updated:** Wed May 14, 2025 02:35 PM UTC
**Owner:** nobody


As requested by @milde in https://sourceforge.net/p/docutils/bugs/441/#7043/cdb8/8742/6e7f I'm opening this issue to allow for discussion on Docutils' public API, versioning policy, and deprecation.

[Enhancement proposal 10](https://docutils.sourceforge.io/docs/eps/ep-010.html) summarizes the discussion. It will be updated with new insights and decisions until a consensus is found.

This also relates to FR 87 on type annotations. 

From Günter, 

> The idea is to reconcile the reality (Docutils is used as if it were mature) and the version number (<1) once the API sufficiently defined a deprecation policy is agreed.

The only text I can find on library versioning is at https://docutils.sourceforge.io/docs/dev/policies.html#version-identification, excerpt below:

> **Major releases** (x.0, e.g. 1.0) will be rare, and will
represent major changes in API, functionality, or commitment.  The
major number will be bumped to 1 when the project is
feature-complete, and may be incremented later if there is a major
change in the design or API.  When Docutils reaches version 1.0,
the major APIs will be considered frozen.
For details, see the `backwards compatibility policy`_.

> Releases that change the minor number (x.y, e.g. 0.5) will be
**feature releases**; new features from the `Docutils core`_ will
be included.

> Releases that change the micro number (x.y.z, e.g. 0.4.1) will be
**bug-fix releases**.  No new features will be introduced in these
releases; only bug fixes will be included.

The proposed backwards compatability policy reads:

> Docutils' backwards compatibility policy follows the rules for Python in
PEP 387. ... The scope of the public API is laid out at the start of the backwards
  compatibility rules

I propose two modifications to the policies, which will make future changes to Docutils easier to review and reason about, for project members as well as outside contributors. 

Firstly, I propose adopting a formal versioning "system" such as Sematic Versioning ([SemVer](https://semver.org/)) or Calendar Versioning ([CalVer](https://calver.org/)). 

Semantic versioning is nearly identical to the current versioning policy, and has the benefit of being a known quantity, reducing misunderstandings. A potential phrasing would be:

**"Docutils follows SemVer. All changes must also follow the backwards compatability policy."**

What this does change is that the API is never considered complete, as in the original phrasing. Docutils [isn't slated for inclusion](https://www.python.org/dev/peps/pep-0258/#rejection-notice) in the standard library any more, and there will always be potential improvements and changes -- new parsers, new node types, changes in the HTML specification, et cetera. 

The 1.0 release then does not need to be a "big deal", and future breaking changes can go to 2.0, 3.0, etc -- setuptools is now on `60.5.0`!

Semantic versioning does have some drawbacks (https://snarky.ca/why-i-dont-like-semver/), so projects like pip have adopted calendar based versioning -- the major version is the year (22), and the minor version is either the current month or an increasing number.  This relies on strong documentation and changelogs, so that when users upgrade it is obvious what changed (the idea being that every change breaks someone, so there is no contract that version numbers within a certain range mean no breakage). Luckily, Docutils has a good culture around changelogs and histories etc, so this would be easy to adopt.

______


I also suggest enumerating all modules, classes, and functions that form the public API. The current backwards compatability policy references PEP 387, which is specifically for the Python project itself. Checking through the documentation on every change to identify if a name is public or private is error prone (we are all human, and can miss things with no malintent) and time consuming.

At the very least I would suggest, `docutils.nodes`, the reader/writer/parser aliases, `docutils.core`,  and the front end tools. (I'm happy to write out the full list if you give me modules/etc that should be part of the public API). It would also be useful to identify what parts of Docutils large downstream consumers use, and either create higher level abstractions or mark those as public API. (I would suggest Sphinx and MyST-parser). 

It is also the [established practice](https://www.python.org/dev/peps/pep-0008/#descriptive-naming-styles) to mark names as private by prefixing them with an underscore. I suggest adopting this, as it gives strong guidance to downstream library authors what Docutils considers private and public. Making a private name public is far easier than going through a deprecation cycle for the reverse.

I'd suggest adding the ability to have exceptions to the policy, with removal after one minor version. My full suggested text is:

**"Removal or significant alteration of any members of the public API will only take place after the behaviour has been marked as deprecated for two minor releases. Certain changes may have a shorter deprecation period of one minor release. This requires at least two project members to be in favour of doing so, and no members against.**

**Changes that may affect end-users (e.g. by requiring changes to the configuration file or potentially breaking custom style sheets) should be announced with a FutureWarning."**

This post is intentionally opinionated so as to provide something to talk over / edit -- I'm not massively attached to any one thing!

A

----
for reference, amongst others, I took inspiration from:
https://setuptools.pypa.io/en/latest/development/releases.html
https://pip.pypa.io/en/latest/development/release-process/
https://numpy.org/neps/nep-0023-backwards-compatibility.html



---

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

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

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.

Applied in [r10294]. 
Thank you for the patch.


---

**[patches:#216] Fix type annotation for get_default_settings**

**Status:** open-accepted
**Group:** None
**Created:** Thu Jan 22, 2026 09:04 AM UTC by Dmitry Shachnev
**Last Updated:** Sun Jan 25, 2026 02:15 PM UTC
**Owner:** nobody
**Attachments:**

- [0001-Fix-type-annotation-for-get_default_settings.patch](https://sourceforge.net/p/docutils/patches/216/attachment/0001-Fix-type-annotation-for-get_default_settings.patch) (966 Bytes; text/x-patch)


It accepts classes themselves, not instances of those classes.

This fixes error from mypy that I have for code that calls `get_default_settings(Writer)`.
```
error: Argument 1 to "get_default_settings" has incompatible type "type[Writer]"; expected "SettingsSpec"  [arg-type]
```


---

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

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

- **status**: open --> open-accepted
- **Comment**:

Applied in [r10294]. 
Thank you for the patch.



---

**[patches:#216] Fix type annotation for get_default_settings**

**Status:** open-accepted
**Group:** None
**Created:** Thu Jan 22, 2026 09:04 AM UTC by Dmitry Shachnev
**Last Updated:** Thu Jan 22, 2026 09:04 AM UTC
**Owner:** nobody
**Attachments:**

- [0001-Fix-type-annotation-for-get_default_settings.patch](https://sourceforge.net/p/docutils/patches/216/attachment/0001-Fix-type-annotation-for-get_default_settings.patch) (966 Bytes; text/x-patch)


It accepts classes themselves, not instances of those classes.

This fixes error from mypy that I have for code that calls `get_default_settings(Writer)`.
```
error: Argument 1 to "get_default_settings" has incompatible type "type[Writer]"; expected "SettingsSpec"  [arg-type]
```


---

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

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

---

**[patches:#216] Fix type annotation for get_default_settings**

**Status:** open
**Group:** None
**Created:** Thu Jan 22, 2026 09:04 AM UTC by Dmitry Shachnev
**Last Updated:** Thu Jan 22, 2026 09:04 AM UTC
**Owner:** nobody
**Attachments:**

- [0001-Fix-type-annotation-for-get_default_settings.patch](https://sourceforge.net/p/docutils/patches/216/attachment/0001-Fix-type-annotation-for-get_default_settings.patch) (966 Bytes; text/x-patch)


It accepts classes themselves, not instances of those classes.

This fixes error from mypy that I have for code that calls `get_default_settings(Writer)`.
```
error: Argument 1 to "get_default_settings" has incompatible type "type[Writer]"; expected "SettingsSpec"  [arg-type]
```


---

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

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

Karl has a point, that it is apache specfifc

but
for pages served by apache ... this is a betterment

all the best

On Mon, 12 Jan 2026 at 01:07, Karl O. Pinc <ko...@ka...> wrote:
>
> On Sun, 11 Jan 2026 20:53:55 -0000 (UTC)
> Guenter Milde via Docutils-develop
> <doc...@li...> wrote:
>
> > Bug report #516 by Ulrich Müller notices that the "View document
> > source" links are served with the "personal" MIME type
> > "text/prs.fallenstein.rst"
> >
> > The following patch is intended to override this with the "unoffical
> > official" unregistered MIME type "text/x-rst":
> >
> > --- .htaccess (Revision 10160)
> > +++ .htaccess (Arbeitskopie)
> > @@ -1,5 +1,12 @@
> > +# Enable directory index listings
> > +# ===============================
> >  Options Indexes
> >
> > +# MIME types
> > +# ==========
> > +# use "text/x-rst" instead of the personal/vanity entry
> > "text.prs.fallenstein.rst" +AddType text/x-rst .rst
> > +
> >  # Redirects
> >  # =========
> >
> > Would this be a good idea?
>
> I'm going to comment, even though abundently ignorant.
>
> Anything involving .htaccess is voodoo, and apache-specific
> action-at-a-distance voodoo at that.  When doing web-related
> sysadmin work I try to stay far away from .htaccess files.
>
> Please ignore this comment if you do not find it useful.
>
> Regards,
>
> Karl <ko...@ka...>
> Free Software:  "You don't pay back, you pay forward."
>                  -- Robert A. Heinlein
>
>
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.

On Sun, 11 Jan 2026 20:53:55 -0000 (UTC)
Guenter Milde via Docutils-develop
<doc...@li...> wrote:

> Bug report #516 by Ulrich Müller notices that the "View document
> source" links are served with the "personal" MIME type
> "text/prs.fallenstein.rst"
> 
> The following patch is intended to override this with the "unoffical
> official" unregistered MIME type "text/x-rst":
> 
> --- .htaccess	(Revision 10160)
> +++ .htaccess	(Arbeitskopie)
> @@ -1,5 +1,12 @@
> +# Enable directory index listings
> +# ===============================
>  Options Indexes
>  
> +# MIME types
> +# ==========
> +# use "text/x-rst" instead of the personal/vanity entry
> "text.prs.fallenstein.rst" +AddType text/x-rst .rst
> +
>  # Redirects
>  # =========
>  
> Would this be a good idea?

I'm going to comment, even though abundently ignorant.

Anything involving .htaccess is voodoo, and apache-specific
action-at-a-distance voodoo at that.  When doing web-related
sysadmin work I try to stay far away from .htaccess files.

Please ignore this comment if you do not find it useful.

Regards,

Karl <ko...@ka...>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein

Dear Docutils developers,

Bug report #516 by Ulrich Müller notices that the "View document source"
links are served with the "personal" MIME type "text/prs.fallenstein.rst"

The following patch is intended to override this with the "unoffical
official" unregistered MIME type "text/x-rst":

--- .htaccess	(Revision 10160)
+++ .htaccess	(Arbeitskopie)
@@ -1,5 +1,12 @@
+# Enable directory index listings
+# ===============================
 Options Indexes
 
+# MIME types
+# ==========
+# use "text/x-rst" instead of the personal/vanity entry "text.prs.fallenstein.rst"
+AddType text/x-rst .rst
+
 # Redirects
 # =========
 
Would this be a good idea?

Günter

 

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


---

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

**Status:** open
**Created:** Mon Dec 15, 2025 07:26 AM UTC by Ulrich Müller
**Last Updated:** Fri Jan 09, 2026 05:40 PM UTC
**Owner:** nobody


The Docutils FAQ says in section 2.24 https://docutils.sourceforge.io/FAQ.html#what-s-the-official-mime-type-for-restructuredtext-data:

> [...] the "official unofficial" standard MIME type is "text/x-rst".

However, when following the "View document source" at the bottom of the page, I get a different MIME type:
~~~
$ curl -I https://docutils.sourceforge.io/FAQ.rst
HTTP/2 200 
date: Mon, 15 Dec 2025 07:20:49 GMT
content-type: text/prs.fallenstein.rst
[...]
~~~
Clearly, this is not what the FAQ says.



---

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.

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)


---

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

**Status:** open
**Created:** Mon Dec 15, 2025 07:26 AM UTC by Ulrich Müller
**Last Updated:** Mon Dec 15, 2025 10:23 AM UTC
**Owner:** nobody


The Docutils FAQ says in section 2.24 https://docutils.sourceforge.io/FAQ.html#what-s-the-official-mime-type-for-restructuredtext-data:

> [...] the "official unofficial" standard MIME type is "text/x-rst".

However, when following the "View document source" at the bottom of the page, I get a different MIME type:
~~~
$ curl -I https://docutils.sourceforge.io/FAQ.rst
HTTP/2 200 
date: Mon, 15 Dec 2025 07:20:49 GMT
content-type: text/prs.fallenstein.rst
[...]
~~~
Clearly, this is not what the FAQ says.



---

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.

Line numbers are still wrong in the nested parsing of cell content in "CSV tables".
Generally, the line numbers are only intended for ease of debugging and should not be relied upon too heavily.


---

**[bugs:#517] content_offset in directives inside grid/simple tables are off**

**Status:** open-fixed
**Created:** Sat Dec 27, 2025 05:07 PM UTC by Felix Fontein
**Last Updated:** Wed Jan 07, 2026 01:13 PM UTC
**Owner:** nobody


When parsing a directive in a grid table or simple table, the directive's `content_offset` is off by one. (When nesting such a table in another such a table, it's off by one for every nesting level.)

For example, for the following code block directives, `content_offset` is always off from the real content line where the code block's content is in:

```rst
content_offset is off by 1:

+----------------------+
| .. code-block:: yaml |
|                      |
|    - foo             |
+----------------------+

content_offset is off by 2:

+------------------------+
|+----------------------+|
|| .. code-block:: yaml ||
||                      ||
||    - foo             ||
|+----------------------+|
+------------------------+

content_offset is off by 3:

+--------------------------+
|+------------------------+|
||+----------------------+||
||| .. code-block:: yaml |||
|||                      |||
|||    - foo             |||
||+----------------------+||
|+------------------------+|
+--------------------------+

content_offset is off by 1:

=====  =====
col 1  col 2
=====  =====
1      .. code-block:: yaml

          - foo
=====  =====

content_offset is off by 2:

=====  =====
col 1  col 2
=====  =====
1      =====  =====
       col 1  col 2
       =====  =====
       1      .. code-block:: yaml

                 - foo
       =====  =====
=====  =====
```

(I've noticed this when registering an own code block directive to find the actual location - row and column - of the code block's contents, to be able to give more precise error messages when linting.)


---

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.

- **status**: open --> open-fixed
- **Comment**:

The fix is out.
Sorry for the confusion: I intended to publish 2 commits with one `git svn dcommit`
but only the first came through.



---

**[bugs:#517] content_offset in directives inside grid/simple tables are off**

**Status:** open-fixed
**Created:** Sat Dec 27, 2025 05:07 PM UTC by Felix Fontein
**Last Updated:** Tue Jan 06, 2026 08:59 PM UTC
**Owner:** nobody


When parsing a directive in a grid table or simple table, the directive's `content_offset` is off by one. (When nesting such a table in another such a table, it's off by one for every nesting level.)

For example, for the following code block directives, `content_offset` is always off from the real content line where the code block's content is in:

```rst
content_offset is off by 1:

+----------------------+
| .. code-block:: yaml |
|                      |
|    - foo             |
+----------------------+

content_offset is off by 2:

+------------------------+
|+----------------------+|
|| .. code-block:: yaml ||
||                      ||
||    - foo             ||
|+----------------------+|
+------------------------+

content_offset is off by 3:

+--------------------------+
|+------------------------+|
||+----------------------+||
||| .. code-block:: yaml |||
|||                      |||
|||    - foo             |||
||+----------------------+||
|+------------------------+|
+--------------------------+

content_offset is off by 1:

=====  =====
col 1  col 2
=====  =====
1      .. code-block:: yaml

          - foo
=====  =====

content_offset is off by 2:

=====  =====
col 1  col 2
=====  =====
1      =====  =====
       col 1  col 2
       =====  =====
       1      .. code-block:: yaml

                 - foo
       =====  =====
=====  =====
```

(I've noticed this when registering an own code block directive to find the actual location - row and column - of the code block's contents, to be able to give more precise error messages when linting.)


---

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.

- **status**: open-fixed --> open



---

**[bugs:#517] content_offset in directives inside grid/simple tables are off**

**Status:** open
**Created:** Sat Dec 27, 2025 05:07 PM UTC by Felix Fontein
**Last Updated:** Tue Jan 06, 2026 05:35 PM UTC
**Owner:** nobody


When parsing a directive in a grid table or simple table, the directive's `content_offset` is off by one. (When nesting such a table in another such a table, it's off by one for every nesting level.)

For example, for the following code block directives, `content_offset` is always off from the real content line where the code block's content is in:

```rst
content_offset is off by 1:

+----------------------+
| .. code-block:: yaml |
|                      |
|    - foo             |
+----------------------+

content_offset is off by 2:

+------------------------+
|+----------------------+|
|| .. code-block:: yaml ||
||                      ||
||    - foo             ||
|+----------------------+|
+------------------------+

content_offset is off by 3:

+--------------------------+
|+------------------------+|
||+----------------------+||
||| .. code-block:: yaml |||
|||                      |||
|||    - foo             |||
||+----------------------+||
|+------------------------+|
+--------------------------+

content_offset is off by 1:

=====  =====
col 1  col 2
=====  =====
1      .. code-block:: yaml

          - foo
=====  =====

content_offset is off by 2:

=====  =====
col 1  col 2
=====  =====
1      =====  =====
       col 1  col 2
       =====  =====
       1      .. code-block:: yaml

                 - foo
       =====  =====
=====  =====
```

(I've noticed this when registering an own code block directive to find the actual location - row and column - of the code block's contents, to be able to give more precise error messages when linting.)


---

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.

- **status**: open --> open-fixed



---

**[bugs:#517] content_offset in directives inside grid/simple tables are off**

**Status:** open-fixed
**Created:** Sat Dec 27, 2025 05:07 PM UTC by Felix Fontein
**Last Updated:** Tue Jan 06, 2026 05:35 PM UTC
**Owner:** nobody


When parsing a directive in a grid table or simple table, the directive's `content_offset` is off by one. (When nesting such a table in another such a table, it's off by one for every nesting level.)

For example, for the following code block directives, `content_offset` is always off from the real content line where the code block's content is in:

```rst
content_offset is off by 1:

+----------------------+
| .. code-block:: yaml |
|                      |
|    - foo             |
+----------------------+

content_offset is off by 2:

+------------------------+
|+----------------------+|
|| .. code-block:: yaml ||
||                      ||
||    - foo             ||
|+----------------------+|
+------------------------+

content_offset is off by 3:

+--------------------------+
|+------------------------+|
||+----------------------+||
||| .. code-block:: yaml |||
|||                      |||
|||    - foo             |||
||+----------------------+||
|+------------------------+|
+--------------------------+

content_offset is off by 1:

=====  =====
col 1  col 2
=====  =====
1      .. code-block:: yaml

          - foo
=====  =====

content_offset is off by 2:

=====  =====
col 1  col 2
=====  =====
1      =====  =====
       col 1  col 2
       =====  =====
       1      .. code-block:: yaml

                 - foo
       =====  =====
=====  =====
```

(I've noticed this when registering an own code block directive to find the actual location - row and column - of the code block's contents, to be able to give more precise error messages when linting.)


---

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.

Thanks for the test script.  The attached variant was used to explore the problem and find the
spot that needs to be changed.
Commit [r10279] fixes the problem (and also wrong line numbers in some system messages for markup errors inside table cells.


Attachments:

- [directive-in-table.py](https://sourceforge.net/p/docutils/bugs/_discuss/thread/450678dd49/a008/attachment/directive-in-table.py) (3.0 kB; text/x-python)


---

**[bugs:#517] content_offset in directives inside grid/simple tables are off**

**Status:** open
**Created:** Sat Dec 27, 2025 05:07 PM UTC by Felix Fontein
**Last Updated:** Thu Jan 01, 2026 08:42 PM UTC
**Owner:** nobody


When parsing a directive in a grid table or simple table, the directive's `content_offset` is off by one. (When nesting such a table in another such a table, it's off by one for every nesting level.)

For example, for the following code block directives, `content_offset` is always off from the real content line where the code block's content is in:

```rst
content_offset is off by 1:

+----------------------+
| .. code-block:: yaml |
|                      |
|    - foo             |
+----------------------+

content_offset is off by 2:

+------------------------+
|+----------------------+|
|| .. code-block:: yaml ||
||                      ||
||    - foo             ||
|+----------------------+|
+------------------------+

content_offset is off by 3:

+--------------------------+
|+------------------------+|
||+----------------------+||
||| .. code-block:: yaml |||
|||                      |||
|||    - foo             |||
||+----------------------+||
|+------------------------+|
+--------------------------+

content_offset is off by 1:

=====  =====
col 1  col 2
=====  =====
1      .. code-block:: yaml

          - foo
=====  =====

content_offset is off by 2:

=====  =====
col 1  col 2
=====  =====
1      =====  =====
       col 1  col 2
       =====  =====
       1      .. code-block:: yaml

                 - foo
       =====  =====
=====  =====
```

(I've noticed this when registering an own code block directive to find the actual location - row and column - of the code block's contents, to be able to give more precise error messages when linting.)


---

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.

Thank you for the report.
Could you attach your test-directive, so that I can experiment and try a fix?


---

**[bugs:#517] content_offset in directives inside grid/simple tables are off**

**Status:** open
**Created:** Sat Dec 27, 2025 05:07 PM UTC by Felix Fontein
**Last Updated:** Sat Dec 27, 2025 05:07 PM UTC
**Owner:** nobody


When parsing a directive in a grid table or simple table, the directive's `content_offset` is off by one. (When nesting such a table in another such a table, it's off by one for every nesting level.)

For example, for the following code block directives, `content_offset` is always off from the real content line where the code block's content is in:

```rst
content_offset is off by 1:

+----------------------+
| .. code-block:: yaml |
|                      |
|    - foo             |
+----------------------+

content_offset is off by 2:

+------------------------+
|+----------------------+|
|| .. code-block:: yaml ||
||                      ||
||    - foo             ||
|+----------------------+|
+------------------------+

content_offset is off by 3:

+--------------------------+
|+------------------------+|
||+----------------------+||
||| .. code-block:: yaml |||
|||                      |||
|||    - foo             |||
||+----------------------+||
|+------------------------+|
+--------------------------+

content_offset is off by 1:

=====  =====
col 1  col 2
=====  =====
1      .. code-block:: yaml

          - foo
=====  =====

content_offset is off by 2:

=====  =====
col 1  col 2
=====  =====
1      =====  =====
       col 1  col 2
       =====  =====
       1      .. code-block:: yaml

                 - foo
       =====  =====
=====  =====
```

(I've noticed this when registering an own code block directive to find the actual location - row and column - of the code block's contents, to be able to give more precise error messages when linting.)


---

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.

- **status**: open-fixed --> closed-fixed
- **Comment**:

Fixed in Docutils 0.22.4.
Thank you for analysis and report.



---

**[bugs:#514] publish_file no longer works with "BytesIO-like" objects.**

**Status:** closed-fixed
**Created:** Sat Nov 15, 2025 05:26 PM UTC by Kristian Lehto
**Last Updated:** Mon Dec 01, 2025 11:14 PM UTC
**Owner:** nobody


Hello,

We are using code bellow to convert rst files to html.

Code works fine if we use old docutils version 0.20.1.

python -m pip install docutils==0.20.1

But current 0.22.3 version crashes.

import io
from docutils.core import publish_file

text = open('test.rst', 'rb').read()
source = io.BytesIO(text)
destination = open('test.html', 'w')
publish_file(source=source, destination=destination, writer_name='html')
destination.close()
source.close()

Traceback (most recent call last):
  File "C:\projects\test\test.py", line 7, in <module>
    publish_file(source=source, destination=destination, writer_name='html')
    ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Python314\Lib\site-packages\docutils\core.py", line 465, in publish_file
    output, _publisher = publish_programmatically(
                         ~~~~~~~~~~~~~~~~~~~~~~~~^
        source_class=io.FileInput, source=source, source_path=source_path,
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ...<7 lines>...
        config_section=config_section,
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        enable_exit_status=enable_exit_status)
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Python314\Lib\site-packages\docutils\core.py", line 794, in publish_programmatically
    output = publisher.publish(enable_exit_status=enable_exit_status)
  File "C:\Python314\Lib\site-packages\docutils\core.py", line 269, in publish
    self.document = self.reader.read(self.source, self.parser,
                    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
                                     self.settings)
                                     ^^^^^^^^^^^^^^
  File "C:\Python314\Lib\site-packages\docutils\readers\__init__.py", line 95, in read
    self.parse()
    ~~~~~~~~~~^^
  File "C:\Python314\Lib\site-packages\docutils\readers\__init__.py", line 101, in parse
    self.parser.parse(self.input, document)
    ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Python314\Lib\site-packages\docutils\parsers\rst\__init__.py", line 175, in parse
    inputlines = docutils.statemachine.string2lines(
          inputstring, tab_width=document.settings.tab_width,
          convert_whitespace=True)
  File "C:\Python314\Lib\site-packages\docutils\statemachine.py", line 1515, in string2lines
    astring = whitespace.sub(' ', astring)
TypeError: cannot use a string pattern on a bytes-like object


---

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.

Hei everybody,

another quick release, docutils 0.22.4 containing

reStructuredText Specification:
  - Clarify indentation rules: minimal indentation is *one* space.
  - Clarify comment syntax: Comments begin with two dots and *whitespace*.

HTML writers:
  - New value "auto" for the initial_header_level_ setting.
  - Bugfixes in the provisional style-sheet "responsive.css".

see https://docutils.sourceforge.io/HISTORY.html for details

thanks to Günter for his work

all the best
 e

hei

if no stopper shows up
i will release 0.22.4 tomorrow dec 18 around 7pm CET

all the best
 e

Dear Docutils developers,

On 2025-12-04, Guenter Milde via Docutils-develop wrote:

> My ideas for the next steps are

> * wait for 2, ..., 4 weeks to see whether there are bug reports that can be
>   fixed in a 0.22.4 "micro release".

We got one bug report that is fixed in the repository and 
one (https://sourceforge.net/p/docutils/bugs/516/) concerning the "x-rst"
MIME type, not the Docutils code.


Release 0.22.4 is ready to be released anytime soon (today?).

Günter    

Suggestion:

Introduce a new Doctree element `<line_break>` in Docutils 1.0

* add "br" to docutils.dtd and document it in https://docutils.sourceforge.io/docs/ref/doctree.html
* add new class `docutils.nodes.line_break`
* add `visit_line_break()` and `depart_line_break()` methods to Docutils writers.

New [standard directive](https://docutils.sourceforge.io/docs/ref/rst/directives.html) `line-break`. Similar to "replace", "date", and "unicode", this directive may only be used  in substitution definitions, e.g.
~~~
.. |br| .. line-break::

I want a line break\ |br|
before this text.
~~~
@aa-turner what do you think?


---

**[feature-requests:#101] New "doctree" element for hard line breaks.**

**Status:** pending-moreinfo
**Group:** Default
**Created:** Tue Dec 12, 2023 08:16 PM UTC by Günter Milde
**Last Updated:** Mon Apr 28, 2025 08:21 PM UTC
**Owner:** nobody


Not providing for "hard line break elements" in the Docutils document model and reStructuredText syntax was a deliberate decision at the time these two were devised.

However, times have changed and there are new arguments and use-cases for hard line breaks.
(cf.  the  [comments in #85](https://sourceforge.net/p/docutils/feature-requests/85/#d02b)).
Something like a `<br>` inline node or special handling of `<inline class=line-break>` inline nodes may be considered. The latter would not change the document model and could be implemented at the writer level or via stylesheet rules.

Whether to add a reStructuredText syntax for hard line breaks can be decided independently.
The current rules require a non-white character in a role defined with `.. role:: line-break`.
    



---

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

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

Thank you for the information.
According to the IANA entry, Benja Fallenstein  registered the "rst" MIME type because:
> The registrant just happened to have need of a registered media type for it.
--- https://www.iana.org/assignments/media-types/text/prs.fallenstein.rst

So the actual error is not the quoted part of the FAQ answer, but
> ... there is no registered MIME type for reStructuredText, ....

It seems that with the switch of the source file extending from ".txt" to ".rst" in August 2024 some applications started to use the registered MIME type when serving or analysing the source files.


---

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

**Status:** open
**Created:** Mon Dec 15, 2025 07:26 AM UTC by Ulrich Müller
**Last Updated:** Mon Dec 15, 2025 07:26 AM UTC
**Owner:** nobody


The Docutils FAQ says in section 2.24 https://docutils.sourceforge.io/FAQ.html#what-s-the-official-mime-type-for-restructuredtext-data:

> [...] the "official unofficial" standard MIME type is "text/x-rst".

However, when following the "View document source" at the bottom of the page, I get a different MIME type:
~~~
$ curl -I https://docutils.sourceforge.io/FAQ.rst
HTTP/2 200 
date: Mon, 15 Dec 2025 07:20:49 GMT
content-type: text/prs.fallenstein.rst
[...]
~~~
Clearly, this is not what the FAQ says.



---

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.

- **status**: open --> closed-fixed
- **Comment**:

Fixed in [r10271].



---

**[bugs:#515] Wrong statement in "reStructuredText Specification"**

**Status:** closed-fixed
**Labels:** Documentation 
**Created:** Tue Dec 02, 2025 10:45 AM UTC by Günter Milde
**Last Updated:** Tue Dec 02, 2025 10:48 AM UTC
**Owner:** nobody


The rST specification states in one example that
"A footnote contains body elements, consistently indented by at least 3 spaces."
The minimal indentation in rST is one space.


---

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.