Invalid link references in reStructuredText

[roxeteer]

If multiple links have the same clickable text, the generated references are incorrect in reStructuredText. For example:

This Markdown sample:

[click here](http://www.example.com/) or [click here](http://johnmacfarlane.net/pandoc/)

generates this reST code:

`click here`_ or `click here`_

.. _click here: http://www.example.com/
.. _click here: http://johnmacfarlane.net/pandoc/

which fails in Sphinx reST parser and in Pandoc produces this incorrect HTML:

<p><a href="http://johnmacfarlane.net/pandoc/">click here</a> or <a href="http://johnmacfarlane.net/pandoc/">click here</a></p>

The solution would be that Pandoc either generates code with embedded URIs or uses indirect hyperlink targets:

`click here <http://www.example.com/>`_ or `click here <http://johnmacfarlane.net/pandoc/>`_

or

`click here`__ or `click here`__

.. _link1: http://www.example.com/
.. _link2: http://johnmacfarlane.net/pandoc/

__ link1_
__ link2_

[roxeteer]

Related to this issue, Pandoc is not able to correctly parse indirect hyperlink targets (the last example): #512

[cjerdonek]

I think I came across this same issue with duplicate text.

The reStructuredText output from pandoc generated the following warning when I passed the pandoc output to Python's Docutils (specifically rst2html.py) for conversion to HTML:

<stdin>:6: (WARNING/2) Duplicate explicit target name: "github".

Another option would be for pandoc to issue a warning in this case.

[jgm]

Note: by default pandoc will produce the output you desire,

`click here <http://www.example.com/>`_ or `click here <http://johnmacfarlane.net/pandoc/>`_

It only produces reference-style links if you use the --reference-links option.

I'm guessing, though, that you want reference style links in general; you just want pandoc to be intelligent enough not to use them when it will produce problems.

[cjerdonek]

This issue discusses two closely related issues: outputting reference-style links with duplicate reference names (the original issue that produces incorrect HTML) and outputting embedded URIs (pandoc's default behavior) with duplicate reference names (the behavior I reported that yields a warning when the output is passed to rst2html.py).

I think the solution in both cases is to use anonymous references, which @roxeteer described partially in the original post and which are discussed here in more detail:

• Anonymous Hyperlinks
• Embedded URIs

As described in the links above, anonymous references can be achieved by using a double underscore instead of a single underscore in both cases. In the case of embedded URI's (non-reference-style links), this would mean doing this--

`click here <http://www.example.com/>`__

instead of this--

`click here <http://www.example.com/>`_

[jgm]

@cjerdonek, thanks. I should have a fix soon.

[cjerdonek]

Awesome, thanks again! 😀