reST & Sphinx cheat sheet¶
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 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | ========
DocTitle
========
Then use underlining only:
.. _header1:
Header 1
========
Header 1.1
----------
Header 1.1.1
~~~~~~~~~~~~
Header 1.1.1.1
""""""""""""""
|
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`
:ref:`h2document:intersphinx`
When you are linking to another manual, make sure the shortcut (here: “h2document”) is included in Settings.cfg:
[intersphinx_mapping]
h2document = https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/Index.html
...
We use the same conventions for naming the shortcuts in Settings.cfg
,
see 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!
Link to: Same manual | Link to: Other manual | |
---|---|---|
Explicit anchor text | :ref:`Cross Referencing <intersphinx>` |
:ref:`Cross Referencing <t3docwrite:intersphinx>` |
Automatic anchor text | :ref:`intersphinx` |
:ref:`t3docwrite:intersphinx` |
See also
Lists¶
To create a bullet list:
- add a blank line before and after the list
- indent the list item text by 3 spaces - including the item sign
- to create a nested list:
- indent the items by 3 spaces (left-align with parent item text)
- apply rules of parent list (blank lines, item text indentation, ..)
More text.
To create a bullet list:
* add a blank line before and after the list
* indent the list item text by 3 spaces - including the item sign
* to create a nested list:
* indent the items by 3 spaces (left-align with parent item text)
* apply rules of parent list (blank lines, item text indentation, ..)
More text.
Numbered lists¶
To create a numbered list:
- add a blank line before and after the list
- indent the list item text by 3 spaces - including the item sign
- to create a nested list:
- indent the items by 3 spaces (left-align with parent item text)
- apply rules of parent list (blank lines, item text indentation, ..)
More text.
To create a numbered list:
#. add a blank line before and after the list
#. indent the list item text by 3 spaces - including the item sign
#. to create a nested list:
#. indent the items by 3 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 2 3 4 | .. code-block:: php
$a = 'hello';
$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 (3 spaces).
Literal Block (::
)¶
Or, use the literal block markup ::
if PHP is already set as default
with highlight
directive and you want to combine a text with a colon,
followed by the code block.
How it looks:
Assign the variable a:
$a = 'hello';
Source:
Assign the variable a::
$a = 'hello';
Inline code, text roles¶
For inline code or for other semantic markup of special texts, use text roles.
Examples:
$result = $a + 23;
(PHP snippet)lib.hello.value = Hello World!
(TypoScript snippets)/etc/passwd
(file)- ctrl + s (keyboard strokes)
Source (inline text with text roles):
1 2 3 4 | :php:`$result = $a + 23;`
:typoscript:`lib.hello.value = Hello World!`
:file:`/etc/passwd`
:kbd:`ctrl` + :kbd:`s`
|
Bold & italic¶
Normal text, bold text and italic text.
Source (bold & italic):
Normal text, **bold text** and *italic text*.
Images¶

Source (image):
.. 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.
Source:
.. rst-class:: bignums
1. Embed an image
Source::
.. image: some_image.png
:class: with-shadow
2. Two
Do something else ...
How it looks:
Embed an image
Source:
../images/a4.jpg :class: with-shadow
Two
Do something else …
With Big Numbers XXL¶
Source:
.. rst-class:: bignums-xxl
1. Embed an image
Source::
.. image: some_image.png
:class: with-shadow
2. Two
Do something else ...
How it looks:
Embed an image
Source:
../images/a4.jpg :class: with-shadow
Two
Do something else …
Tips, hints, important (Admonitions)¶
Tip
To look at the reST source of this rendered page, scroll to the bottom and click on “View page source”.
- Source (tip):
.. tip:: To look at the reST source of this rendered page, scroll to the bottom and click on "View page source".
Diagrams¶
Source:
.. uml::
== Initialization ==
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
== Repetition ==
Alice -> Bob: Another authentication Request
Alice <-- Bob: another authentication Response
How it looks: