Next topic

This Page

Quick search

This extension is meant to help with the common pattern of having many external
links that point to URLs on one and the same site, e.g. links to bug trackers,
version control web interfaces, or simply subpages in other websites. It does
so by providing aliases to base URLs, so that you only need to give the subpage
name when creating a link.

Let’s assume that you want to include many links to issues at the Sphinx
tracker, at https://github.com/sphinx-doc/sphinx/issues/num. Typing
this URL again and again is tedious, so you can use extlinks
to avoid repeating yourself.

Now, you can use the alias name as a new role, e.g. :issue:`123`. This
then inserts a link to https://github.com/sphinx-doc/sphinx/issues/123.
As you can see, the target given in the role is substituted in the base URL
in the place of %s.

The link caption depends on the second item in the tuple, the prefix:

If the prefix is None, the link caption is the full URL.

If the prefix is the empty string, the link caption is the partial URL
given in the role content (123 in this case.)

If the prefix is a non-empty string, the link caption is the partial URL,
prepended by the prefix – in the above example, the link caption would be
issue123.

You can also use the usual “explicit title” syntax supported by other roles
that generate links, i.e. :issue:`thisissue<123>`. In this case, the
prefix is not relevant.

Note

Since links are generated from the role in the reading stage, they appear as
ordinary links to e.g. the linkcheck builder.