3. Explicit Directive Quick Notes

3.1. Comments

Arbitrary indented text may follow the explicit markup start and will be processed as a comment element, and not included in the output.

..
   _This: is a comment.

..
   [and] this.

..
   this:: too.

..
   |even| this:: .

.. [this] however, is a citation.

See comments for more information.

3.2. QuickNote: Explicit Directive

.. directive_name::    <-- two colons
    :config_option:    <-- config options when available

    text block the directive applies to

3.5. Footnotes

Lorem ipsum\ [3]_ dolor sit amet, consectetur adipiscing elit\ [#]_, sed do eiusmod
tempor incididunt [#unique_name]_ ut labore et dolore magna aliqua.  Ut enim\ [*]_ ad
minim veniam, quis nostrud...

.. rubric:: Footnotes   <-- optional

.. [citation_label]
    Footnote text

.. [3]             <-- manually-numbered footnote
.. [#]             <-- auto-numbered footnote (starts at 1)
.. [#unique_name]  <-- auto-numbered label
.. [*]             <-- auto-symbol footnote

Note that the reference must be preceded by a space. If the hyperlinked footnote symbol should be against the word before it, then escape the preceeding space like this: footnoted topic\ [1]_.

Auto-numbered label footnotes are used when a footnote reference needs to be used more than once.

Auto-numbered and auto-symbol footnotes rely upon the sequence in which the footnotes actually appear. To avoid maintenance difficulty (e.g. when paragraphs are moved around in a document), use manually-numbered footnotes or auto-numbered labels.

Footnote text must be consistently indented and left-aligned. The first body element within a footnote may begin on the same line as the footnote label. However, if the first element fits on one line and the indentation of the remaining elements differ, the first element must begin on the line after the footnote label. Otherwise, the difference in indentation will not be detected.

Footnotes may occur anywhere in the document, not only at the end. Where and how they appear in the processed output depends on the processing system.

3.6. Citations

Citations are different from footnotes in that the first character after the first ‘[’ is something other than a number or # or *.

Lorem ipsum [CIT2002]_ dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud...

.. [CIT2002] Book or article reference, URL or whatever.
    More text indented when additional text is needed.

3.7. Substitutions

reStructuredText supports “substitutions” (ref), which are pieces of text and/or markup referred to in the text by |name|. They are defined like footnotes with explicit markup blocks, like this:

.. |unique_name| replace:: replacement *text*

or this:

.. |caution| image:: warning.png
         :alt: Warning!

or this:

.. |aacute| unicode:: U+000E1 .. LATIN SMALL LETTER A WITH ACUTE ACCENT MARK
    :trim:     <-- optional, causes whitespace on either side to be closed.
                   This       :  Lorem ipsum [aacute] dolor sit amet
                   Rather than:  Lorem ipsum\ [aacute]\ dolor sit amet

See reStructuredText reference for substitutions for details.

If you want to use some substitutions for all documents, put them into rst_prolog or rst_epilog (a Sphinx variable in the doc project’s conf.py file) or put them into a separate file and include it into all documents you want to use them in, using the .. include:: directive. (Be sure to give the include file a file name extension differing from that of other source files, to avoid Sphinx finding it as a standalone document.)

Sphinx defines some default substitutions.