---
title: "Supported named inline text roles"
manual: "How to Document"
version: "main"
permalink: "https://docs.typo3.org/permalink/h2document:text-roles"
source: "Reference/ReStructuredText/InlineMarkup/TextRoles/Index.rst"
rendered: "2026-09-26T10:48:44+00:00"
---

# Supported named inline text roles {#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-name:`), 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](https://docutils.sourceforge.io/docs/ref/rst/roles.html#standard-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.

> [!WARNING]
> **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:
>
> ```rst
> `\Vendor\Ext\MyClass`        renders as: VendorExtMyClass
> `\\Vendor\\Ext\\MyClass`     renders as: \Vendor\Ext\MyClass
> ```
>
> Double every backslash you want to keep. `:file:`, `:php:`
> and `:php-short:` 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:` {#text-roles-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.

```rst
:abbr:`LIFO (last-in, first-out)`
```

-   **How it looks:**

    LIFO

## `:path:` {#text-roles-path}

Refers to a directory or folder path, as opposed to a specific file. Use
[:file:](https://docs.typo3.org/permalink/h2document:text-roles-file) instead when the path ends in a file name.

```rst
The extension stores its data in :path:`public/fileadmin`.
```

-   **How it looks:**

    The extension stores its data in `public/fileadmin`.

## `:file:` {#text-roles-file}

Refers to a specific file, including its name and, if helpful, its path.
Use [:path:](https://docs.typo3.org/permalink/h2document:text-roles-path) instead when referring to a directory
rather than a single file.

```rst
Edit :file:`config/system/settings.php` to change the setting.
```

-   **How it looks:**

    Edit `config/system/settings.php` to change the setting.

## `:issue:` {#text-roles-issue}

Links to an issue on [TYPO3 Forge](https://forge.typo3.org) 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.

```rst
See also :issue:`102056` or :issue:`this issue <99508>`.
```

-   **How it looks:**

    See also [forge#102056](https://forge.typo3.org/issues/102056) or [this issue](https://forge.typo3.org/issues/99508).

## More text roles, documented on their own pages {#text-roles-elsewhere}

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](https://docs.typo3.org/permalink/h2document:rest-refer-to-gui-elements).
-   `:composer:` and `:t3ext:` for linking Composer packages and
    TER extensions — see
    [Linking Composer packages and TYPO3 extensions](https://docs.typo3.org/permalink/h2document:linking-extensions).
-   `:t3src:` for linking source files of the TYPO3 Core — see
    [Linking source files of the TYPO3 Core](https://docs.typo3.org/permalink/h2document:linking-core-source).
-   `:php:`, `:php-short:`, `:typoscript:` and other code
    roles with an infobox — see
    [Inline code with or without infoboxes](https://docs.typo3.org/permalink/h2document:inline-code).

> [!NOTE]
> **See also**
>
> -   [Basic inline markup (bold, italic etc.)](https://docs.typo3.org/permalink/h2document:rest-bold-italic)
> -   [Links in ReStructured Text](https://docs.typo3.org/permalink/h2document:how-to-document-hyperlinks)
> -   [Docutils: Interpreted Text Roles](http://docutils.sourceforge.io/docs/ref/rst/roles.html)