Re: How to create and reference custom heading ids with reStructuredText?

On 2018-02-14, Ciro Santilli wrote:

> Please CC.

This doesn't work with slrn via GMANE, sorry.

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

Not easily, but see below.

> So note how I want two changes:

> - the id to be inside the heading, not on a separate div

The separate div is the HTML4-compatible representation of the section
element (with the HTML5 writer this will eventually become a <section>
element, too). With Docutils, the id is given to the <section>, not the
section's <title>.

> - control over the actual id

In Docutils, an element can have multiple ids but for the HTML
representation these need to be put on separate elements.
The current mechanism works for most practical purposes -- you may create a
custom HTML writer or propose a patch (and good resons for a change) to have
the custom id replacing the auto-generated one.

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

Well, the input is quite similar to the rST you probably used to get the
"close version"::


    .. _my custom header:
    
    My header
    =========
  
    `my custom header`_

This is translated to the internal representation::

  <document source="/tmp/foo.rst">
      <target refid="my-custom-header"></target>
      <section ids="my-header my-custom-header" 
               names="my\ header my\ custom\ header">
          <title>My header</title>
          <paragraph><reference name="my custom header"
                                refid="my-custom-header">my custom
                     header</reference></paragraph>
      </section>
  </document>

So everything is there to get the desired HTML output via a custom writer.
But is it worth the effort?


Günter

   


------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Docutils-users mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-users

Please use "Reply All" to reply to the list.