Linking Pages

Creating meaningful links between pages in your documentation will make your users love you, and while it’s a little confusing at first it makes a lot of sense in the long run.

I would suggest that making your documentation nicely linkable works best if you can get yourself into a few particularly useful habits:

Labelling Sections

Give every section of your documentation a meaningful label. For instance, the top of this page looks like the following:

.. _linking-pages:

=============
Linking Pages
=============

Once you have labelled a section, you then reference it with a reference link:

:ref:`linking-pages`

Which generates a link with the section title as the text, e.g. Linking Pages. Additionally, you can title the reference:

:ref:`Stuff about Linking Pages <linking-pages>`

Which becomes Stuff about Linking Pages.