Links to TYPO3 documentation

You can link the following elements in any TYPO3 manual: headlines, confvals, and PHP domain definitions. You can also put an anchor almost anywhere and link to it.

There are two ways to write such a link:

A permalink, written as a normal link with a URL. This is the preferred way, also for links inside the same manual.
A reST reference with the :ref: text role.

Both ways point to an anchor, not to a file. The link keeps working when the section moves to another page or its headline is renamed.

Table of contents

Copy the link from the link modal

When you hover over an element that can be linked, a link icon appears:

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

Click the link icon. A modal opens that offers the following for this element:

The permalink itself.
The current URL of the element.
A link in reST, a link in Markdown, and a link in HTML. The reST and the Markdown link use the permalink.

Copy the link in reStructuredText (reST)

Copy the link from this modal rather than assembling it by hand. Do not copy the URL from the address bar of your browser, or the URL from the modal: it contains the version and the path of the page, and it breaks when the page is moved.

The link in reST from the modal looks like this:

Link copied from the link modal

`Hide detail page in URL <https://docs.typo3.org/permalink/georgringer-news:hidedetailpage>`_

Reword the link text to fit your sentence, see Always give a link text.

Permalinks

A permalink is a plain URL on docs.typo3.org. It names the manual and the anchor of the element, and it redirects to the current location of the element in the main version of the manual. Use it like any other external link:

A permalink in reST

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

A permalink has the following syntax:

Syntax of a permalink

https://docs.typo3.org/permalink/[interlink]:[anchor]

Permalinks are the preferred way to link TYPO3 documentation, for the following reasons:

You can open a permalink directly from the source file, in an editor, a diff, or a review. You do not have to render the manual first to see where the link goes.
The same link works in reST, in Markdown, in a commit message, in an issue, and in a chat.

Permalinks inside the same manual

Use permalinks for links inside your own manual as well. Write them with the interlink shortcode of your manual, which is set with interlink-shortcode in Documentation/guides.xml:

A permalink from this guide to a page of this guide

Every headline needs an
`anchor <https://docs.typo3.org/permalink/h2document:link-targets-explanation>`_.

The rendering turns such a permalink into a link to the page in the rendered manual, also in a local render with make docs.

Rules for permalinks

If you write or change a permalink by hand, follow these three rules:

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.
Write the manual as its shortcode, with the slash. A permalink uses the same shortcode as a reST reference, for example friendsoftypo3/content-blocks:. Older permalinks write the slash as a hyphen, such as friendsoftypo3-content-blocks:. This form still works, but not for a vendor whose name has a hyphen: permalink/web-vision/deepltranslate-core:start resolves, permalink/web-vision-deepltranslate-core:start does not.
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.

The rendered page links to the right target even if you break one of these rules. The URL in the source file, however, returns 404 for everyone who opens it from there. The rendering warns about a missing shortcode and about an anchor with underscores, so make test-docs fails on them. See render-guides issue #1402.

reST references

A reST reference uses the :ref: text role:

Reference to another manual

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

A reference has the following syntax:

Syntax of a reST reference

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

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

Reference inside the same manual

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

The link modal does not offer a reST reference. Many manuals contain reST references. They keep working, and you do not have to replace them with permalinks.

Headlines without an anchor

If a headline has no anchor, the modal shows a warning and offers no permalink. All its links, the one in reST included, use the URL of the page:

Do not use the links from the modal in this case. They point to a page and a headline, not to an anchor. They break when the section is moved to another page. They can point to the wrong section when another section with the same headline is added.

Add a unique anchor to the headline instead, and link to that anchor with a permalink. See section Link anchors.

Do not write a file path into a permalink either, such as https://docs.typo3.org/permalink/georgringer-news:Tutorials/Index#some-section. The permalink route of docs.typo3.org resolves anchors only, so such a link returns 404. The rendering warns about it and asks for the anchor of the headline.

A :doc: link to a page and a headline, such as :doc:`Some further explanations <georgringer/news:Tutorials/BestPractice/HideDetailPage/Index#some-further-explanations>`, has the same problems.

Always give a link text

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

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

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

A permalink without a link text shows the bare URL.

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.

The link modal uses the headline of the target as the 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/ReStructuredText/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.