Note
This version of the guide covers the new PHP-based rendering of Documentation with the TYPO3 Documentation theme.
If the project you are looking at has a file Documentation/guides.xml it is using the new rendering.
Otherwise, consider to migrate the Documentation or head over to the legacy version of this guide: How to document, Sphinx based.
Links & cross references¶
In reStructuredText (reST) there are multiple methods to define links to different targets. This text describes those most commonly used in TYPO3 manuals.
References to TYPO3 manuals¶
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:
After you click the link symbol you can copy the reST link from the modal that appears:
The reST code of the reference looks like this:
:ref:`Hide detail page in URL <georgringer/news:hideDetailPage>`
A reference has the following syntax:
:ref:`[link_text] <[interlink]:[anchor]>`
If you are linking within the same manual you can omit the [interlink]:
part,
including the colon.
: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 to make add a unique link anchors to the headline to be linked in this case. See section Link anchors.
External links¶
Important
Do not use this mechanism (external links) for links to sections of the TYPO3. Use references as described in the section above: References to TYPO3 manuals.
An URL that is mentioned within a text is automatically linked:
Lorem Ipsum Dolor https://example.org dolor sit
The result looks like this:
Lorem Ipsum Dolor https://example.org dolor sit
If you want to also give the URL a distinctive link text you can use the following syntax:
Lorem Ipsum Dolor `Example Page <https://example.org>`__ dolor sit
The result looks like this:
Lorem Ipsum Dolor Example Page dolor sit
Sometimes links can get quite long and unruly to use within the text. You can use so called named links to separate the link definitions from the text:
Lorem Ipsum Dolor `Example Page`_ dolor sit
.. _Example Page: https://example.org
The result looks like this:
Lorem Ipsum Dolor Example Page dolor sit
Link anchors¶
Link anchors assign a unique name to a headline and its section. These anchors can be used in internal references and references between TYPO3 manuals.
As long as the anchor of a section stays the same the section can be moved to another page or the headline can be renamed and references will still go to the correct target.
You can define a link anchor with a label for a section.
In the following example, the link target columns-inline
is assigned
to the section with the title "Inline columns".
Place the link anchor definition directly before the section header:
.. _columns-inline:
Inline columns
==============
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
- https://example.org
- https://example.com
- 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
- 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:: rst
$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')
)