.. _page title: ========================= reStructuredText Markup ========================= .. This document is duplicated within the Moin2 repository as `docs/user/rest.rst` and `src/moin/help/help-en/rst.data`. Please update both. Do not include features only supported by Sphinx. .. contents:: :depth: 3 This document is an introduction to the `reStructuredText`_ (rST) markup language. It demonstrates the features of the Moin2 rST support. For details, follow the links to the `reStructuredText Markup Specification`_. There are two HTML version of this document: one is part of the Wiki Help generated by Moin, the other belongs to the _`external documentation` generated by Sphinx_. Some features and links only work in the Wiki Help page. Section Headings ================ *Section headings* are underlined (or over- and underlined) with a printing nonalphanumeric 7-bit ASCII character (`details`__). __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#sections * The underline/overline must be at least as long as the title text. * A blank line after a heading is optional. * Instead of a fixed order of heading adornment styles, the level is determined by their order in the document: The first adornment style encountered is registered as page title style (

in HTML), the second style is assigned to level 2, the third style to level 3, and so on.\ [#fn:document-title]_ * Once established, adornment styles must be consistent. Skipping a heading level results in a parsing error. .. list-table:: :header-rows: 1 * - Markup - Result * - :: ======= Level 1 ======= - The first encountered style becomes the `page title`_ (if it is unique)\ [#fn:document-title]_. * - :: Level 2 ======= - See the heading of `this section
`__. * - :: Level 3 ------- Level 4 ******* Level 5 ::::::: Level 6 +++++++ - See `below`__. (Section headings may not be nested in body elements like lists_, tables_, or admonitions_. You may use rubrics_ for informal headings outside the main document structure.) __ Level 3 ------- Level 4 ******* Level 5 ::::::: Level 6 +++++++ .. [#fn:document-title] If any visible content appears before the first heading on a page or if the adornment style is used more than once, the first heading is set to level 2 and all subsequent headings are demoted by one level (details__). __ https://docutils.sourceforge.io/docs/api/transforms.html#doctitle Thematic Breaks =============== .. _transition example: A *thematic break* represents a change in subject or emphasis. It is typically rendered as additional space between paragraphs, often with a horizontal line, a row of asterisks, or some other ornament. See below for an example. -------------------------------------------------------------------------- HTML represents a *thematic break* with the ``
`` element. In reStructuredText, this element is called *transition* and represented by a horizontal line of 4 or more repeated punctuation characters (details__). __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html #transitions .. list-table:: :header-rows: 1 * - Markup - Result * - :: See below for an example. ------------------------ HTML represents […] - See `above `__. (Transitions may not be nested in body elements like lists_, tables_, admonitions_, ...). Text Formatting =============== *Inline markup* can be applied to words or phrases within a text block to format text (`details `__). * Less common styles are obtained via `interpreted text roles`_. * reStructuredText does not support ``***Nested** inline markup*``. [#]_ .. list-table:: :header-rows: 1 * - Markup - Result - Notes * - ``*emphasis*`` - *emphasis* - * - ``**strong emphasis**`` - **strong emphasis** - * - ````inline \literal\```` - ``inline \literal\`` - In `literal context`_, `backslashes `__ have no special meaning. * - ```Hamlet``` - `Hamlet` - `Interpreted text`_. The `default text role`_ is configurable, it defaults to the "title" role (see below). * - ``:ab:`abbr.``` - :ab:`abbr.` - Abbreviations, can be styled with custom CSS. * - ``:code:`answer = 42``` - :code:`answer = 42` - For syntax highlight, see `custom text roles`_. * - ``:sub:`sub`\ script`` - :sub:`sub`\ script - Character-level markup … * - ``:sup:`super`\ script`` - :sup:`super`\ script - … requires `escaped spaces `__. .. _"title" role: * - ``:title:`Moin``` - :title:`Moin` - The title of a creative work (book, opera, coding project, etc.) Analog to HTML . This is the initial `default text role`_. .. [#] This is a longstanding Docutils TODO issue. Additional Text Roles --------------------- Including__ the "html-roles.txt" `standard definition file`_ adds roles that correspond to HTML elements representing `edits to the document`__ and `text-level semantics`__. __ include_ __ https://html.spec.whatwg.org/multipage/edits.html __ https://html.spec.whatwg.org/multipage/text-level-semantics.html .. include:: =================== =============== ==================================== Markup Result Notes =================== =============== ==================================== ``:del:`removed``` :del:`removed` removed content ``:ins:`inserted``` :ins:`inserted` editional additions ``:b:`keyword``` :b:`keyword` highlight :b:`key words` without marking them up as important ``:dfn:`dfn``` :dfn:`dfn` the defining instance of a term ``:i:`rôle``` :i:`rôle` alternate voice ``:kbd:`Ctrl X``` :kbd:`Ctrl X` user input ``:mark:`up``` :mark:`up` highlight a :mark:`run of text` ``:q:`Tagline!``` :q:`Tagline!` content quoted from another source ``:s:`strike``` :s:`strike` text that is inaccurate or no longer relevant ``:samp:`Ready!``` :samp:`Ready!` computer output ``:small:`print``` :small:`print` side comments ``:u:`anotation``` :u:`anotation` unarticulated annotations of, e.g, :u:`mispellings` ``:var:`n``` :var:`n` variables =================== =============== ==================================== Custom Text Roles ----------------- *Custom interpreted text roles* can be used to attach CSS class values to inline text and set the code language for syntax highlight (`details <"role" directive_>`__). .. list-table:: :header-rows: 1 * - Markup - Result - Notes * - :: .. role:: green ``A :green:`dragon`.`` - .. role:: green A :green:`dragon`. - Moin pre-defines some `CSS classes`__ for background color. Text with other classes can be styled with custom CSS. __ `Moin CSS classes`_ * - :: .. role:: blue(emphasis) ``The `Norwegian`:blue:.`` - .. role:: blue(emphasis) The `Norwegian`:blue:. - Custom roles may be based on standard roles. * - :: .. role:: em-tt(emphasis) :class: monospaced ``*emphasis* and :em-tt:`emphasis monospace``` - .. role:: em-tt(emphasis) :class: monospaced *emphasis* and :em-tt:`emphasis monospace` - Custom roles may be used as surrogate for nested inline markup. * - :: .. role:: tex(code) :language: latex ``:tex:`\frac{\pi}{4}``` - .. role:: tex(code) :language: latex :tex:`\frac{\pi}{4}` - There is highlight support for many languages__. See also `code blocks`_. __ https://pygments.org/languages/ * The examples rely on `Moin CSS classes`_ missing in the `external documentation`_. Hyperlinks ========== Hyperlinks connect a *hyperlink reference* to a matching *hyperlink target* (`details `__). * Matching of named_ references and targets is done after normalizing whitespace and case. * Anonymous_ references and targets are matched according to their order. * The target can also be embedded_ in the reference. Internal Links -------------- **Page-internal links** point to an anchor (named element or anonymous target) in the same document. .. list-table:: :header-rows: 1 * - Markup - Result - Notes * - .. _named: ``Simple_ reference and _`simple` inline target``. - Simple_ reference and _`simple` inline target. - See `simple reference names`_ and `inline targets`_. * - ``Links to a `named paragraph`_, the `MoinMoin logo`_, and a table named `fruit salad`_.`` - Links to a `named paragraph`_, the `MoinMoin logo`_, and a table named `fruit salad`_. - Put `phrase references`_ in backticks. * - ``It's `easy `__.`` - It's `easy `__. - Custom link text with `embedded alias`_. * - .. _anonymous: ``Easy__ as pie.`` :: __ simple_ - Easy__ as pie. __ simple_ - Custom link text with `anonymous reference`_ and anonymous `indirect target`_. * - ``Section headings_ are implicit targets.`` - `Section headings`_ are implicit targets. - For details, see `implicit targets`_. * - :: .. _named paragraph: This paragraph is a target. - .. _named paragraph: This paragraph is a target. - `Empty hyperlink targets`_ mark the following element. .. _Wiki-internal links: The Moin rST converter interprets named hyperlink references without matching target as **Wiki-internal links** (whitespace is normalized). * Caution! `Explicit targets`_, `inline targets`_ and `section headings`_ with the same name take precedence! * Docutils and Sphinx report unknown target names as errors. ======================== =================== ============================ Markup Result Notes ======================== =================== ============================ ``Home_`` Home_ item in default namespace ```users/Home`_`` `users/Home`_ item in specified namespace ```../moin`_`` `../moin`_ sibling item in current namespace ```../moin#Linking`_`` `../moin#Linking`_ fragment of a sibling item ```/Subitem Example`_`` `/Subitem Example`_ subitem of the current item ======================== =================== ============================ Wiki-internal link targets may also be specified as `URI References`_. * The `syntax for Wiki-internal links`__ differs from POSIX *path* syntax! __ https://moin-20.readthedocs.io/en/latest/user/namespaces.html#url-layout .. list-table:: :header-rows: 1 * - Markup - Result - Notes * - ````__`` - ``__ - item in default namespace (as embedded URI reference) * - ```My Castle `__`` - `My Castle `__ - ... with custom text * - ````__`` - ``__ - item in specified namespace * - ```Moin markup`__`` :: __ ../moin - `Moin markup`__ __ ../moin - sibling item (in an `anonymous target`_) * - ``|MoinMoin|_ markup`` :: .. _MoinMoin: ../moin - |MoinMoin|_ markup .. _MoinMoin: ../moin - ... as image_ link via `substitution reference`_ The substitution text becomes the `reference name`_, an `explicit target`_ maps it to a URI reference. * - ```sub-item `__`` - `sub-item `__ - subitem (with custom text) In `URI context`_, whitespace is removed by default. Use an `escaped space `__ or percent encoding. External Links -------------- *External* links point to an external resource (specified as URI). .. list-table:: :header-rows: 1 * - Markup - Result - Notes * - ``Moin (https://moinmo.in/) supports rST.`` - Moin (https://moinmo.in/) supports rST. - URIs and email addresses are turned into `standalone hyperlinks`_. * - ``Moin_ supports rST.`` :: .. _moin: https://moinmo.in/ - Moin_ supports rST .. _moin: https://moinmo.in/ - A named `hyperlink reference`_ and matching `external target`_ keep the details out of the text flow. * - .. _embedded: ```Moin `__ supports rST.`` - `Moin `__ supports rST. - Reference with custom link text and `embedded URI`_. * - ```Moin supports rST`__.`` :: __ https:// moin-20.readthedocs.io/ en/latest/user/rest.html - `Moin supports rST`__. __ https:// moin-20.readthedocs.io/ en/latest/user/rest.html - `Anonymous references`_ and targets are handy for verbose or repeated link texts. * - ``:RFC:`6921``` - :RFC:`6921` - `"rfc-reference" role`_ * - ``:PEP:`01``` - :PEP:`01` - `"pep-reference" role`_ .. TODO: interwiki link currently fails: * - ```InterWiki page on MeatBall `__`` - `InterWiki page on MeatBall `__ - InterWiki page on MeatBall. [#]_ .. [#] Interwiki links work only in Moin and only after configuring. Blockquotes =========== An indented text block is interpreted as a *blockquote*, a text part quoted from another source (details__). __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html #block-quotes * Blockquotes may contain arbitrary body elements. * To add an attribution_, append a paragraph preceded by "``--``" or an em-dash. .. list-table:: :header-rows: 1 * - Markup - Result * - :: preceding paragraph It is my business to know things. That is my trade. -- Sherlock Holmes succeeding paragraph - preceding paragraph It is my business to know things. That is my trade. -- Sherlock Holmes succeeding paragraph Lists ===== reStructuredText provides syntax for `unordered lists`_, `ordered lists`_, `definition lists`_, `field lists`_, and `option lists`_. See `line blocks`_ for the rST alternative to a "bulletless" list. * Lists must be separated from other body elements by blank lines. Blank lines between list items are optional. * The list marker must **not** be indented. * List items may contain arbitrary body elements. Unordered Lists --------------- A text block which begins with a ``*``, ``+``, ``-``, ``•``, ``‣``, or ``⁃``, followed by whitespace, is a *bullet list* item (`details `__). * Item content must be left-aligned and indented relative to the marker. * Content may start on the same line as the marker or on the next line. * The first content line sets the `indentation level`_ for this item. Sub-items 2.1 to 2.2.2 show some valid input variants. .. list-table:: :header-rows: 1 * - Markup - Result * - :: - item 1 - item 2 - item 2.1 - item 2.2 - item 2.2.1 - item 2.2.2 - item 3 - - item 1 - item 2 - item 2.1 - item 2.2 - item 2.2.1 - item 2.2.2 - item 3 * - :: Attention! * Indented lists * are nested in a block quote. - Attention! * Indented lists * are nested in a block quote. Ordered Lists --------------- *Ordered lists* are similar to `unordered lists`_, but use *enumerators* instead of bullets (`details `_). * Ordered lists can be automatically enumerated using the ``#`` character. * The first enumerator determines the *enumeration sequence*, *formatting type* [#]_, and *start value*. Sub-items 2.1 to 2.2.2 show some valid indentation variants. .. list-table:: :header-rows: 1 * - Markup - Result * - :: #. item 1 #. item 2 (a) item 2.1 (#) item 2.2 i) item 2.2.1 #) item 2.2.2 #. item 3 - #. item 1 #. item 2 (a) item 2.1 (#) item 2.2 i) item 2.2.1 #) item 2.2.2 #. item 3 * - :: 4) item 4 with C. uppercase #. letters and IV) custom #) start values - 4) item 4 with C. uppercase #. letters and IV) custom #) start values .. [#] HTML output ignores the formatting style and always uses a trailing period. Definition Lists ---------------- *Definition lists* are formed by a *term* on one line followed by an indented *definition* or *description* on the next line (details__). __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html #definition-lists .. list-table:: :header-rows: 1 * - Markup - Result * - :: term Description term 2 : classifier Optional *classifiers* may be appended to the term. - term Description term 2 : classifier Optional *classifiers* may be appended to the term. Field Lists ----------- *Field lists* are mappings from field names to field bodies (details__). __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html #field-lists * Field bodies may start on the same line as the field name or on the next line. * Field list syntax is also used for options in directives_ and for `bibliographic fields`_. .. list-table:: :header-rows: 1 * - Markup - Result * - :: :Version: 2.0b2 :Release Date: 2001-08-16 :Authors: - Joe Doe - Erika Mustermann - Jan Kowalski - :Version: 2.0b2 :Release Date: 2001-08-16 :Authors: - Joe Doe - Erika Mustermann - Jan Kowalski Option lists ------------ *Option lists* document the options of a command-line program (`details