[Docutils-users] How to create and reference custom heading ids with reStructuredText?

[Ciro S. <cir...@gm...>]

Please CC.

Cross post:
https://stackoverflow.com/questions/48759542/how-to-create-and-reference-custom-heading-ids-with-restructuredtext

Currently, if I have:

    My header
    =========

    `My header`_

`rst2html` Docutils 0.14 produces:

    <div class="document" id="my-header">
    <h1 class="title">My header</h1>

    <p><a class="reference internal" href="#my-header">My header</a></p>

Is it possible to obtain the following ouptut instead:

    <h1 class="title" id="my-custom-header">My header</h1>

    <p><a class="reference internal" href="#my-custom-header">My
header</a></p>

So note how I want two changes:

- the id to be inside the heading, not on a separate div
- control over the actual id

The closest I could get was:

    <div class="document" id="my-header">
    <span id="my-custom-header"></span>
    <h1 class="title">My header</h1>

    <p><a class="reference external" href="my-custom-header">My
header</a></p>

but this is still not ideal, as I now have multiple ids floating around,
and not inside the `h1`.

Asciidoc for example has that covered with:

    [[my-custom-header]]
    == My header

    <<my-custom-header>>