#77 Make anchors visible in webpage output

[Erik Martin-Dorel]

As a user of Alectryon (a tool relying on docutils to generate webpages from literate-programming code), I had submitted that issue / feature request: https://github.com/cpitclaudel/alectryon/issues/19 (Make anchors visible in Alectryon's webpage output).

And the author suggested that the availability of this feature directly relies on docutils:

That's a great idea. I think it would require a change to Docutils html writer, specifically the visit_title function in writers/_html_base.py. Could you open a feature request on the docutils tracker?

Hence this ticket :) So do you confirm this feature is lacking in docutils?

Because on second thought (after reading https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/docutils/writers/_html_base.py#l37), I believe the code below should already do the job?

        self.body.append(
              self.starttag(node, 'h%s' % h_level, '', **atts))
        atts = {}
        if node.hasattr('refid'):
            atts['class'] = 'toc-backref'
            atts['href'] = '#' + node['refid']
        if atts:
            self.body.append(self.starttag({}, 'a', '', **atts))
            close_tag = '</a></h%s>\n' % (h_level)
        else:
            close_tag = '</h%s>\n' % (h_level)

Thanks in advance for your reply and help

[Erik Martin-Dorel]

Sorry I realize I clicked on Submit too early (before putting a complete title to the ticket 😅)

[engelbert gruber]

Thanks in advance for your reply and help

i would prefer additional

reStructured input

    xxxx

current output

    xxxx

desired output

    xxxx

dont i

[Clément Pit-Claudel]

Here you go:

reStructured input

Title 1
=======

A

Title 2
-------

B

Title 3
~~~~~~~

C

current output

<div class="document" id="title-1">
<h1 class="title">Title 1</h1>

<p>A</p>
<div class="section" id="title-2">
<h1>Title 2</h1>
<p>B</p>
<div class="section" id="title-3">
<h2>Title 3</h2>
<p>C</p>
</div>
</div>
</div>

desired output

<div class="document" id="title-1">
<h1 class="title">Title 1 <a href="#title-1">¶</a></h1>

<p>A</p>
<div class="section" id="title-2">
<h1>Title 2 <a href="#title-2">¶</a></h1>
<p>B</p>
<div class="section" id="title-3">
<h2>Title 3 <a href="#title-3">¶</a></h2>
<p>C</p>
</div>
</div>
</div>

[Günter Milde]

on second thought ... I believe the code below should already do the job?

This depends on what you really want:

• A symbol appearing when hovering over a section heading can be easily added via CSS. This would, however have no function.
• Maybe you are after a way to easily create a bookmark (or copy a link) to the section in browsers. This could be done adding a link to itself before or after the heading (as done by, e.g., Sphinx).
• The anchor already present in a section heading links back to it's ToC entry.
  A user can easily click on the backlink and copy/bookmark the ToC entry linking to the section.

[Erik Martin-Dorel]

Maybe you are after a way to easily create a bookmark (or copy a link) to the section in browsers. This could be done adding a link to itself before or after the heading (as done by, e.g., Sphinx).

Indeed this is the intended feature :-)

Regarding the implementation itself − a symbol such as ¶ after the section title (like Clément proposed) or just before − I've no strong opinion.

The anchor already present in a section heading links back to it's ToC entry.
A user can easily click on the backlink and copy/bookmark the ToC entry linking to the section.

Thanks for your remark! Indeed that can be solution :-)
But as these links will only be generated if there is a ToC, do you think it would be useful to add an independent feature similar to that of Sphinx, or to GitHub's rendering of Markdown files? − https://user-images.githubusercontent.com/10367254/107887926-e1e1ea00-6f09-11eb-8b48-ccdb4b3f4452.png so that even if the ToC is not enabled, users would have by default (but may disable) a small symbol such as ¶…

What do you think?

[Günter Milde]

Duplicate of https://sourceforge.net/p/docutils/feature-requests/28/