1.9. Explicit Markup

“Explicit markup” is used in reStructuredText for most constructs that need special handling, such as footnotes, specially-highlighted paragraphs, comments, and generic directives.

An explicit markup block begins with a line starting with two dots followed by whitespace (".. ") and is terminated by the next paragraph at the same level of indentation. There needs to be a blank line between explicit markup and normal paragraphs. This may all sound a bit complicated, but it is intuitive enough when you write it.

1.9.1. Comments

Every explicit markup block which is not a valid markup construct (like the footnotes above) is regarded as a comment.

However, it must have some text in the ".. " line, otherwise it is ignored, and content will be displayed (indented).

the example

.. This is a comment
..
   _so: is this!
..
   [and] this!
..
   this:: too!
..
   |even| this:: !

1.9.2. Directives

Directives are generic blocks of explicit markup. Besides Roles, it is one of the extension mechanisms of reStructuredText, and Sphinx makes heavy use of it. Basically, a directive consists of a name, arguments, options and content. Keep this terminology in mind, it is used in one of the next chapter describing custom directives.

the example

.. cpp:function:: char* foo(x)
                  char* foo(y, z)
   :noindexentry:

   Return a line of text input from the user.

which gives

char *foo(x)

char *foo(y, z)

Return a line of text input from the user.

.. cpp:function:: is the directive name. It is given two arguments here, the remainder of the first line and the second line, as well as one option :noindexentry:. As you can see, options are given in the lines immediately following the arguments and indicated by the colons.

The directive content follows after a blank line and is indented relative to the directive start.

If you want to suppress the addition of an entry in the shown index, you can give the directive option flag :noindexentry:. If you want to typeset an object description, without even making it available for cross-referencing, you can give the directive option flag :noindex: (which implies :noindexentry:).

Hint

As far as possible, all examples in this document use the :noindexentry: option to keep the automatically created index as clean as possible but still be able to reference it.

1.9.3. Footnotes

For footnotes, use [#]_ to mark the footnote location, and add the footnote body at the bottom of the document after a “Footnotes” rubric heading.

the example

Lorem ipsum [#]_ dolor sit amet ... [#]_

.. rubric:: Footnotes

.. [#] Text of the first footnote.
.. [#] Text of the second footnote.

which gives

Lorem ipsum 1 dolor sit amet … 2

Footnotes

1

Text of the first footnote.

2

Text of the second footnote.

You can also explicitly number the footnotes for better context.

1.9.4. Citations

Citations are identical to footnotes except that they use only non-numeric labels such as [note]_ or [GVR2001]_. Citation labels are simple reference names (case-insensitive single words consisting of alphanumerics plus internal hyphens, underscores, and periods; no whitespace). Citations may be rendered separately and differently from footnotes.

the example

Here is a citation reference: [CIT2002]_.

.. [CIT2002] This is the citation. It's just like a footnote,
   except the label is textual.

which gives

Here is a citation reference: [CIT2002].

CIT2002

This is the citation. It’s just like a footnote, except the label is textual.

To use a professional bibliography, you should use the Sphinx extension BibTeX Citations.