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:
and
:php- are exceptions -- they take the text verbatim,
so a single backslash there already prints as-is. If you are not
sure how a given role handles it, check the rendered output rather
than assuming.
: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/to change the setting.system/ settings. php
: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: :typoscript:and other code roles with an infobox — see Inline code with or without infoboxes.