diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst index a59585bab..32360baf7 100644 --- a/doc/markup/inline.rst +++ b/doc/markup/inline.rst @@ -145,10 +145,15 @@ Cross-referencing arbitrary locations The same works for tables that are given an explicit caption using the :dudir:`table` directive. - * Labels that aren't placed before a section title can still be referenced - to, but you must give the link an explicit title, using this syntax: + * Labels that aren't placed before a section title can still be referenced, + but you must give the link an explicit title, using this syntax: ``:ref:`Link title ```. + .. note:: + + Reference labels must start with an underscore. When referencing a + label, the underscore must be omitted (see examples above). + Using :rst:role:`ref` is advised over standard reStructuredText links to sections (like ```Section title`_``) because it works across files, when section headings are changed, and for all builders that support