George V. Reilly

reStructuredText Anonymous Hyperlinks

While re­search­ing yesterday’s post about nested markup in Re­Struc­tured­Text, I finally learned how to use anonymous hyperlinks.

Hitherto, I used one of these three forms for hyperlinks:

1. The central conceit of the fictional `Flashman Papers`_ is that Flashy
2. besieging Breda_ in 1625.
3. my club, `Freely Speaking Toastmasters <http://freelyspeaking.org/>`_.

.. _Flashman Papers:
    https://en.wikipedia.org/wiki/The_Flashman_Papers
.. _Breda: http://en.wikipedia.org/wiki/Siege_of_Breda

The first, `Flashman Papers`_, is a named hyperlink reference, which refers to an external hyperlink target, .. _Flashman Papers: URI. Note that the reference name starts with a backquote, `, and ends with backquote-underscore, `_.

The second, Breda_, is a simple reference name—the backquotes are optional.

`Freely Speaking Toast­mas­ters <http://freelyspeak­ing.org/>`_, is an embedded URI. The syntax is `, reference-name, <, URI, >`.

With anonymous hyperlinks, the reference name does not need to be repeated in the hyperlink target. Instead, the reference name ends with a double-underscore, __, and the target looks like either .. __: URI or __ URI. The targets must appear in the order they are referenced. It’s best if they’re close to the references in the text, for main­tain­abil­i­ty.

researching `yesterday's post`__ about ...,
I learned how to use `anonymous hyperlinks`__.

.. __: /blog/2016/06/29/reStructuredTextNestedMarkup.html
__ http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#anonymous-hyperlinks

To handle escaping backquotes inside code literals for this post, I used the literal role instead of double backquotes:

The first, :literal:`\`Flashman Papers\`_`, is a *named hyperlink reference*
Normally, I use double-backquotes to bracket code: ``a += b & c[i]``.
blog comments powered by Disqus
reStructuredText Nested Markup » « Review: Jimmy's Hall