TYPO3 Logo
Writing Documentation
Release: main

Loading data.

BASICS

  • About this guide
  • Help & Support
  • Basic principles
  • Documentation content style guide
    • Spelling
    • Spelling, terms and glossary
    • File structure
    • Formats (reST, Markdown)
    • Coding guidelines for reST files
    • Guidelines for creating images
    • Commit messages
    • Licenses
  • reStructuredText & Sphinx
    • Introduction
    • Basic reST & Sphinx syntax
    • Common pitfalls
      • Problems with headers
      • Problems with links
      • Problems with indents
      • Problems with inline style
      • Problems with lists
    • Cheat sheet: reST & Sphinx
    • Reference: reST & Sphinx
      • Code blocks and code structure
        • Code blocks with syntax highlighting
        • Configuration values (confval)
        • Inline code & text roles
        • PHP domain
      • Content styles and content elements
        • Admonitions: Tip, Note, Warning, See also, etc
        • Bold, Italic etc.
        • Cards
        • Clever reST
        • Comments
        • Links & cross referencing
        • Special characters
        • Special styles
        • Tables
        • Tabs
        • Versions
        • Embed YouTube videos
      • Graphs, images and diagrams
        • PlantUML diagrams
        • Graphviz graphs
        • Images
      • Lists
        • Styled numbered sections (bignums)
        • Bullet lists / unordered lists
        • Definition lists
        • List items as buttons
        • Numbered lists
      • Menus and page structure
        • Content menu
        • Headlines and sections
        • Including files
        • Toctree and the hierarchical structure of a manual
        • Orphaned pages
        • Sidebar
  • User's round trip

HOWTOS

  • How to write good content
    • Tips for writing good content
    • Writing a tutorial
    • Writing Resources
  • How to document an extension
    • Register for docs.typo3.org
    • Webhook
    • Reregister versions
    • FAQ
    • Contribute to system extensions
    • Contribute to third-party extensions
  • Contribute to the TYPO3 documentation
    • Workflow #1: "Edit on GitHub"
    • Workflow #2: "Local editing and rendering with Docker"
    • How You Can Help
  • Tools for Editing reST
  • How to render documentation
    • Rendering the documentation with Docker
    • Rendering the documentation with Docker Compose
    • Troubleshooting local rendering with Docker
  • How to work with GitHub

ADVANCED

  • How to add translations
  • Update documentation for new releases
  • Guidelines for reviewing manuals

MAINTAINERS

  • For maintainers
    • Backport changes
  • Sitemap
  • Index
  • Appendix
    • Example Toctree
      • Topic1
        • Subtopic 1
        • Subtopic 2
    • Information for editing this guide

PAGE CONTENTS

  • Links & cross referencing
    • Quick Reference
    • External links
      • External link as anonymous URL
        • Syntax
        • Example
        • How it looks
      • External link as named reference
        • Syntax
    • Link targets
      • Explicit link targets (Labels for cross referencing)
      • Implicit link targets
    • Cross referencing (:ref:)
      • In the same manual
      • From one manual to another
        • Example 1: Use text of headline as anchor text
        • Example 2: Specify anchor text
      • Understanding the benefits
      • Tips
    • Preventing links
    • Hypothetical domains
  1. Start
  2. reStructuredText & Sphinx
  3. Reference: reST & Sphinx
  4. Content styles and content elements
  5. Links & cross referencing
View source How to edit Edit on GitHub

Display settings


Color scheme of code blocks:


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

  1. 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')
        )
  • Previous
  • Next
  • Home
  • Contact
  • Issues
  • Repository

Last updated: Jan 10, 2023 17:38

Last rendered: Jan 10, 2023 17:39

  • TYPO3 Theme 4.7.9
  • DRC v3.0.dev30
© Copyright since 2017 by the TYPO3 contributors
  • Legal Notice
  • Privacy Policy
  • Code of Conduct