Inline code with or without infoboxes 

Any text inside single or double backticks is printed as inline code. Use single backticks by default; double backticks are only needed when the code itself contains an unescaped backtick:

This is $someCode and that is some ` code.

This is `$someCode` and that is ``some ` code``.
Copied!

Code roles with language information and an infobox 

You can also use text roles that name the language of the code:

  • $variable = 'Some general PHP'
  • \TYPO3\CMS\Core\Core\Environment TYPO3 class with fully qualified name
  • Environment TYPO3 class with short name
  • GeneralUtility::makeInstance() class member
  • \TYPO3\CMS\Core\Http TYPO3 namespace
  • \Symfony\Component\Dotenv\Dotenv External class
  • $GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport'] configuration values
  • page = PAGE
  • TCAdefaults.pages.hidden
  • <f:debug>{myVariable}</f:debug>
  • <code>
  • code#mycode {font-family: courier}
  • alert('test')
  • ./vendor/bin/typo3 help 
*   :php:`$variable = 'Some general PHP'`
*   :php:`\TYPO3\CMS\Core\Core\Environment` TYPO3 class with fully qualified name
*   :php-short:`\TYPO3\CMS\Core\Core\Environment` TYPO3 class with short name
*   :php-short:`\TYPO3\CMS\Core\Utility\GeneralUtility::makeInstance()` class member
*   :php-namespace:`\TYPO3\CMS\Core\Http` TYPO3 namespace
*   :php:`\Symfony\Component\Dotenv\Dotenv` External class
*   :php:`$GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport']` configuration values
*   :typoscript:`page = PAGE`
*   :tsconfig:`TCAdefaults.pages.hidden`
*   :fluid:`<f:debug>{myVariable}</f:debug>`
*   :html:`<code>`
*   :css:`code#mycode {font-family: courier}`
*   :js:`alert('test')`
*   :bash:`./vendor/bin/typo3 help`
Copied!

Every code role shows an icon right after the code that opens an infobox. For most roles, the infobox only names the language, for example "Code written in SQL". Some roles can tell the reader more:

The code text itself stays plain, selectable text, so it can be copied directly instead of accidentally opening the infobox.

Two text roles that are not code roles open an infobox as well: :composer: always does, with information from Packagist, and :file: only does for a file that the same manual documents with the .. typo3:file:: directive.

When to use a code role for inline code 

A code role labels its text as code in a language. Use one when the text is code in that language: a statement, an expression, a keyword, a type, or an identifier that the rendering can look up.

Everything else is a plain literal in single backticks. On text that is not code, the language label and the infobox add nothing, and they promise information that is not there.

Plain literals for array keys, configuration keys and column names 

A TCA key, CType, array key, or YAML configuration key looks like PHP because it is often written inside a PHP array, but the key itself is a string. Database table and column names such as tt_content or pid are often written next to SQL, but they are names, not SQL. Write all of them as plain literals:

The `enablecolumns` key ...

The `pid` column of the `pages` table ...
Copied!

Keep :sql: for actual SQL, such as a statement, a keyword like WHERE , or a column type like varchar(255) .

Plain literals for class names used generically 

When you talk about a kind of thing rather than one specific class, for example "a PreviewRenderer" used generically, there is nothing a role could resolve. Use a plain literal.

A namespace in a plain literal needs doubled backslashes, for example \Vendor\Ext\PreviewRenderer: unlike :php: , a plain literal drops a single backslash instead of printing it. See Backslashes in text roles.

PHP classes and interfaces with :php: and :php-short: 

These two roles resolve a PHP type, such as a class or an interface, and a member of one. Always pass the fully qualified name, including the leading backslash: the namespace is what the roles need to find the class. For a type of the TYPO3 Core, the infobox then shows its signature, the summary of its doc comment and a link to https://api.typo3.org. For any other type, for example one from Symfony, it can only say that the text is a class or interface name.

:php: also recognizes a path in the global configuration, such as $GLOBALS['TYPO3_CONF_VARS']['MAIL']['transport'] , and explains $GLOBALS['TYPO3_CONF_VARS'] in its infobox.

Referencing a PHP class or interface with :php-short: 

Use :php-short: . It resolves the type from the fully qualified name but shows only the short name, which reads much better inline:

:php-short:`\TYPO3\CMS\Core\Security\ContentSecurityPolicy\Scope`
Copied!

:php: resolves the type the same way but prints the full namespace.

Referencing a class member with :php-short: 

A method, property, constant or enum case resolves as well, as long as you write it after the fully qualified class, with :: or ->:

Create a scope with
:php-short:`\TYPO3\CMS\Core\Security\ContentSecurityPolicy\Scope::backend()`.
Copied!

The text prints as Scope::backend() . The infobox names what the member is, for example "PHP function" for a method, "PHP property", "PHP constant" or "PHP enum case", and describes the class it belongs to; the link to https://api.typo3.org leads to the member on the page of its class.

A member written on its own, such as Scope::backend(), has nothing to resolve without its namespace. Introduce the class once with :php-short: , then write the bare member as a plain literal.

Referencing a PHP namespace with :php-namespace: 

Use :php-namespace: for a namespace. Pass the fully qualified namespace, including the leading backslash:

The classes of :php-namespace:`\TYPO3\CMS\Core\Http` handle requests
and responses.
Copied!

The text prints as \TYPO3\CMS\Core\Http . The role always prints the full namespace, because the last segment alone says too little. The infobox calls it a PHP namespace. For a namespace of the TYPO3 Core, the infobox also links to the page of the namespace on https://api.typo3.org. The class index does not list a namespace.

:php: and :php-short: also recognize a namespace that the TYPO3 API knows, and print it in full. A use statement in a code example that imports such a namespace is recognized too.

Some names are a class and a namespace at the same time, for example \TYPO3\CMS\Core\Exception. :php: and :php-short: treat such a name as the class. If you mean the namespace, use :php-namespace: .

TypoScript and TSconfig with :typoscript: and :tsconfig: 

The infobox of :typoscript: and :tsconfig: says what the code is and links to its description. The rendering reads this from the configuration values of the TypoScript reference. This works in every manual, in the version of the TypoScript reference that its interlinks use.

The roles find the following:

  • A full path to an option, for example stdWrap.parseFunc , page.includeJS , or options.pageTree.doktypesToShowInNewPageDragArea .
  • An object type, a function, or a top-level object on its own, for example USER, COA_INT, PAGE, stdWrap, typolink, config, or module.

A name that several options share, such as wrap or current, gets no description. A wrong description is worse than none. Write the full path instead, for example stdWrap.current rather than current.

Naming the configuration value in angle brackets 

If the code alone does not tell which option it is, name the configuration value in angle brackets, as in :confval: :

Use :typoscript:`current <t3tsref:stdwrap-current>` to ...
Copied!

The text prints as current . The page shows only the code before the angle brackets.

  • The key is the :name: of the confval. Put an interlink key in front of it, such as t3tsref: or t3coreapi:, for a configuration value of another manual. Without an interlink key, the key names a configuration value of the same manual.
  • Any configuration value works, not only a TypoScript one. For example, you can name a TCA option.
  • The text before the angle brackets must be a path or a name. The rendering never reads code such as an HTML wrap, <div> | </div>, or <INCLUDE_TYPOSCRIPT: ...> as a key.

If the named manual does not document the key, the rendering shows a warning, and make test-docs fails. If the rendering cannot reach the manual, it shows no warning.