Links & cross referencing

Quick Reference

In Sphinx you can use several types of links:

External links

for linking to other sources outside of the reST docs on docs.typo3.org.

`anchor text <url>`__

(with one or two underscores at the end, if in doubt, use two)

Cross-Referencing (:ref:)

for linking to other sections of the same manual on docs.typo3.org with Intersphinx mechanism

:ref:`anchor text <link-target>`

Cross-Referencing with intersphinx (:ref:)

for linking to other sections of a different manual on docs.typo3.org

If your link target is in another manual (for example "Getting Started Tutorial", you must add the shortcut (here: t3start) for the other manual:

:ref:`anchor text <t3start:link-target>`

The shortcut must be defined in Settings: Documentation/Settings.cfg

Whenever you use the cross-referencing mechanism, you should create a link target for a section chapter, by adding a label before the section header:

..  _link-target:

Headline
========

How to create links is described in more detail in the next sections.

Preventing links

being automatically generated from simple URLs – mostly used in connection with hypothetical domains.

:samp:`<url>`

Hypothetical domains

are domains for use in URLs where the domain does not matter, but serves as a placeholder. The TYPO3 documentation uses a defined set of them.

:samp:`https://example.org/news/`

External links

Important

Do not use this mechanism (external links) for links to sections of the official documentation. Use the Intersphinx mechanism as described in Cross referencing (:ref:). See Understanding the benefits for an explanation of why you should do this.

You can use one or more underscores (_) for the link. The difference is as follows:

• One underscore creates a named reference

• Two underscores create an anonymous URL

For further explanation of the difference between these 2, please see Stackoverflow.

If in doubt, just use 2 underscores as explained in the next section External link as anonymous URL.

External link as anonymous URL

Syntax

`Anchor text <URL>`__

• There must always be a space between the anchor text and the URL

Example

`Sphinx hyperlinks <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#hyperlinks>`__

How it looks

Sphinx hyperlinks

External link as named reference

Syntax

Same as anonymous URL, but with one underscore instead of 2.

`Anchor text <URL>`_

• There must always be a space between the anchor text and the URL

Link targets

When using the Cross referencing (:ref:) mechanism (as described in the next section), you will link to link targets.

Explicit link targets (Labels for cross referencing)

You can define an explicit link target with a label for a section (or chapter):

A section label of the name columns-inline is set:

..  _columns-inline:

Here, the link target columns-inline will be defined.

• Place the link target definition directly before the section header:

..  _columns-inline:

Inline columns
==============

• You can define more than one link target definition (for example if you want to keep some for historical reasons to not break links but the name has changed considerably)

Implicit link targets

For every section (or chapter), an implicit link target is created from the header.

However, there are some disadvantages in using these, so we will not go into that further.

Cross referencing (:ref:)

This section describes how to link to sections of the current or other manuals correctly.

Additional information: See the Sphinx documentation.

For an overview of the link types, see Cross references in the "ReST & Sphinx Cheat Sheet".

In the same manual

A section label of the name columns-inline has been set somewhere:

..  _columns-inline:

Inline Columns
==============

You can then link to it like this from the same manual:

:ref:`columns-inline`

This will use the header of the section as anchor text.

You can also explicitly set an anchor text:

:ref:`Inline columns <columns-inline>`

From one manual to another

Example 1: Use text of headline as anchor text

Again, we want to link to the labels columns-inline and This-is-ABC.

But since the labels are now in a different manuals, we need to prefix the names of that manuals:

:ref:`t3tca:columns-inline`
:ref:`t3install:This-is-ABC`

The name t3tca is the name we have given it in the Settings.cfg file: . This-is-ABC is just an example wording.

t3tca            = https://docs.typo3.org/m/typo3/reference-tca/main/en-us/
t3install      = https://docs.typo3.org/m/typo3/guide-installation/main/en-us/

Important

Check the Settings.cfg file for the manual you are working on to make sure the manual shortcuts for intersphinx linking are available in the section [intersphinx_mapping]. You may need to remove the comment marker # at the beginning of the line.

This is called cross-referencing with the intersphinx mechanism.

In this example, the linktext shown will be whatever the text of the headline is that follows the label in the manual we link to, in this case the TCA manual.

Example 2: Specify anchor text

If we want to control the anchor text ourselves, we can do so by writing:

:ref:`this is our linktext <t3tca:columns-inline>`

Understanding the benefits

Imagine that the TCA manual has been restructured. Text and maybe urls changed, but the - purely - symbolic label has been kept. As a result the links (= intersphinx references) in foreign manuals will work again as soon they are rebuilt.

Tips

1. For convenience many manuals already have a objects.inv.json where you can easily

   see what link targets are available. Example: https://docs.typo3.org/m/typo3/reference-tca/main/en-us/objects.inv.json

2. As an editor you should not change or remove labels once they have been published.

   If you feel that a label (= link target) should be changed you should keep the old one and add the new one on a separate line. You cannot know whether some other manual in the world links to the label you would like to remove.

3. You still CAN remove that label. The only problem that may arise is that foreign links

   aren't generated any more.

Preventing links

Sphinx automatically converts simple URLs into links. This can be unintentional in certain contexts, for example when using a hypothetical domain like "example.org" or placeholders instead of real query parameters in a tutorial. To prevent linking, the TYPO3 documentation uses the :samp: directive to wrap the URL.

For example:

The TYPO3 backend can be accessed via :samp:`https://example.org/typo3` ..

is rendered like:

The TYPO3 backend can be accessed via https://example.org/typo3 ..

To emphasize parts of the URL, use curly braces:

The *route* is the "speaking URL" as a whole without the domain part,
for example :samp:`https://example.org/<page-path>/{<page-name>}`.

is rendered like:

The route is the "speaking URL" as a whole without the domain part, for example https://example.org/<page-path>/<page-name>.

Hypothetical domains

The TYPO3 documentation uses a defined set of dummy domains when describing URLs where the domain name does not matter, but serves as a placeholder. The defined set is

1. https://example.org

2. https://example.com

3. https://example.net

– in this order: https://example.org as the preferred domain, and https://example.com and https://example.net as alternatives if multiple domains are required in the same context.

Why is https://example.com not preferred, as common sense would have it? Because the preference for .org over .com fits with the fact that the TYPO3 documentation is hosted on https://typo3.org and the TYPO3 Association is owning the TYPO3 GmbH.

For explicit mention of the local development context it uses

4. https://example.localhost.

If you need additional dummy domains, use subdomains of the domains listed above such as https://staging.example.org and https://production.example.org.

For example:

The class :php:`MailMessage` can be used to generate and send a mail without
using Fluid:


..  code-block:: rest

    $mail = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Mail\MailMessage::class);
    $mail
        ->from(new Address('john.doe@example.org', 'John Doe'))
        ->to(
            new Address('receiver@example.com', 'Max Mustermann'),
            new Address('other@example.net')
        )