CODEWITHSUNDEEP
markdownrestructuredtext
Andrew
Andrew

Reputation: 4428

What's the rst equivalent of markdown named links?

In markdown, I can do this:

Imagine a long paragraph here, with [an extended phrase linked
to something elsewhere][shortref].

[shortref]: http://really-long-and-annoying-link-here

What's the equivalent syntax in reStructuredText?

Upvotes: 1

Views: 166

Answers (2)

G. Milde
G. Milde

Reputation: 929

The direct equivalent to markdown's "named links" is an an anonymous hyperlink reference with embedded alias:

Imagine a long paragraph here, with `an extended
phrase linked to something elsewhere <shortref_>`__.

.. _shortref: http://really-long-and-annoying-link-here

It is suited for one-time use of the extended phrase.

If you want to re-use the extended phrase, embed the alias in a named hyperlink reference (watch the number of trailing underscores):

Imagine a long paragraph here, with `an extended
phrase linked to something elsewhere <shortref_>`_.

Subsequent use of `an extended phrase linked to 
something elsewhere`_ must not contain the alias.

.. _shortref: 
    http://really-long-and-annoying-link-here

To keep the alias "out of the way", use an indirect hyperlink target which may be anonymous or named:

Imagine a long paragraph here, with `an extended
phrase linked to something elsewhere`__.

__ shortref_

.. _shortref: 
   http://really-long-annoying-link-here

You may also use an internal hyperlink target (with empty "link block") placed above the target it refers to:

Imagine a long paragraph here, with `an extended
phrase linked to something elsewhere`_.

.. _an extended phrase linked to something
    elsewhere:
.. _shortref: really-long-
              and-annoying-link-here

(Note: In rST, you can wrap a "really-long-and-annoying" URL because whitespace is ignored in URI context.)

Substitutions come handy if the extended phrase should be abbreviated in the rST source or if it contains inline markup:

Imagine a long paragraph here, with |shortref|_.

.. |shortref| replace:: an *extended phrase* 
                  linked to something elsewhere

.. _shortref: 
   really-long-and-annoying-link-here

Substitutions use a namespace different from reference names.

Upvotes: 0

Steve Piercy
Steve Piercy

Reputation: 15065

You could define a substitution with a replacement and a reference to the corresponding hyperlink target.

Imagine a long paragraph here, with |SR|_.

.. |SR| replace:: an extended phrase linked to something elsewhere
.. _SR: http://really-long-and-annoying-link-here

Another option is not an exact equivalent, but is still close:

Imagine a long paragraph here, with `an extended phrase linked
to something elsewhere`_.

Here is a short reference link: `shortref`_.

.. _shortref: `an extended phrase linked to something elsewhere`_
.. _an extended phrase linked to something elsewhere: http://really-long-and-annoying-link-here

The example above uses a combination of external and indirect hyperlink targets.

Upvotes: 3

Related Questions