References to TYPO3 documentation

You can link the following elements in any TYPO3 manual: Headlines, confvals and phpdomain definitions. It is also possible to put an anchor almost anywhere and then link it.

When an element in a manual can be linked a link symbol will appear when you hover it:

Hover over a headline to see if it is linkable, then click the link icon

After you click the link icon you can copy the reST link from the modal that appears:

The reST code of the reference looks like this:

Reference from another manual

:ref:`Hide detail page in URL <georgringer/news:hideDetailPage>`

A reference has the following syntax:

Syntax of a reST reference

:ref:`[link_text] <[interlink]:[anchor]>`

If you are linking within the same manual you can omit the [interlink]: part, including the colon.

Reference from inside the same manual

:ref:`Hide detail page in URL <hideDetailPage>`

If there is a warning box displayed, that the link has no anchor, you can still link to it using a doc-reference:

The link then looks like this in reST:

:doc:`Some further explanations <georgringer/news:Tutorials/BestPractice/HideDetailPage/Index#some-further-explanations>`

However such a link would not work anymore if the section was moved to another page or if another section with the same headline was introduced.

We suggest adding a unique link anchor to the headline to be linked to in this case. See section Link anchors.

Permalinks

The same modal also offers a permalink: a plain URL that resolves to the current location of the element.

A permalink used as an external link

`Cache tags <https://docs.typo3.org/permalink/t3coreapi:caching-developer-cache-tags>`_

Permalinks are the preferred way to link TYPO3 documentation. Unlike a reST reference, a permalink can be opened directly from the source file — in an editor, a diff or a review — without rendering the manual first, and it works outside reST as well, for example in a commit message or an issue.

Copy permalinks from the modal rather than assembling them by hand. A permalink follows three rules that are easy to get wrong:

The interlink shortcode is required. It is needed even when the anchor lives in the manual you are writing in: permalink/t3coreapi:dependency-injection resolves, permalink/dependency-injection does not.
The manual is written with hyphens, not slashes. This is where a permalink differs from the reST reference above: :ref: uses friendsoftypo3/content-blocks:, the permalink uses friendsoftypo3-content-blocks:.
Underscores in an anchor become hyphens. The anchor .. _run_upgrade_wizard: is published as run-upgrade-wizard, so only permalink/t3coreapi:run-upgrade-wizard resolves.

Warning

A wrong permalink can render without any warning and still return 404 for readers. Rendering resolves the URL against the anchors it holds in memory, while docs.typo3.org resolves it against the published inventory, in which the keys are normalized. All three mistakes above therefore pass a make test-docs run. See render-guides issue #1402.

Always give a link text

Give every reference and every permalink its own link text, written to fit the sentence it appears in:

To keep news URLs short, :ref:`hide the detail page <georgringer/news:hideDetailPage>`.

Tag the entries with
`cache tags <https://docs.typo3.org/permalink/t3coreapi:caching-developer-cache-tags>`_
so that they can be flushed together.

A reference without a link text, such as :ref:`georgringer/news:hideDetailPage`, uses the headline of the target section instead. This causes two problems:

A headline is written as a title, not as part of your sentence. "To keep news URLs short, Hide detail page in URL." does not read well, and you cannot adapt the wording to the grammar around it.
Headlines change. When a headline is renamed, its anchor stays the same, so the link keeps working, but its text changes with the headline. The link can then stop fitting your sentence, or stop saying what you meant, without anybody touching your page.

A permalink without a link text is worse: it shows the bare URL.

The reST reference you copy from the link modal uses the headline of the target as its link text. Reword that text to fit your sentence before you use it.

Let the rendering check the link texts

A manual can have the rendering warn about every reference that has no link text of its own. Switch the check on with check-link-text in Documentation/guides.xml:

Documentation/guides.xml

<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
           check-link-text="true" />

The check is off by default, because a warning fails a render with --minimal-test and most manuals still have references without a link text. Give the references of your manual a link text first, then switch it on so that the next one cannot slip in unnoticed.

Switching the check for a single page

A page can override the setting of its manual with a field above the title:

Documentation/Reference/Menus/NavigationTitle.rst

:check-link-text: off

================
Navigation title
================

Use off for a page that shows a reference without a link text on purpose, for example one that demonstrates what such a reference does. Use on while a manual is being cleaned up page by page and the setting of the manual is still off.