Cheat sheet: reST & Sphinx¶
Headlines¶
Every reST (.rst) file should use these underlining styles. In reST, you can use different styles in any order you want. These are our conventions for TYPO3 documentation.
1 ========
2 DocTitle
3 ========
4
5 Then use underlining only:
6
7 .. _header1:
8
9 Header 1
10 ========
11
12 Header 1.1
13 ----------
14
15 Header 1.1.1
16 ~~~~~~~~~~~~
17
18 Header 1.1.1.1
19 """"""""""""""
line 1-3: This is the doc title. Every .rst file should have one.
line 7: header label. This can be used for cross-referencing to this section:
:ref:`header1`
9-10: Header level 1
etc.
Links¶
External links¶
method 1:
`anchor text <URL>`__
Check out more information on `t3o <https://typo3.org>`__.
(with one or two underscores at the end, if in doubt, use two)
method 2: "External Hyperlink Targets":
Check out more information on t3o_
_t3o: https://typo3.org
This may be more convenient if you use a link several times.
Cross references¶
When linking within docs.typo3.org, you should use this method of cross-referencing.
Use it to link to a section in this manual:
:ref:`intersphinx`
A section with the label intersphinx must exist! It is placed before the header:
.. _intersphinx:
Intersphinx
===========
Or, when cross-referencing to other manuals:
:ref:`shortcut:label`
When you are linking to another manual, make sure the shortcut (here: "h2document") is included in Settings: Documentation/Settings.cfg:
[intersphinx_mapping]
h2document = https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Index.html
...
We use the same conventions for naming the shortcuts in Settings.cfg
,
see Settings: Documentation/Settings.cfg. Not used manuals are commented out.
Tip
This is a cool feature, where reST & Sphinx shines: Even when a section is moved to another page (which effectively changes the URL), the link will still work!
|
---|
Explicit anchor text
:ThisManual: |
Automatic anchor text
:ThisManual: |
Preventing links¶
Prevent unintentional linking of simple URLs with the :samp:
directive:
The TYPO3 backend can be accessed via :samp:`https://example.org/typo3` ..
and emphasize parts of the URL with curly braces:
The *route* is the "speaking URL" as a whole without the domain part,
for example :samp:`https://example.org/{<path>}`.
Hypothetical domains¶
If the domain name of an URL does not matter, but serves as a placeholder, choose from this list of dummy domains – in this order:
https://example.org
https://example.com
https://example.net
and use for explicit mention of the local development context:
https://example.localhost
.
For further dummy domains use subdomains of the domains listed above such as
https://staging.example.org
https://production.example.org
.
See also
Lists¶
How it looks:
To create a bullet list:
add a blank line before and after the list
indent the list item text by 4 spaces - including the item sign
to create a nested list:
indent the items by 4 spaces (left-align with parent item text)
apply rules of parent list (blank lines, item text indentation, ..)
More text.
Source:
To create a bullet list:
* add a blank line before and after the list
* indent the list item text by 4 spaces - including the item sign
* to create a nested list:
* indent the items by 4 spaces (left-align with parent item text)
* apply rules of parent list (blank lines, item text indentation, ..)
More text.
Numbered lists¶
How it looks:
To create a numbered list:
add a blank line before and after the list
indent the list item text by 4 spaces - including the item sign
to create a nested list:
indent the items by 4 spaces (left-align with parent item text)
apply rules of parent list (blank lines, item text indentation, ..)
More text.
Source:
To create a numbered list:
#. add a blank line before and after the list
#. indent the list item text by 4 spaces - including the item sign
#. to create a nested list:
#. indent the items by 4 spaces (left-align with parent item text)
#. apply rules of parent list (blank lines, item text indentation, ..)
More text.
Code Blocks¶
Important
Use syntactically correct code in your code blocks.
Code block directive¶
How it looks:
$a = 'hello';
$b = 'something';
Source:
1.. code-block:: php
2
3 $a = 'hello';
4 $b = 'something';
This uses the directive "code-block" (line 1)
Important
Make sure to indent correctly. The lines of the code-block (line 3+) must be indented (4 spaces).
Placeholders¶
Use the Backus-Naur form like <placeholder-name>
for placeholders in code and
URLs.
Examples:
class <Entity>Controller extends ActionController
typo3/sysext/core/bin/typo3 impexp:import <file>
https://example.org/typo3/main?token=<token-id>
For XML and HTML, use the comment tag <!-- placeholder-name -->
.
Inline code, text roles¶
For inline code or for other semantic markup of special texts, use text roles.
How it looks:
$result = $a + 23;
(PHP snippet)lib.hello.value = Hello World!
(TypoScript snippets)/etc/passwd
(file)ctrl + s (keyboard strokes)
Source:
1:php:`$result = $a + 23;`
2:typoscript:`lib.hello.value = Hello World!`
3:file:`/etc/passwd`
4:kbd:`ctrl` + :kbd:`s`
Bold & italic¶
How it looks:
Normal text, bold text and italic text.
Source:
Normal text, **bold text** and *italic text*.
Images¶
How it looks:

Source:
.. image:: /Images/a4.jpg
:class: with-shadow
Another example:
.. image:: /Images/a4.jpg
:class: with-shadow
:target: https://typo3.org
:alt: alt text
:width: 100px
See also
Styled numbered lists¶
This is often used, for a Quick Start section, involving a few numbered steps:
With Big Numbers¶
This is an example with a code block (::
) embedded in the sections.
How it looks:
Embed an image
Source:
/Images/a4.jpg :class: with-shadow
Two
Do something else ...
Source:
.. rst-class:: bignums
1. Embed an image
Source:
.. code-block:: rest
.. image: some_image.png
:class: with-shadow
2. Two
Do something else ...
With Big Numbers XXL¶
How it looks:
Embed an image
Source:
/Images/a4.jpg :class: with-shadow
Two
Do something else ...
Source:
.. rst-class:: bignums-xxl
1. Embed an image
Source:
.. code-block:: rest
.. image: some_image.png
:class: with-shadow
2. Two
Do something else ...
Configuration values (confval)¶
How it looks:
- title¶
- Required
true
- Type
string or LLL reference
- Scope
Display
- Path
$GLOBALS > TCA > [table] > columns > [field]
The name of the field as shown in the form.
Source:
.. confval:: title
:Required: true
:type: string or LLL reference
:Scope: Display
:Path: $GLOBALS > TCA > [table] > columns > [field]
The name of the field as shown in the form.
PHP domain¶
How it looks:
- class Vendor\MyExtension\DateTime¶
Datetime class
- setDate($year, $month, $day)¶
Set the date.
- Parameters
$year (
int
) -- The year.$month (
int
) -- The month.$day (
int
) -- The day.
- Returns
Either false on failure, or the datetime object for method chaining.
Source:
.. php:namespace:: Vendor\MyExtension
.. php:class:: DateTime
Datetime class
.. php:method:: setDate($year, $month, $day)
Set the date.
:param int $year: The year.
:param int $month: The month.
:param int $day: The day.
:returns: Either false on failure, or the datetime object for method chaining.
Tips, hints, important (Admonitions)¶
Visit Admonitions: Tip, Note, Warning, See also, etc to see the available admonitions.
How it looks:
Tip
To look at the reST source of this rendered page, scroll to the top and click on View source.
Source:
.. tip::
To look at the reST source of this rendered page, scroll to the bottom
and click on "View page source".
Cards¶
How it looks:
The Page Management Guide introduces TYPO3's Page Tree and explains how pages are created and managed.
Source:
.. container:: row m-0 p-0
.. container:: col-md-6 pl-0 pr-3 py-3 m-0
.. container:: card px-0 h-100
.. rst-class:: card-header h3
.. rubric:: :ref:`Pages <t3editors:pages>`
.. container:: card-body
The Page Management Guide introduces TYPO3's Page Tree and explains how pages are created and managed.
.. container:: card-footer pb-0
.. rst-class:: horizbuttons-striking-m
- `11 <https://docs.typo3.org/m/typo3/tutorial-editors/11.5/en-us/Pages/Index.html>`__
Tabs¶
How it looks:
touch example-project-directory/public/FIRST_INSTALL
echo $null >> public/FIRST_INSTALL
Source:
.. tabs::
.. group-tab:: bash
.. code-block:: bash
touch example-project-directory/public/FIRST_INSTALL
.. group-tab:: powershell
.. code-block:: powershell
echo $null >> public/FIRST_INSTALL
Graphs¶
How it looks:
Source:
.. graphviz::
graph {
user [
shape=plaintext;
width=4;
label="User";
style="";
]
view [
shape=box;
width=4;
label=<<B>View</B><BR/>Displaying the data>;
]
controller [
shape=box;
width=4;
label=<<B>Controller</B><BR/>Control of functionality>;
]
model [
shape=box;
width=4;
label=<<B>Model</B><BR/>Domain model and domain logic>;
]
user -- view -- controller -- model;
}