Supported named inline text roles
A named inline text role marks up a short piece of text inline, in the
middle of a sentence. Write the role name surrounded by colons
(
:role-), immediately followed — with no space — by the text
it applies to, enclosed in backticks. Some roles expect that text to
follow a particular syntax, for example a link target, an issue number,
or a fully-qualified class name.
In general we support any text roles in reStructuredText that were
previously supported by Sphinx. The TYPO3 Documentation Rendering
Container also supports the
Docutils Standard Text Roles
except for
:raw:
, as that could pose security issues.
The roles below are the ones most commonly used across TYPO3 documentation that are not already covered on their own page.
Attention
For most roles, a lone backslash inside the backticks is treated as an escape character and silently disappears from the output instead of being printed. This trips people up in Windows paths and PHP namespaces:
`\Vendor\Ext\MyClass` renders as: VendorExtMyClass
`\\Vendor\\Ext\\MyClass` renders as: \Vendor\Ext\MyClassDouble every backslash you want to keep.
:file:
,
:php:
,
:php-, and
:php- are exceptions. They
print a single backslash as it is.
In these four roles, the text must not end with a backslash. That backslash escapes the closing backtick, and the role runs on into the text that follows. Doubling it does not help, because these roles then print both backslashes. If you are not sure how a given role handles a backslash, check the rendered output.
:abbr:
Marks a piece of text as an abbreviation or acronym. Write the abbreviation followed by its expansion in parentheses; the expansion is shown as a tooltip on hover and is not printed inline.
:abbr:`LIFO (last-in, first-out)`- How it looks:
- LIFO
:path:
Refers to a directory or folder path, as opposed to a specific file. Use :file: instead when the path ends in a file name.
The extension stores its data in :path:`public/fileadmin`.- How it looks:
- The extension stores its data in
public/.fileadmin
:file:
Refers to a specific file, including its name and, if helpful, its path. Use :path: instead when referring to a directory rather than a single file.
Edit :file:`config/system/settings.php` to change the setting.- How it looks:
- Edit
config/system/settings.phpto change the setting.
If the file is defined with the directive
.. typo3:, the role
links to its description. A popup tells the reader where the file is in a
Composer-based installation and in a Classic mode installation. The official
manuals define their files in
TYPO3 Explained, and
the role finds those files in every manual, in the version that the
interlinks of the manual use:
Add the setting to :file:`config/sites/my-site/settings.yaml`.- How it looks:
- Add the setting to
config/sites/my-site/settings.yaml.
Each definition decides with a regular expression which paths it matches. A file that neither the manual itself nor TYPO3 Explained defines, or a path that the expression does not match, prints as plain code.
:issue:
Links to an issue on TYPO3 Forge by its
number. By default the link text is forge#<number>; pass a custom link
text before the number in angle brackets to show different text instead.
See also :issue:`102056` or :issue:`this issue <99508>`.- How it looks:
- See also forge#102056 or this issue.
More text roles, documented on their own pages
A few text roles are common enough, or involved enough, to have a full page to themselves rather than a short entry here:
:guilabel:for GUI labels — backend modules, tabs, buttons, fields — and click paths through them, and:kbd:for keyboard shortcuts — see Referring to GUI elements and keystrokes.:composer:and:t3ext:for linking Composer packages and TER extensions — see Linking Composer packages and TYPO3 extensions.:t3src:for linking source files of the TYPO3 Core — see Linking source files of the TYPO3 Core.:php:,:php-,short: :php-,namespace: :typoscript:, and other code roles with an infobox — see Inline code with or without infoboxes.