.. This is a comment. It starts with 2 dots and a space .. ----------------------------------------------------------- include directive: Here, it includes the file Includes.txt. All files in the documentation project should do this. Use correct path! ----------------------------------------------------------- .. include:: ../Includes.txt .. ------------------------------------------------------------------ highlight directive: sets the default language for code-blocks. Usually, default is set to PHP in Includes.txt. Here, we set it to rst (for reStructuredText). ------------------------------------------------------------------ .. highlight:: rst .. ------------------------------------------------------------------------ header label: You can use this to create cross-references: To link to the next section, use :ref:`rest-cheat-sheet` or :ref:`h2document:rest-cheat-sheet` from another manual ------------------------------------------------------------------------- .. --------------------------------------------------------- header: Use (over and) underline to mark a text as header --------------------------------------------------------- .. _rest-cheat-sheet: ========================= 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. .. code-block:: rest :linenos: ======== 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. .. seealso:: * :ref:`Headlines-and-sections` * :ref:`explicit-link-targets` .. _cheat-sheet-links: :ref:`Links ` ========================================= .. _cheat-sheet-external-links: External Links -------------- method 1: Check out more information on `t3o `__. Source:: Check out more information on `t3o `__. :: `anchor text `__ (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 source:: Check out more information on t3o_ .. (this is a comment) the link is defined (usually on bottom of page) .. _t3o: https://typo3.org This may be more convenient if you use a link several times. .. _linked: https://typo3.org .. _cheat-sheet-intersphinx: 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 :ref:`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 :file:`Settings.cfg`, see :ref:`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! .. t3-field-list-table:: :header-rows: 1 - :Anchor: :ThisManual: Link to: Same manual :OtherManual: Link to: Other manual - :Anchor: **Explicit** anchor text :ThisManual: ``:ref:`Cross Referencing ``` :OtherManual: ``:ref:`Cross Referencing ``` - :Anchor: **Automatic** anchor text :ThisManual: ``:ref:`intersphinx``` :OtherManual: ``:ref:`t3docwrite:intersphinx``` .. seealso:: * :ref:`link-targets-explanation` (labels) * :ref:`intersphinx` * :ref:`settings-cfg` :ref:`Lists ` ========================= This is a bullet list: * list item 1 * list item 2 More text. .. important:: Always add blank line before and after list! .. code-block:: rest This is a bullet list: * list item 1 * list item 2 More text. **Important:** Always add blank line before and after list! Add a blank link too, when starting another list hierarchy:: This is a bullet list: * list item 1 * list item 1.1 * list item 1.2 * list item 2 :ref:`numbered-lists` ===================== .. important:: Always add blank line before and after list! some text #. list item 1 #. list item 2 some text .. code-block:: rest some text #. list item 1 #. list item 2 some text :ref:`Code Blocks ` ===================================================================== .. important:: Use syntactically correct code in your codeblocks. Code Block Directive -------------------- **How it looks:** .. code-block:: php $a = 'hello'; $b = 'something'; Source: .. code-block:: rest :linenos: .. 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'; :ref:`Inline Code, Textroles ` ========================================= For inline code or for other semantic markup of special texts, use textroles. Examples: #. :php:`$result = $a + 23;` (PHP snippet) #. :typoscript:`lib.hello.value = Hello World!` (TypoScript snippets) #. :file:`/etc/passwd` (file) #. :kbd:`ctrl` + :kbd:`s` (keyboard strokes) Source (inline text with textroles): .. code-block:: rest :linenos: :php:`$result = $a + 23;` :typoscript:`lib.hello.value = Hello World!` :file:`/etc/passwd` :kbd:`ctrl` + :kbd:`s` :ref:`Bold & Italic ` ======================================= Normal text, **bold text** and *italic text*. Source (bold & italic): .. code-block:: rest Normal text, **bold text** and *italic text*. :ref:`Images ` =========================== .. image:: ../images/a4.jpg :class: with-shadow Source (image): .. code-block:: rest .. image:: ../images/a4.jpg :class: with-shadow Another example: .. code-block:: rest .. image:: ../images/a4.jpg :class: with-shadow :target: https://typo3.org :alt: alt text :width: 100px .. seealso:: * :ref:`images` :ref:`YouTube Videos ` =============================== .. youtube:: wNxO-aXY5Yw Source (YouTube): .. code-block:: rest .. youtube:: wNxO-aXY5Yw :ref:`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 (:rst:`::`) 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:* .. rst-class:: bignums 1. Embed an image Source:: ../images/a4.jpg :class: with-shadow 2. 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:* .. rst-class:: bignums-xxl 1. Embed an image Source:: ../images/a4.jpg :class: with-shadow 2. Two Do something else ... :ref:`Tips, Hints, Important ` (Admonitions) ============================================================== .. --------------------------------------------------------------- tip: This directive will display the following indented text as text with a green box (as styled by our sphinx template). --------------------------------------------------------------- .. tip:: To look at the reST source of this rendered page, scroll to the bottom and click on "View page source". Source (tip): .. code-block:: rst .. tip:: To look at the reST source of this rendered page, scroll to the bottom and click on "View page source".