# The Docutils Document Tree

A Guide to the Docutils Generic DTD

Author:

  David Goodger

Contact:
  docutils-develop@lists.sourceforge.net
Revision:
  10268
Date:
  2025-12-02
Copyright:
  This document has been placed in the public domain.

This document describes the XML data structure of Docutils documents: the relationships and semantics of elements and attributes.

The Docutils document structure is formally defined by the Docutils Generic XML document type definition (DTD) docutils.dtd, which is the definitive source for details of element structural relationships. It should be used in conjunction with the description of the semantics of the elements, attributes, and parameter entities in this document.

The reader is assumed to have some familiarity with XML or SGML, and an understanding of the data structure meaning of "tree". For a list of introductory articles, see, e.g., Introducing the Extensible Markup Language (XML).

Docutils implements the Document tree data structure in the Python module docutils.nodes. For details, see its internal API documentation ("docstrings") and the source nodes.py.

The reStructuredText markup language is used for illustrative examples throughout this document. For a gentle introduction, see A ReStructuredText Primer. For complete technical details, see the reStructuredText Markup Specification.

## Element Hierarchy

The Docutils document model uses strict element content models.

Below is a simplified diagram of the hierarchy of elements in the Docutils document tree structure. An element may contain elements immediately below it in the diagram. Element types in square brackets indicate recursive or one-to-many relationships: structural elements (sections) may contain sub-sections, some body elements may contain other body elements, etc. The element reference details valid parents and children for each element.

root element (<document>)
[structural elements] |
| structural subelements
| bibliographic elements | decorative elements
[body elements]
[body subelements] |  |
| [inline elements]
text

Every element has a unique structure and semantics, but elements may be classified into general categories according to their place and role in the document. Some elements belong to more than one category.

Alternatively, we may classify elements by their content model:

Compound elements
  may contain child elements but no text data.
  Examples: <bullet_list>, <footnote>, <table>
Simple elements
  may contain text data.
  Most simple elements have a mixed content model. However, only inline elements may be intermixed with text (%text.model). [1]
  Examples: <paragraph> (mixed), <literal_block> (text-only)
Empty elements
  contain neither child elements nor text.
  Category members: <colspec>, <image>, <meta>, <pending>, <transition>

[1]

This is unlike the much looser HTML document model, where paragraphs and text data may occur at the same level.

### Element Categories

#### Root Element

Every Docutils document contains exactly one root element. The root element has no parent. It may contain structural elements, all structural subelements, and body elements. It does not directly contain text.

Category members:

  <document>

Docutils class:

  nodes.Root

#### Structural Elements

Structural elements group other elements to provide a document structure. They are child elements of the root element or other structural elements. Structural elements may contain specific structural elements, structural subelements, or body elements.

Category members:

  <section>, <sidebar>, <topic>

Docutils class:

  nodes.Structural

Parameter Entities:

  %structure.model directly or indirectly includes all structural elements.

#### Structural Subelements

Structural subelements are child elements of the root element or specific structural elements. Their content model varies (see the respective element reference section for details).

Category members:
  empty:

    <meta>, <transition>

  simple:

    <title>, <subtitle>

  compound:

    <decoration>, <docinfo>

Docutils class:

  nodes.SubStructural

#### Decorative Elements

Decorative elements are used to generate page headers and footers. They are child elements of <decoration> and contain body elements.

Category members:

  <footer>, <header>

Docutils class:

  nodes.Decorative

#### Bibliographic Elements

Bibliographic elements store document meta-data like title or author. They are child elements of <docinfo>. Their content model varies (see the respective element reference section).

Category members:
  simple:

    <address>, <author>, <contact>, <copyright>, <date>, <organization>, <revision>, <status>, <version>

  compound:

    <authors>, <field>

Docutils class:

  nodes.Bibliographic

Parameter entity:

  %bibliographic.elements

#### Body Elements

Body elements are children of the root element, structural elements, or compound body elements. Simple body elements may contain text and inline elements or text data only (see the respective element reference section). Compound body elements may contain body subelements or further body elements.

Category members:
  empty:

    <image> , <pending>, <target>

  simple:

    <comment>, <doctest_block>, <literal_block>, <math_block>, <paragraph>, <raw>, <reference>, <rubric>, <substitution_definition>

  compound:

    <admonition>, <attention>, <block_quote>, <bullet_list>, <caution>, <citation>, <compound>, <container>, <danger>, <definition_list>, <enumerated_list>, <error>, <field_list>, <figure>, <footnote>, <hint>, <important>, <line_block>, <note>, <option_list>, <system_message>, <table>, <tip>, <warning>

Docutils class:

  nodes.Body

Parameter Entities:

  %body.elements directly includes all body elements, %structure.model indirectly includes all body elements.

#### Body Subelements

Body subelements always occur within specific parent elements (e.g. <bullet_list> contains <list_item>), never at the body element level (beside paragraphs, etc.). Body subelements may be compound elements (containing body elements or further body subelements) or simple elements.

Category members:
  empty:

    <colspec>

  simple:

    <attribution>, <caption>, <classifier>, <field_name>, <label>, <line>, <option_argument>, <option_string>, <term>, <title>

  compound:

    <definition>, <definition_list_item>, <description>, <entry>, <field>, <field_body>, <legend>, <list_item>, <option>, <option_group>, <option_list_item>, <row>, <tbody>, <tgroup>, <thead>

Docutils class:

  nodes.Part

#### Inline Elements

Inline elements are contained within simple body elements or other inline elements. Inline elements are simple elements: All inline elements may contain text data, most inline elements may also contain further inline elements.

Category members:

  <abbreviation>, <acronym>, <citation_reference>, <emphasis>, <footnote_reference>, <generated>, <image>, <inline>, <literal>, <math>, <problematic>, <raw>, <reference>, <strong>, <subscript>, <substitution_reference>, <superscript>, <target>, <title_reference>

Docutils class:

  nodes.Inline

Parameter Entities:

  %inline.elements directly includes all inline elements, %text.model indirectly includes all inline elements.

## Element Reference

### Introduction

Each element in the Docutils Generic DTD is described in its own section below. Each section contains the following items:

- Summary description (up to two sentences).

- Details (of element relationships and semantics):

  Category:

    One or more references to the element categories in the Element Hierarchy above. Some elements belong to more than one category.

  Analogues:

    Analogous elements in well-known document models such as HTML [html.spec] or DocBook [tdg5.1]. Describes similarities and differences.

  Processing:

    Formatting or rendering recommendations for the element.

  Parents:

    Elements which may contain the element.

  Children:

    Elements which may occur within the element. Optionally followed by the formal XML content model from the Docutils Generic DTD.

  Attributes:

    XML Attributes that are defined for this element.

  Parameter Entities:

    Parameter entities which directly or indirectly include the element (if applicable and not already implied by the element category).

- Additional free text description and explanations (optional).

- Examples: reStructuredText examples are shown along with fragments of the document trees resulting from parsing. Pseudo-XML is used to display the results of parsing and processing.

### <abbreviation>

The <abbreviation> element is an inline element representing an abbreviation, a shortened or contracted form of a word or phrase used to represent the whole.

Category:

  Inline Elements

Analogues:

  <abbreviation> is analogous to the DocBook <abbrev> element. The HTML <abbr> element is used for both, abbreviations and acronyms.

Processing:

  May be used to semantically mark the presence of an abbreviation in the text for styling or scripting purposes. Writers may ignore the element and just render its contents.

Parents:

  all elements employing %text.model in their content models

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

The reStructuredText "abbreviation" role creates an <abbreviation> element:

    :abbreviation:`St` is a common abbreviation for "street".

Pseudo-XML fragment from simple parsing:

    <paragraph>
        <abbreviation>
            St
        is a common abbreviation for "street".

### <acronym>

The <acronym> element is an inline element used to represent an acronym (abbreviation formed by the initial letters of other words).

Category:

  Inline Elements

Analogues:

  <acronym> is analogous to the DocBook <acronym> element. The HTML <abbr> element is used for both, abbreviations and acronyms.

Processing:

  May be used to semantically mark the presence of an acronym in the text for styling or scripting purposes. Writers may ignore the element and just render its contents.

Parents:

  all elements employing %text.model in their content models

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

The reStructuredText "acronym" role creates an <acronym> element:

    `WWW`:acronym: is the acronym for the world wide web.

Pseudo-XML fragment from simple parsing:

    <paragraph>
        <acronym>
            WWW
        is the acronym for the world wide web.

### <address>

The <address> element holds the surface mailing address information for the author(s) (individual or group) of the document, or a third-party contact address.

Category:

  Bibliographic Elements

Analogues:

  <address> is analogous to the DocBook <address> element.

Processing:

  As with the <literal_block> element, newlines are significant and must be preserved. However, a monospaced typeface should not be used.

Parents:

  <docinfo>, <authors>

Children:

  text data plus inline elements (%text.model)

Attributes:

  the common attributes and xml:space.

The <address> element is only valid in the bibliographic data (<docinfo>). You may use a <line_block> to format addresses in the document body.

#### Examples

In reStructuredText, "address" is one of the registered bibliographic fields:

    Document Title
    ==============

    :Address: 123 Example Ave.
              Example, EX

Complete pseudo-XML result after parsing and applying transforms:

    <document ids="document-title" names="document title">
        <title>
            Document Title
        <docinfo>
            <address>
                123 Example Ave.
                Example, EX

See <docinfo> for a more complete example, including processing context.

### <admonition>

The <admonition> element is a generic, titled admonition, a distinctive and self-contained notice.

Category:

  Compound Body Elements

Analogues:

  The generic <admonition> has no direct analogues in common DTDs. It can be emulated with primitives and type effects. The specific admonitions <caution>, <note>, <tip>, and <warning> are analogous to the respective DocBook elements.

Processing:

  Rendered distinctly (inset and/or in a box, etc.).

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  <admonition> elements begin with a <title> and may contain one or more body elements.

Attributes:

  only the common attributes.

See also the specific admonition elements <attention> <caution>, <danger>, <error>, <hint>, <important>, <note>, <tip>, and <warning>.

#### Examples

The reStructuredText "admonition" directive creates a generic <admonition> element:

    .. admonition:: By the way...

       You can make up your own admonition too.

Pseudo-XML fragment from simple parsing:

    <admonition class="admonition-by-the-way">
        <title>
            By the way...
        <paragraph>
            You can make up your own admonition too.

### <attention>

The <attention> element is a specific admonition, a distinctive and self-contained notice.

Category:

  Compound Body Elements

Analogues:

  <attention> has no direct analogues in common DTDs. It can be emulated with primitives and type effects.

Processing:

  Rendered distinctly (inset and/or in a box, etc.), with the generated title "Attention!" (or similar).

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  one or more body elements

Attributes:

  only the common attributes.

See also the generic <admonition> and the other specific admonition elements.

#### Examples

A reStructuredText "attention" directive:

    .. Attention:: All your base are belong to us.

Pseudo-XML fragment from simple parsing:

    <attention>
        <paragraph>
            All your base are belong to us.

### <attribution>

The <attribution> element identifies the source of a <block_quote>.

Category:

  Body Subelements (simple)

Analogues:

  <attribution> is analogous to the DocBook <attribution> element.

Processing:

  Placed below the block quote, usually be preceded by a dash, right aligned, or otherwise set apart from the quotation.

Parent:

  <block_quote>

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

The Docutils HTML and LaTeX writers provide the "attribution" setting to configure the formatting of the <attribution>.

#### Examples

See <block_quote>.

### <author>

The <author> element holds the name of the author (or one of the authors) of the document.

Category:

  Bibliographic Elements

Analogues:

  <author> is analogous to the DocBook <personname> element.

Processing:

  see <docinfo>

Parents:

  <docinfo>, <authors>

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

In reStructuredText, "author" is one of the registered bibliographic fields:

    Document Title
    ==============

    :Author: J. Random Hacker

Complete pseudo-XML result after parsing and applying transforms:

    <document ids="document-title" names="document title">
        <title>
            Document Title
        <docinfo>
            <author>
                J. Random Hacker

See <docinfo> for a more complete example, including processing context.

### <authors>

The <authors> element is a container for author information for documents with multiple authors.

Category:

  Bibliographic Elements

Analogues:

  <authors> is analogous to the DocBook <authorgroup> element.

Processing:

  See <docinfo>.

Parent:

  <docinfo>

Children:

  <author>, <organization>, <address>, <contact>:

      ((author, organization?, address?, contact?)+)

Attributes:

  only the common attributes.

#### Examples

In reStructuredText, the "authors" field is one of the registered bibliographic fields:

    Document Title
    ==============

    :Authors: J. Random Hacker; Jane Doe

Complete pseudo-XML result after parsing and applying transforms:

    <document ids="document-title" names="document title">
        <title>
            Document Title
        <docinfo>
            <authors>
                <author>
                    J. Random Hacker
                <author>
                    Jane Doe

There is currently no way to represent an individual author's <organization>, <address>, or <contact> in a reStructuredText "authors" field.

See <docinfo> for a more complete example, including processing context.

### <block_quote>

The <block_quote> element is used for quotations set off from the main text (standalone).

Category:

  Compound Body Elements

Analogues:

  <block_quote> is analogous to the <blockquote> element in both HTML and DocBook.

Processing:

  <block_quote> elements serve to set their contents off from the main text, typically with indentation and/or other decoration.

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  body elements followed by an optional <attribution>

Attributes:

  only the common attributes.

#### Examples

In reStructuredText, an indented text block without preceding markup is a block quote:

    As a great palaeontologist once said,

        This theory, that is mine, is mine.

        -- Anne Elk (Miss)

Pseudo-XML fragment from simple parsing:

    <paragraph>
        As a great palaeontologist once said,
    <block_quote>
        <paragraph>
            This theory, that is mine, is mine.
        <attribution>
            Anne Elk (Miss)

The "epigraph" and "pull-quote" directives produce <block_quote> elements, too.

### <bullet_list>

The <bullet_list> element contains <list_item> elements which are uniformly marked with bullets. Bullets are typically simple dingbats (symbols) such as circles and squares.

Category:

  Compound Body Elements

Analogues:

  <bullet_list> is analogous to the HTML <ul> element [2] and to the DocBook <itemizedlist> element.

Processing:

  Each list item should begin a new vertical block, prefaced by a bullet/dingbat.

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  one or more <list_item> elements

Attributes:

  the common attributes and bullet.

[2]

HTML's <ul> is short for "unordered list", which we consider to be a misnomer. "Unordered" implies that the list items may be randomly rearranged without affecting the meaning of the list. Bullet lists are often ordered; the ordering is simply left implicit.

#### Examples

A reStructuredText bullet list:

    - Item 1, paragraph 1.

      Item 1, paragraph 2.

    - Item 2.

Pseudo-XML fragment from simple parsing:

    <bullet_list bullet="-">
        <list_item>
            <paragraph>
                Item 1, paragraph 1.
            <paragraph>
                Item 1, paragraph 2.
        <list_item>
            <paragraph>
                Item 2.

See <list_item> for another example.

### <caption>

The <caption> element represents the title/caption of a <figure>. [3]

Category:

  Body Subelements (simple)

Analogues:

  The <caption> element is analogous to the DocBook <title> element (but specific to a <figure>). The HTML <figcaption> element combines <caption> and <legend>.

Processing:

  Placed above, below, or besides the image it describes. Often preceded by a figure number. May be repeated in a generated "list of figures".

Parent:

  <figure>

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

See <figure>.

[3]

The title/caption of a <table> is represented by a <title> element.

### <caution>

The <caution> element is a specific admonition, a distinctive and self-contained notice. See also the generic <admonition> and the other specific admonition elements.

Category:

  Compound Body Elements

Analogues:

  <caution> is analogous to the DocBook <caution> element.

Processing:

  Rendered distinctly (inset and/or in a box, etc.), with the generated title "Caution" (or similar).

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  one or more body elements

Attributes:

  only the common attributes.

#### Examples

A reStructuredText "caution" directive:

    .. Caution:: Don't take any wooden nickels.

Pseudo-XML fragment from simple parsing:

    <caution>
        <paragraph>
            Don't take any wooden nickels.

### <citation>

The <citation> element contains a description of an external bibliographic source. It is usually paired with one or more <citation_reference> elements that represent corresponding reference marks in the running text.

Category:

  Compound Body Elements

Analogues:

  <citation> is analogous to the DocBook <bibliomixed> element. [4]

  The "doc-biblioentry" DPub ARIA role (deprecated in version 1.1) can be used to mark a conforming HTML emulation. The corresponding type in the EPUB 3 Structural Semantics Vocabulary is "biblioentry".

Processing:

  Formatted as entry in a bibliography or similar to a <footnote>.

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  <citation> elements begin with a <label> and contain body elements:

      (label, (%body.elements;)+)

Attributes:

  the common attributes and backrefs.

[4]

The DocBook <citation> element resembles a <citation_reference>.

#### Example

See <citation_reference>.

### <citation_reference>

The <citation_reference> element represents a cross reference to a <citation>.

Category:

  Inline Elements

Analogues:

  The <citation_reference> element is analogous to the DocBook <citation> element. There is no equivalent in HTML. The <a> element can be used to provide a link to the corresponding citation.

Processing:

  Typically enclosed in square brackets.

Parents:

  all elements employing %text.model in their content models

Children:

  only text data

Attributes:

  refid, refname, and the common attributes.

#### Example

reStructuredText syntax for citation references is similar to a footnote reference except for the use of a simple reference name instead of a numerical or symbolic label:

    For details on brontosauruses, see [Elk:70]_.

    .. [Elk:70] `My Theory on Brontosauruses`,
                Anne Elk, London, 1972.

Pseudo-XML fragment simple parsing:

    <paragraph>
        For details on brontosauruses, see
        <citation_reference ids="citation-reference-1" refname="elk:70">
            Elk:70
        .
    <citation ids="elk-70" names="elk:70">
        <label>
            Elk:70
        <paragraph>
            <title_reference>
                My Theory on Brontosauruses
            ,
            Anne Elk, London, 1972.

The references.Footnotes Docutils transform resolves this to:

    <paragraph>
        For details on brontosauruses, see
        <citation_reference ids="citation-reference-1" refid="elk-70">
            Elk:70
        .
    <citation backrefs="citation-reference-1" ids="elk-70" names="elk:70">
        <label>
            Elk:70
        <paragraph>
            <title_reference>
                My Theory on Brontosauruses
            ,
            Anne Elk, London, 1972.

### <classifier>

The <classifier> element contains the classification or type of the <term> being defined in a <definition_list>. For example, it can be used to indicate the type of a variable.

Category:

  Body Subelements (simple)

Analogues:

  <classifier> has no direct analogues in common DTDs. It can be emulated with primitives or type effects.

Processing:

  see <definition_list_item>

Parent:

  <definition_list_item>

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

A reStructuredText definition list with classifiers:

    name : string
        Customer name.
    i : int
        Temporary index variable.

Pseudo-XML fragment from simple parsing:

    <definition_list>
        <definition_list_item>
            <term>
                name
            <classifier>
                string
            <definition>
                <paragraph>
                    Customer name.
        <definition_list_item>
            <term>
                i
            <classifier>
                int
            <definition>
                <paragraph>
                    Temporary index variable.

### <colspec>

The <colspec> element contains specifications for a column in a <table>. It is defined in the Exchange Table Model.

Category:

  Body Subelements (empty)

Analogues:

  <colspec> is analogous to the DocBook <colspec> element. The HTML <col> element is related but has different semantics.

Processing:

  See colspec in the Exchange Table Model.

Parent:

  <tgroup>

Children:

  none (empty)

Attributes:

  The Exchange Table Model defines the attributes align, char, charoff, colname, colnum, colsep, colwidth, and rowsep. [5] Via the %tbl.colspec.att parameter entity, <colspec> also accepts the common attributes and stub.

  [5]

  Docutils ignores all attributes except colwidth.

#### Examples

See <table>.

### <comment>

The <comment> element is used for explanatory notes that should not be visible in the document rendering.

Category:

  Simple Body Elements

Analogues:

  While most markup languages provide a syntax for comments, the <comment> element has no direct analogues in HTML or DocBook.

Processing:

  Included as comment or skipped in translations to other markup languages. [6] Hidden from the document rendering.

Parents:

  all elements employing %body.elements, %structure.model, or %text.model in their content models

Children:

  only text data

Attributes:

  the common attributes and xml:space.

#### Examples

In reStructuredText, a comment block [7] is started by two full stops. No processing is done on the content but beware of a misinterpretation as explicit markup construct:

    .. This is a *comment*.
    .. [This] is a *citation*.
    ..
       [This] is another *comment*.

Pseudo-XML fragment from simple parsing:

    <comment xml:space="preserve">
        This is a *comment*.
    <citation ids="this" names="this">
        <label>
            This
        <paragraph>
            is a
            <emphasis>
                citation
            .
    <comment xml:space="preserve">
        [This] is another *comment*.

[6]

In Docutils, the "strip_comments" configuration setting triggers the removal of comment elements from the document tree.

[7]

There is no syntax for inline comments in reStructuredText.

### <compound>

The <compound> element combines multiple body elements to a single logical paragraph.

Category:

  Compound Body Elements

Analogues:

  The <compound> element has no direct analogues in common DTDs. In HTML, it can be emulated with <div> and CSS styling. [8]

Processing:

  Typically rendered as multiple distinct text blocks, with the possibility of variations to emphasize their logical unity (cf. the "compound" directive).

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  one or more body elements

Attributes:

  only the common attributes.

[8]

The Docutils counterpart to HTML’s <div> is the <container> element.

#### Examples

The reStructuredText "compound" directive creates a <compound> element:

    .. compound::

       The 'rm' command is very dangerous.  If you are logged
       in as root and enter ::

           cd /
           rm -rf *

       you will erase the entire contents of your file system.

Pseudo-XML fragment from simple parsing:

    <compound>
        <paragraph>
            The 'rm' command is very dangerous.  If you are logged
            in as root and enter
        <literal_block xml:space="preserve">
            cd /
            rm -rf *
        <paragraph>
            you will erase the entire contents of your file system.

### <contact>

The <contact> element holds contact information for the author (individual or group) of the document, or a third-party contact. It is typically used for an email or web address.

Category:

  Bibliographic Elements

Analogues:

  <contact> is analogous to the DocBook <email> element. The HTML <address> element serves a similar purpose.

Processing:

  See <docinfo>.

Parents:

  <docinfo>, <authors>

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

In reStructuredText, "contact" is one of the registered bibliographic fields:

    Document Title
    ==============

    :Contact: jrh@example.com

Complete pseudo-XML result after parsing and applying transforms:

    <document ids="document-title" names="document title">
        <title>
            Document Title
        <docinfo>
            <contact>
                <reference refuri="mailto:jrh@example.com">
                    jrh@example.com

See <docinfo> for a more complete example, including processing context.

### <container>

The <container> element groups multiple body elements for user- or application-specific purposes.

Category:

  Compound Body Elements

Analogues:

  The <container> element is analogous to the HTML <div> element or the SVG <g> element.

Processing:

  Can be used for styling or scripting purposes. An example is a frame or background colour based on the value of the classes attribute.

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  one or more body elements

Attributes:

  only the common attributes.

#### Examples

The reStructuredText "container" directive creates a <container> element:

    .. container:: green boxed-equation

       .. math:: -1^2 = 1

       This paragraph is in the box, too.

Pseudo-XML fragment from simple parsing:

    <container classes="framed square">
        <math_block xml:space="preserve">
            -1^2 = 1
        <paragraph>
            This paragraph is in the box, too.

The HTML output can be placed in a common box with the custom CSS rule

    div.framed {border: solid;
             padding: 1em;}

### <copyright>

The <copyright> element contains the document's copyright statement.

Category:

  Bibliographic Elements

Analogues:

  <copyright> is analogous to the DocBook <copyright> element.

Processing:

  see <docinfo>

Parent:

  <docinfo>

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

In reStructuredText, "copyright" is one of the registered bibliographic fields:

    Document Title
    ==============

    :Copyright: This document has been placed in the public domain.

Complete pseudo-XML result after parsing and applying transforms:

    <document ids="document-title" names="document title">
        <title>
            Document Title
        <docinfo>
            <copyright>
                This document has been placed in the public domain.

See <docinfo> for a more complete example, including processing context.

### <danger>

The <danger> element is a specific admonition, a distinctive and self-contained notice.

Category:

  Compound Body Elements

Analogues:

  <danger> has no direct analogues in common DTDs. It can be emulated with primitives and type effects.

Processing:

  Rendered distinctly (inset and/or in a box, etc.), with the generated title "!DANGER!" (or similar).

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  one or more body elements

Attributes:

  only the common attributes.

See also the generic <admonition> and the other specific admonition elements.

#### Examples

A reStructuredText "danger" directive:

    .. DANGER:: Mad scientist at work!

Pseudo-XML fragment from simple parsing:

    <danger>
        <paragraph>
            Mad scientist at work!

### <date>

The <date> element contains the date of publication, release, or last modification of the document.

Category:

  Bibliographic Elements

Analogues:

  <date> is analogous to the DocBook <date> element.

Processing:

  Often used with the RCS/CVS keyword "Date". See <docinfo>.

Parent:

  <docinfo>

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

In reStructuredText, "date" is one of the registered bibliographic fields:

    Document Title
    ==============

    :Date: 2002-08-20

Complete pseudo-XML result after parsing and applying transforms:

    <document ids="document-title" names="document title">
        <title>
            Document Title
        <docinfo>
            <date>
                2002-08-20

See <docinfo> for a more complete example, including processing context.

### <decoration>

The <decoration> element is a container for <header> and <footer> elements and potential future extensions. These elements are used for notes, time/datestamp, processing information, etc.

Category:

  Structural Subelements

Analogues:

  There are no direct analogies to <decoration> in HTML or DocBook.

Processing:

  See the individual decorative elements.

Parent:

  <document>

Children:

  The decorative elements <header> and/or <footer>. Although the content model doesn't specifically require contents, no empty <decoration> elements are ever created.

Attributes:

  only the common attributes.

#### Examples

See <header> and <footer>.

### <definition>

The <definition> element is a container for the body elements used to define a <term> in a <definition_list>.

Category:

  Body Subelements (compound)

Analogues:

  <definition> is analogous to the HTML <dd> element and to the DocBook <listitem> element (inside a <variablelistentry> element).

Processing:

  see <definition_list_item>

Parent:

  <definition_list_item>

Children:

  body elements

Attributes:

  only the common attributes.

#### Examples

See the examples for the <definition_list>, <definition_list_item>, and <classifier> elements.

### <definition_list>

The <definition_list> element contains a list of terms and their definitions. It can be used for glossaries or dictionaries, to describe or classify things, for dialogues, or to itemize subtopics.

Category:

  Compound Body Elements

Analogues:

  <definition_list> is analogous to the HTML <dl> element and to the DocBook <variablelist> element.

Processing:

  see <definition_list_item>

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  one or more <definition_list_item> elements

Attributes:

  only the common attributes.

See also <field_list>.

#### Examples

A reStructuredText definition list. The classifier is optional.

    Term
        Definition.

    Term : classifier
        The ' : ' indicates a classifier in
        definition list item terms only.

Pseudo-XML fragment from simple parsing:

    <definition_list>
        <definition_list_item>
            <term>
                Term
            <definition>
                <paragraph>
                    Definition.
        <definition_list_item>
            <term>
                Term
            <classifier>
                classifier
            <definition>
                <paragraph>
                    The ' : ' indicates a classifier in
                    definition list item terms only.

See <definition_list_item> and <classifier> for further examples.

### <definition_list_item>

A wrapper for a set of terms (with optional classifiers) and the associated definition in a <definition_list>.

Category:

  Body Subelements (compound)

Analogues:

  <definition_list_item> is analogous to the DocBook <variablelistentry> element.

Processing:

  The optional <classifier>s can be rendered differently from the <term>. They should be separated visually, typically by spaces plus a colon or dash.

Parent:

  <definition_list>

Children:

  <definition_list_item> elements each contain one or more <term> elements, zero or more <classifier> elements, and a <definition>:

      ((term, classifier*)+, definition)

  Changed in Docutils 0.22: allow multiple terms.

Attributes:

  only the common attributes.

#### Examples

A complex reStructuredText definition list:

    Tyrannosaurus Rex : carnivore
        Big and scary; the "Tyrant King".

    Brontosaurus : herbivore
      ..

        All brontosauruses are thin at one end,
        much much thicker in the middle
        and then thin again at the far end.

        -- Anne Elk (Miss)

Pseudo-XML fragment from simple parsing:

    <definition_list>
        <definition_list_item>
            <term>
                Tyrannosaurus Rex
            <classifier>
                carnivore
            <definition>
                <paragraph>
                    Big and scary; the "Tyrant King".
        <definition_list_item>
            <term>
                Brontosaurus
            <classifier>
                herbivore
            <definition>
                <comment xml:space="preserve">
                <block_quote>
                    <paragraph>
                        All brontosauruses are thin at one end,
                        much much thicker in the middle
                        and then thin again at the far end.
                    <attribution>
                        Anne Elk (Miss)

See <definition_list> and <classifier> for further examples.

### <description>

The <description> element is the part of an <option_list> item that contains the description of a command-line option or group of options.

Category:

  Body Subelements (compound)

Analogues:

  <description> has no direct analogues in common DTDs.

Processing:

  see <option_list>

Parent:

  <option_list_item>

Children:

  body elements

Attributes:

  only the common attributes.

#### Examples

See <option_list>.

### <docinfo>

The <docinfo> element is a container for displayed document bibliographic data, or meta-data (data about the document). It corresponds to the front matter of a book, such as the title page and copyright page.

Category:

  Structural Subelements

Analogues:

  There are no directly analogous HTML or DocBook elements. The DocBook <info> element is related but ususally suppressed in the output.

Processing:

  The <docinfo> element may be rendered as a two-column table or in other styles. It may even be invisible or omitted from the processed output. Meta-data may be extracted from <docinfo> children; for example, HTML <meta> tags may be constructed.

  When Docutils transforms a reStructuredText <field_list> into a <docinfo> element (see the examples below), RCS/CVS keywords are normally stripped from simple (one paragraph) field bodies. For complete details, please see RCS Keywords in the reStructuredText Markup Specification.

Parent:

  <document>

Children:

  bibliographic elements

Attributes:

  only the common attributes.

See also the <meta> element (for hidden meta-data).

#### Examples

Bibliographic data is represented in reStructuredText by a field list as the first visible element of a document (after optional document title and subtitle). The field list is transformed into a <docinfo> element and its children by the DocInfo transform. [9]

Source:

    Docinfo Example
    ===============

    :Author: J. Random Hacker
    :Contact: jrh@example.com
    :Date: 2002-08-18
    :Status: Work In Progress
    :Version: 1
    :Filename: $RCSfile$
    :Copyright: This document has been placed in the public domain.

Complete pseudo-XML result after parsing and applying transforms:

    <document ids="docinfo-example" names="docinfo example">
        <title>
            Docinfo Example
        <docinfo>
            <author>
                J. Random Hacker
            <contact>
                <reference refuri="mailto:jrh@example.com">
                    jrh@example.com
            <date>
                2002-08-18
            <status>
                Work In Progress
            <version>
                1
            <field classes="filename">
                <field_name>
                    Filename
                <field_body>
                    <paragraph>
                        doctree.rst
            <copyright>
                This document has been placed in the public domain.

Note that "Filename" is a non-standard <docinfo> field, so becomes a generic field element. Also note that the "RCSfile" keyword syntax has been stripped from the "Filename" data.

See <field_list> for a reStructuredText field list example in a non-bibliographic context. Also see the individual examples for the various bibliographic elements.

[9]

Exceptions are the fields "abstract" and "dedication" that are transformed to <topic> elements adjacent to the <docinfo>.

### <doctest_block>

The <doctest_block> element is a Python-specific variant of a <literal_block>.

Category:

  Simple Body Elements

Analogues:

  <doctest_block> is analogous to the HTML <pre> element and the DocBook <programlisting> and <screen> elements.

Processing:

  As with <literal_block>, <doctest_block> elements are typically rendered in a monospaced typeface. It is crucial that all whitespace and line breaks are preserved in the rendered form.

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  text data plus inline elements (%text.model)

Attributes:

  the common attributes and xml:space.

#### Examples

A reStructuredText doctest block:

    This is an ordinary paragraph.

    >>> print('this is a Doctest block')
    this is a Doctest block

Pseudo-XML fragment from simple parsing:

    <paragraph>
        This is an ordinary paragraph.
    <doctest_block xml:space="preserve">
        >>> print('this is a Doctest block')
        this is a Doctest block

The <doctest_block> will be deprecated in Docutils 1.0, the reStructuredText parser will use a <literal_block> instead.

### <document>

The <document> element is the root (topmost) element of the Docutils document tree.

Category:

  Root Element

Analogues:

  <document> is analogous to the HTML <html> element and to several DocBook elements such as <book>.

Parents:

  The <document> element has no parents.

Children:

  structural elements, structural subelements, and body elements

      ( (title, subtitle?)?,
        meta*,
        decoration?,
        (docinfo, transition?)?,
        %structure.model; )

  See the %structure.model parameter entity for details of the body of a <document>.

Attributes:

  the common attributes and title.

<document> is the direct or indirect ancestor of every other element in the tree. It encloses the entire document tree. It is the starting point for a document.

Depending on the source of the data and the stage of processing, the <document> may not initially contain a <title>. A document title is not directly representable in reStructuredText. Instead, the DocTitle transform may promote a lone top-level section title to become the document <title>, and similarly a lone second-level (sub)section's title to become the document <subtitle>.

The contents of "<decoration>" may be specified in a document, constructed programmatically, or both.

The "<docinfo>" may be transformed from an initial <field_list>.

#### Examples

A minimal reStructuredText document with title:

    A Title
    =======

    A paragraph.

Complete pseudo-XML result from simple parsing:

    <document>
        <section ids="a-title" names="a title">
            <title>
                A Title
            <paragraph>
                A paragraph.

After applying transforms, the section title is promoted to become the document title:

    <document ids="a-title" names="a title">
        <title>
            A Title
        <paragraph>
            A paragraph.

### <emphasis>

The <emphasis> element is an inline element representing text that has stress emphasis.

Category:

  Inline Elements

Analogues:

  <emphasis> is analogous to the HTML <em> element and the DocBook <emphasis> element.

Processing:

  Typically displayed in italic type.

Parents:

  all elements employing %text.model in their content models

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

The reStructuredText there are two emphasis markup alternatives:

    There are :emphasis:`two` ways to *emphasize* text.

Pseudo-XML fragment from simple parsing:

    <paragraph>
        There are
        <emphasis>
            two
         ways to
        <emphasis>
            emphasize
         text.

### <entry>

The <entry> element represents one cell of a <table>. It is defined in the Exchange Table Model.

Category:

  Body Subelements (compound)

Analogues:

  <entry> is analogous to the DocBook <entry> element. HTML differentiates between header entries <th> and data entries <td>.

Processing:

  Render content in a table cell. The morecols and morerows attributes may be used to define an entry spanning several table cells. See entry in the Exchange Table Model for details.

Parents:

  <thead>, <tbody>

Children:

  body elements (via the %tbl.entry.mdl parameter entity)

Attributes:

  The <entry> element accepts the colname, namest, nameend, morerows, colsep, rowsep, align, char, charoff, and valign attributes (ignored by Docutils) and (via the %tbl.entry.att parameter entity) the common attributes and morecols.

#### Examples

See <table>.

### <enumerated_list>

The <enumerated_list> element contains <list_item> elements which are uniformly marked with enumerator labels.

Category:

  Compound Body Elements

Analogues:

  <enumerated_list> is analogous to the HTML <ol> element and to the DocBook <orderedlist> element.

Processing:

  Each list item should begin a new vertical block, prefaced by a enumeration marker (such as "1.").

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  one or more <list_item> elements

Attributes:

  enumtype, prefix, suffix, start, and the common attributes.

#### Examples

A reStructuredText enumerated list:

    1. Item 1.

       (A) Item A.
       (B) Item B.
       (C) Item C.

    2. Item 2.

Pseudo-XML fragment from simple parsing:

    <enumerated_list enumtype="arabic" prefix="" suffix=".">
        <list_item>
            <paragraph>
                Item 1.
            <enumerated_list enumtype="upperalpha" prefix="(" suffix=")">
                <list_item>
                    <paragraph>
                        Item A.
                <list_item>
                    <paragraph>
                        Item B.
                <list_item>
                    <paragraph>
                        Item C.
        <list_item>
            <paragraph>
                Item 2.

See <list_item> for another example.

### <error>

The <error> element is a specific admonition, a distinctive and self-contained notice.

Category:

  Compound Body Elements

Analogues:

  <error> has no direct analogues in common DTDs. It can be emulated with primitives and type effects.

Processing:

  Rendered distinctly (inset and/or in a box, etc.), with the generated title "Error" (or similar).

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  one or more body elements

Attributes:

  only the common attributes.

See also the generic <admonition> and the other specific admonition elements.

#### Examples

A reStructuredText "error" directive:

    .. Error:: Does not compute.

Pseudo-XML fragment from simple parsing:

    <error>
        <paragraph>
            Does not compute.

### <field>

The <field> element contains one item of a <field_list>, a pair of <field_name> and <field_body> elements.

Category:

  Body Subelements (compound), Bibliographic Elements

Analogues:

  <field> has no direct analogues in common DTDs. HTML uses <div> elements inside <dl> lists for grouping <dt>/<dd> pairs.

Processing:

  See <field_list>.

Parents:

  <docinfo>, <field_list>

Children:

  one <field_name> and one <field_body> element

Attributes:

  only the common attributes.

#### Examples

See the examples for the <field_list> and <docinfo> elements.

### <field_body>

The <field_body> element is analogous to a database field's data.

Category:

  Body Subelements (compound)

Analogues:

  <field_body> is analogous to the HTML <dd> element.

Processing:

  see <field_list>

Parent:

  <field>

Children:

  body elements

Attributes:

  only the common attributes.

#### Examples

See the examples for the <field_list> and <docinfo> elements.

### <field_list>

The <field_list> element contains two-column table-like structures resembling database records (label & data pairs).

Category:

  Compound Body Elements

Analogues:

  <field_list> is analogue to the HTML <dl> element.

Processing:

  A <field_list> is typically rendered as a two-column list, where the first column contains "labels" (usually with a colon suffix). However, field lists are often used for extension syntax or special processing. Such structures do not survive as field lists to be rendered.

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  one or more <field> elements

Attributes:

  only the common attributes.

Field lists are often meant for further processing. In reStructuredText, field lists are used to represent bibliographic fields (contents of the <docinfo> element) and directive options.

#### Examples

A reStructuredText field list:

    :Author: Me
    :Version: 1
    :Date: 2001-08-11
    :Parameter i: integer

Pseudo-XML fragment from simple parsing:

    <field_list>
        <field>
            <field_name>
                Author
            <field_body>
                <paragraph>
                    Me
        <field>
            <field_name>
                Version
            <field_body>
                <paragraph>
                    1
        <field>
            <field_name>
                Date
            <field_body>
                <paragraph>
                    2001-08-11
        <field>
            <field_name>
                Parameter i
            <field_body>
                <paragraph>
                    integer

### <field_name>

The <field_name> element is analogous to a database field's name.

Category:

  Body Subelements (simple)

Analogues:

  <field_name> is analogous to the HTML <dt> element.

Processing:

  See <field_list>.

Parent:

  <field>

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

See the examples for the <field_list> and <docinfo> elements.

### <figure>

The <figure> element groups an <image> with a <caption> and/or <legend>.

Category:

  Compound Body Elements

Analogues:

  The <figure> element is analogous to the HTML <figure> element and the DocBook <figure> and <informalfigure> elements but limited to images (while HTML and DocBook allow also other main content).

Processing:

  On paged media, figures may float to a different position if this helps the page layout.

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  <image> or <reference> (with nested <image>) followed by <caption> or <legend> or both.

Attributes:

  align (via %align-h.att) , width, and the common attributes.

#### Examples

The reStructuredText "figure" directive creates a <figure> element:

    .. figure:: larch-mini.jpg
       :alt: a larch
       :target: larch.jpg
       :class: thumbnail
       :figclass: numbered

       The larch.

       Larix decidua in Aletschwald.

Pseudo-XML fragment from simple parsing:

    <figure classes="numbered">
        <reference refuri="larch.jpg">
            <image alt="a larch" classes="thumbnail" uri="larch-mini.jpg">
        <caption>
            The larch.
        <legend>
            <paragraph>
                Larix decidua in Aletschwald.

### <footer>

The <footer> element is a container element whose contents are meant to appear at the bottom of a web page, or repeated at the bottom of every printed page.

Category:

  Decorative Elements

Analogues:

  <footer> is analogous to the HTML <footer> element. There are no direct analogies to <footer> in HTML4 or DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system.

Parent:

  <decoration>

Children:

  body elements

Attributes:

  only the common attributes.

The <footer> element may contain processing information (datestamp, a link to Docutils, etc.) as well as custom content.

#### Examples

A document may get a <footer> decoration even without use of the reStructuredText "footer" directive:

    A paragraph.

Complete pseudo-XML result after parsing and applying transforms, assuming that the --date command-line option or "datestamp" configuration setting has been supplied:

    <document>
        <decoration>
            <footer>
                <paragraph>
                    Generated on: 2002-08-20.
        <paragraph>
            A paragraph.

### <footnote>

The <footnote> element is used for labelled notes that provide additional context to a passage of text (footnotes or endnotes). The corresponding footnote mark in running text is set by the <footnote_reference> element.

Category:

  Compound Body Elements

Analogues:

  <footnote> has no direct analogues in DocBook or HTML.

  The DocBook <footnote> element combines features of <footnote> and <footnote_reference>.

  The HTML standard lists suggestions to emulate footnotes. The DPub ARIA role "doc-footnote" may be used to mark a conforming HTML emulation (for collections of notes that occur at the end of a section, "doc-endnotes" is more appropriate). The corresponding types in the EPUB 3 Structural Semantics Vocabulary are "footnote" and "endnote".

Processing:

  A <footnote> element should be set off from the rest of the document, e.g. with a border or using a smaller font size.

  Footnotes may "float" to the bottom or margin of a page or a dedicated section.

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  <footnote> elements begin with an optional [10] <label> and contain body elements:

      (label?, (%body.elements;)+)

Attributes:

  the common attributes plus auto and backrefs.

[10]

The footnote label will become mandatory in Docutils 1.0.

#### Examples

reStructuredText uses explicit markup blocks for footnotes:

    .. [1] This is a footnote.

Pseudo-XML fragment from simple parsing:

    <footnote ids="id1" names="1">
        <label>
            1
        <paragraph>
            This is a footnote.

### <footnote_reference>

The <footnote_reference> element is an inline element representing a cross reference to a <footnote> (a footnote mark).

Category:

  Inline Elements

Analogues:

  The <footnote_reference> element resembles the DocBook <footnoteref> element or the LaTeX \footnotemark command. There is no equivalent in HTML. The <a> element can be used to provide a link to the corresponding footnote.

Processing:

  A <footnote_reference> should generate a mark matching the <label> of the referenced footnote. The mark is typically formatted as superscript or enclosed in square brackets.

Parents:

  all elements employing %text.model in their content models

Children:

  only text data

Attributes:

  auto, refid, refname, and the common attributes.

#### Examples

A reStructuredText footnote reference and footnote:

    [#]_ is an auto-numbered footnote reference.

    .. [#] First auto-numbered footnote.

Pseudo-XML fragment from simple parsing:

    <paragraph>
        <footnote_reference auto="1" ids="id1">
         is an auto-numbered footnote reference.
    <footnote auto="1" ids="id3">
        <paragraph>
            First auto-numbered footnote.

The references.Footnotes Docutils transform resolves this to:

    <paragraph>
        <footnote_reference auto="1" ids="id1" refid="id2">
            1
         is an auto-numbered footnote reference.
    <footnote auto="1" backrefs="id1" ids="id2" names="1">
        <label>
            1
        <paragraph>
            First auto-numbered footnote.

### <generated>

The <generated> element represents text that is not present in the document source but inserted by the processing system.

Category:

  Inline Elements

Analogues:

  There are no analogies to <generated> in HTML or DocBook.

Processing:

  No special handling required.

Parents:

  all elements employing %text.model in their content models

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

The reStructuredText "sectnum" directive automatically numbers sections and subsections in a document:

    .. section-numbering::

    Anagram quiz
    ============

Docutils wraps the generated section numbers in <generated> elements:

    <section ids="anagram-quiz" names="anagram\ quiz">
        <title auto="1">
            <generated classes="sectnum">
                1
            Anagram quiz

### <header>

The <header> element is a container element whose contents are meant to appear at the top of a web page, or at the top of every printed page.

Category:

  Decorative Elements

Analogues:

  <header> is analogous to the HTML <header> element. There are no direct analogies to <header> in HTML4 or DocBook. Equivalents are typically constructed from primitives and/or generated by the processing system.

Parent:

  <decoration>

Children:

  body elements

Attributes:

  only the common attributes.

#### Examples

A reStructuredText "header" directive:

    .. header:: This space for rent.

Pseudo-XML fragment from simple parsing:

    <document>
        <decoration>
            <header>
                <paragraph>
                    This space for rent.

### <hint>

The <hint> element is a specific admonition, a distinctive and self-contained notice.

Category:

  Compound Body Elements

Analogues:

  <hint> has no direct analogues in common DTDs. It can be emulated with primitives and type effects.

Processing:

  Rendered distinctly (inset and/or in a box, etc.), with the generated title "Hint" (or similar).

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  one or more body elements

Attributes:

  only the common attributes.

See also the generic <admonition> and the other specific admonition elements.

#### Examples

A reStructuredText "hint" directive:

    .. Hint:: It's bigger than a bread box.

Pseudo-XML fragment from simple parsing:

    <hint>
        <paragraph>
            It's bigger than a bread box.

### <image>

The <image> element refers to an image resource that should be included in the document.

Categories:

  Body Elements, Inline Elements

Analogues:

  <image> is analogous to the HTML <img>, DocBook <imagedata>, and SVG <image> elements.

Processing:

  The specified image is included into the output document. Depending on the output format, this is done by referring to the image URI or by embedding the image data.

Parents:

  all elements employing %body.elements, %text.model, or %structure.model in their content models

Children:

  none (empty)

Attributes:

  uri, alt, align, height, width, scale, loading, and the common attributes.

It is up to the author to ensure compatibility of the image data format with the output format or user agent (LaTeX engine, HTML browser, ...). The reStructuredText Directives documentation contains a non exhaustive table of compatible image formats.

#### Examples

A reStructuredText "image" directive:

    .. image:: picture.jpeg
       :width: 20 mm
       :alt: alternate text

Pseudo-XML fragment from simple parsing:

    <image alt="alternate text" uri="picture.jpeg" width="20mm">

### <important>

The <important> element is a specific admonition, a distinctive and self-contained notice.

Category:

  Compound Body Elements

Analogues:

  <important> is analogous to the DocBook <important> element.

Processing:

  Rendered distinctly (inset and/or in a box, etc.), with the generated title "Important" (or similar).

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  one or more body elements

Attributes:

  only the common attributes.

See also the generic <admonition> and the other specific admonition elements.

#### Examples

A reStructuredText "important" directive:

    .. Important::

       * Wash behind your ears.
       * Clean up your room.
       * Back up your data.

Pseudo-XML fragment from simple parsing:

    <important>
        <bullet_list>
            <list_item>
                <paragraph>
                    Wash behind your ears.
            <list_item>
                <paragraph>
                    Clean up your room.
            <list_item>
                <paragraph>
                    Back up your data.

### <inline>

The <inline> element is a generic inline container.

Category:

  Inline Elements

Analogues:

  <inline> is analogous to the HTML <span> element and the DocBook <phrase> element.

Processing:

  Writers typically pass the classes attribute to the output document and leave styling to the backend or a custom stylesheet. They may also process the classes attribute and convert the <inline> element to a specific element or render the content distinctly for specific class values. Moreover, writers may ignore the element and just render the content.

Parents:

  all elements employing %text.model in their content models

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

Custom interpreted text roles create <inline> elements (unless they are based on a standard role).

This reStructuredText source fragment creates and uses a custom role:

    .. role:: custom

    An example of using :custom:`interpreted text`

Pseudo-XML fragment from simple parsing:

    <paragraph>
        An example of using
        <inline classes="custom">
            interpreted text

### <label>

The <label> element represents the reference label of a <footnote> or <citation>.

Category:

  Body Subelements (simple)

Analogues:

  The <label> element has no direct analogues in HTML. In DocBook, the label of a footnote is stored as attribute of the <footnote> element and the label of a bibliographic entry is represented by an <abbrev> element.

Processing:

  Rendered prominently, as first token of the footnote or citation. Often enclosed in square brackets.

Parents:

  <footnote>, <citation>

Children:

  only text data

Attributes:

  only the common attributes.

#### Examples

See <footnote>, <footnote_reference>, and <citation_reference>.

### <legend>

The <legend> element contains an extended description of a <figure>. It may complement or replace the figure <caption>.

Category:

  Body Subelements (compound)

Analogues:

  The <legend> element is analogous to the DocBook <caption> element (but specific to a <figure>). The HTML <figcaption> element combines <caption> and <legend>.

Processing:

  Formatted as a displayed block.

Parent:

  <figure>

Children:

  body elements

Attributes:

  only the common attributes.

#### Examples

See <figure>.

### <line>

The <line> element contains a single line of text, part of a <line_block>.

Category:

  Body Subelements (simple)

Analogues:

  <line> has no direct analogues in common DTDs. It can be emulated with primitives or type effects.

Processing:

  See <line_block>.

Parent:

  <line_block>

Children:

  text data plus inline elements

Attributes:

  only the common attributes.

#### Examples

See <line_block>.

### <line_block>

The <line_block> element is a “plain list” of lines and nested line blocks. It is commonly used for verse and addresses.

Category:

  Compound Body Elements

Analogues:

  <line_block> has no direct analogues in common DTDs. Is is related to the DocBook <literallayout> element, however <literallayout> is a verbatim environment which directly contains text.

Processing:

  Each <line> should begin a new vertical block, without markers or additional spacing. Nested <line_blocks> should be indented.

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  <line>, <line_block>

Attributes:

  only the common attributes.

See <literal_block> for an alternative useful for program listings and interactive computer sessions.

#### Examples

A reStructuredText line block:

    Take it away, Eric the Orchestra Leader!

    | A one, two, a one two three four
    |
    | Half a bee, philosophically,
    |     must, *ipso facto*, half not be.
    | But half the bee has got to be,
    |     *vis a vis* its entity.  D'you see?
    |
    | But can a bee be said to be
    |     or not to be an entire bee,
    |         when half the bee is not a bee,
    |             due to some ancient injury?
    |
    | Singing...

Pseudo-XML fragment from simple parsing:

    <paragraph>
        Take it away, Eric the Orchestra Leader!
    <line_block>
        <line>
            A one, two, a one two three four
        <line>
        <line>
            Half a bee, philosophically,
        <line_block>
            <line>
                must,
                <emphasis>
                    ipso facto
                , half not be.
        <line>
            But half the bee has got to be,
        <line_block>
            <line>
                <emphasis>
                    vis a vis
                 its entity.  D'you see?
            <line>
        <line>
            But can a bee be said to be
        <line_block>
            <line>
                or not to be an entire bee,
            <line_block>
                <line>
                    when half the bee is not a bee,
                <line_block>
                    <line>
                        due to some ancient injury?
                    <line>
        <line>
            Singing...

### <list_item>

The <list_item> element is a container for the elements of a list item.

Category:

  Body Subelements (compound)

Analogues:

  <list_item> is analogous to the HTML <li> element and to the DocBook <listitem> element.

Processing:

  See <bullet_list> or <enumerated_list>.

Parents:

  <bullet_list>, <enumerated_list>

Children:

  body elements

Attributes:

  only the common attributes.

#### Examples

A reStructuredText enumerated list with a nested bullet list:

    1. Outer list, item 1.

       * Inner list, item 1.
       * Inner list, item 2.

    2. Outer list, item 2.

Pseudo-XML fragment from simple parsing:

    <enumerated_list enumtype="arabic" prefix="" suffix=".">
        <list_item>
            <paragraph>
                Outer list, item 1.
            <bullet_list bullet="*">
                <list_item>
                    <paragraph>
                        Inner list, item 1.
                <list_item>
                    <paragraph>
                        Inner list, item 2.
        <list_item>
            <paragraph>
                Outer list, item 2.

See <bullet_list> or <enumerated_list> for further examples.

### <literal>

The <literal> element represents inline text that is some literal value.

Category:

  Inline Elements

Analogues:

  <literal> is analogous to the DocBook <literal> element. HTML uses the specific elements <code>, <kbd>, and <samp> for code, input, and output.

Processing:

  Typically rendered in a monospace font. Preservation of line breaks and sequences of whitespace characters is not guaranteed.

Parents:

  all elements employing %text.model in their content models

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

In reStructuredText, inline literals, the "literal" role, and the "code" role create <literal> elements. So do custom roles derived from "literal" or "code":

    .. role:: python(code)
       :language: python

    The statement :python:`print("hello world")`
    writes ``"hello world"`` to standard output.

Pseudo-XML fragment from simple parsing:

    <paragraph>
        The statement
        <literal classes="code python">
            <inline classes="name builtin">
                print
            <inline classes="punctuation">
                (
            <inline classes="literal string double">
                "hello world"
            <inline classes="punctuation">
                )

        writes
        <literal>
            "hello world"
         to standard output.

### <literal_block>

The <literal_block> element contains a block of text where line breaks and whitespace are significant and must be preserved.

#### Details

Category:

  Simple Body Elements

Analogues:

  <literal_block> is analogous to the HTML <pre> element and to the DocBook <programlisting> and <screen> elements.

Processing:

  <literal_block> elements are typically rendered in a monospaced typeface. It is crucial that all whitespace and line breaks are preserved in the rendered form.

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  text data plus inline elements (%text.model)

Attributes:

  the common attributes and xml:space.

<literal_block> elements are commonly used for program listings and interactive computer sessions. See <line_block> for an alternative useful for verse and addresses.

#### Examples

A reStructuredText "parsed-literal" directive:

    .. parsed-literal::

        if parsed_literal:
            text = 'is parsed for reStructuredText_ markup'
            spaces_and_linebreaks = 'are preserved'
            markup_processing = **True**

Pseudo-XML fragment from simple parsing:

    <literal_block xml:space="preserve">
        if parsed_literal:
            text = 'is parsed for
        <reference name="reStructuredText" refid="restructuredtext">
            reStructuredText
         markup'
            spaces_and_linebreaks = 'are preserved'
            markup_processing =
        <strong>
            True

<literal-block> elements are also generated by a literal block and the "code" directive, e.g.

    .. code:: python

           print(8/2)

Pseudo-XML fragment from simple parsing (with the "syntax_highlight" setting at its default value "long"):

    <literal_block classes="code python" xml:space="preserve">
        <inline classes="name builtin">
            print
        <inline classes="punctuation">
            (
        <inline classes="literal number integer">
            8
        <inline classes="operator">
            /
        <inline classes="literal number integer">
            2
        <inline classes="punctuation">
            )

### <math>

The <math> element contains text in LaTeX math format [11] that is typeset as mathematical notation (inline formula).

Category:

  Inline Elements

Analogues:

  <math> is related to the <math> element in MathML and HTML. However, it contains text data only.

Processing:

  Rendered as mathematical notation. If the output format does not support math typesetting, the content may be inserted verbatim.

Parents:

  all elements employing %text.model in their content models

Children:

  only text data

Attributes:

  only the common attributes.

#### Example

reStructuredText source:

    Euler's identity is :math:`e^{\mathrm{i}\pi} + 1 = 0`.

Pseudo-XML fragment from simple parsing:

    <paragraph>
        Euler’s identity is
        <math>
            e^{\mathrm{i}\pi} + 1 = 0
        .

[11] (1,2)

For details of the supported mathematical language, see the "math" directive

### <math_block>

The <math_block> element contains a block of text in LaTeX math format [11] that is typeset as mathematical notation (display formula).

Category:

  Simple Body Elements

Analogues:

  <math_block> is analogous to a HTML/MathML <math> element displayed as block-level element or a LaTeX equation* environment.

Processing:

  Rendered in a block as mathematical notation, typically centered or with indentation If the output format does not support math typesetting, the content may be inserted verbatim.

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  only text data

Attributes:

  the common attributes and xml:space.

#### Example

The reStructuredText "math" directive generates a <math_block> element:

    Euler's identity is the equation

    .. math:: e^{\mathrm{i}\pi} + 1 = 0

Pseudo-XML fragment from simple parsing:

    <paragraph>
        Euler’s identity is the equation
    <math_block xml:space="preserve">
        e^{\mathrm{i}\pi} + 1 = 0

### <meta>

The <meta> element is a container for "hidden" document bibliographic data, or meta-data (data about the document).

Category:

  Structural Subelements

Analogues:

  <meta> is analogous to the HTML <meta> element or the file properties in ODT or PDF documents.

Processing:

  The <meta> element is stored as metadata if the export format supports this. It is typically invisible and may be omitted from the processed output.

  Meta-data may also be extracted from <docinfo> children or the <document> attributes (title).

Parent:

  <document>

Children:

  none (empty)

Attributes:

  the attributes content, dir, http-equiv, lang, media, name, and scheme that correspond to the respective attributes of the HTML <meta> element.

See also the <docinfo> element for displayed meta-data. The document's title attribute stores the metadata document title.

#### Example

A reStructuredText "meta" directive:

    .. meta::
       :description lang=en: An amusing story
       :description lang=fr: Un histoire amusant

Pseudo-XML fragment from simple parsing:

    <meta content="An amusing story" lang="en" name="description">
    <meta content="Un histoire amusant" lang="fr" name="description">

### <note>

The <note> element is a specific admonition, a distinctive and self-contained notice.

Category:

  Compound Body Elements

Analogues:

  <note> is analogous to the DocBook <note> element.

Processing:

  Rendered distinctly (inset and/or in a box, etc.), with the generated title "Note" (or similar).

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  one or more body elements

Attributes:

  only the common attributes.

See also the generic <admonition> and the other specific admonition elements.

#### Examples

A reStructuredText "note" directive:

    .. Note:: Admonitions can be handy to break up a
       long boring technical document.

Pseudo-XML fragment from simple parsing:

    <note>
        <paragraph>
            Admonitions can be handy to break up a
            long boring technical document.

### <option>

The <option> element groups an option string together with zero or more option argument placeholders.

Category:

  Body Subelements (compound)

Analogues:

  <option> has no direct analogues in common DTDs.

Processing:

  See <option_list>.

Parent:

  <option_group>

Children:

  <option> elements start with an <option_string> and may contain <option_argument> elements:

      (option_string, option_argument*)

Attributes:

  only the common attributes.

Note that reStructuredText currently supports only one argument per option.

#### Examples

See the examples for the <option_list> element.

### <option_argument>

The <option_argument> element contains placeholder text for option arguments.

Category:

  Body Subelements (simple)

Analogues:

  <option_argument> has no direct analogues in common DTDs.

Processing:

  The value of the "delimiter" attribute is prefixed to the <option_argument>, separating it from its <option_string> or a preceding <option_argument>. The <option_argument> text is typically rendered in a monospaced typeface, possibly italicized or otherwise altered to indicate its placeholder nature.

Parent:

  <option>

Children:

  only text data

Attributes:

  the common attributes and delimiter.

#### Examples

See the examples for the <option_list> element.

### <option_group>

The <option_group> element groups together one or more <option> elements, all synonyms.

Category:

  Body Subelements (compound)

Analogues:

  <option_group> has no direct analogues in common DTDs.

Processing:

  Typically <option> elements within an <option_group> are joined together in a comma-separated list.

Parent:

  <option_list_item>

Children:

  one or more <option> elements

Attributes:

  only the common attributes.

#### Examples

See the examples for the <option_list> element.

### <option_list>

Each <option_list> element contains a two-column list of command-line options and descriptions, documenting a program's options.

Category:

  Compound Body Elements

Analogues:

  <option_list> has no direct analogues in common DTDs. It can be emulated with primitives such as tables.

Processing:

  An <option_list> is typically rendered as a two-column list, where the first column contains option strings and arguments, and the second column contains descriptions.

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  one or more <option_list_item> elements

Attributes:

  only the common attributes.

#### Examples

A reStructuredText option list:

    -a            command-line option "a"
    -1 file, --one=file, --two file
                  Multiple options with arguments.

Pseudo-XML fragment from simple parsing:

    <option_list>
        <option_list_item>
            <option_group>
                <option>
                    <option_string>
                        -a
            <description>
                <paragraph>
                    command-line option "a"
        <option_list_item>
            <option_group>
                <option>
                    <option_string>
                        -1
                    <option_argument delimiter=" ">
                        file
                <option>
                    <option_string>
                        --one
                    <option_argument delimiter="=">
                        file
                <option>
                    <option_string>
                        --two
                    <option_argument delimiter=" ">
                        file
            <description>
                <paragraph>
                    Multiple options with arguments.

### <option_list_item>

The <option_list_item> element is a container for a pair of <option_group> and <description> elements.

Category:

  Body Subelements (compound)

Analogues:

  <option_list_item> has no direct analogues in common DTDs.

Processing:

  see <option_list>

Parent:

  <option_list>

Children:

  one <option_group> and one <description>

Attributes:

  only the common attributes.

#### Examples

See the examples for the <option_list> element.

### <option_string>

The <option_string> element contains the text of a command-line option.

Category:

  Body Subelements (simple)

Analogues:

  <option_string> has no direct analogues in common DTDs.

Processing:

  The <option_string> text is typically rendered in a monospaced typeface.

Parent:

  <option>

Children:

  only text data

Attributes:

  only the common attributes.

#### Examples

See the examples for the <option_list> element.

### <organization>

The <organization> element contains the name of document author's organization, or the organization responsible for the document.

Category:

  Bibliographic Elements

Analogues:

  <organization> is analogous to the <orgname>, <corpname>, or <publishername> DocBook elements.

Processing:

  See <docinfo>.

Parent:

  <docinfo>

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

In reStructuredText, "organization" is one of the registered bibliographic fields:

    Document Title
    ==============

    :Organization: Humankind

Complete pseudo-XML result after parsing and applying transforms:

    <document ids="document-title" names="document title">
        <title>
            Document Title
        <docinfo>
            <organization>
                Humankind

See <docinfo> for a more complete example, including processing context.

### <paragraph>

The <paragraph> element contains the text and inline elements of a single paragraph, a fundamental building block of documents.

Category:

  Simple Body Elements

Analogues:

  <paragraph> is analogous to the HTML <p> element and to the DocBook <para> element.

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

In reStructuredText, blocks of left-aligned text are paragraphs unless marked up as another body element:

    A paragraph must be
    left-aligned.

Pseudo-XML fragment from simple parsing:

    <paragraph>
        A paragraph must be
        left-aligned.

### <pending>

The <pending> element is a placeholder for a pending transform.

Category:

  Body Elements (empty)

Analogues:

  <pending> has no direct analogues in common DTDs.

Processing:

  Usually replaced or removed by the associated transform. Writers may ignore remaining <pending> elements.

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  none (empty)

Attributes:

  only the common attributes.

#### Example

The reStructuredText "contents" directive indicates that an auto-generated table of contents (ToC) should be inserted at this point:

    .. contents::
       :depth: 1

    first section
    =============

    second section
    ==============

As the ToC can't be generated until the entire document has been parsed, simple parsing adds a <topic> with a <pending> element as placeholder:

    <topic classes="contents" ids="contents" names="contents">
        <title>
            Contents
        <pending>
            .. internal attributes:
                 .transform: docutils.transforms.parts.Contents
                 .details:
                   depth: 1
    <section ids="first-section" names="first\ section">
        <title>
            first section
    <section ids="second-section" names="second\ section">
        <title>
            second section

After parsing is completed, the associated parts.Contents transform replaces the <pending> node with the table of contents:

    <topic classes="contents" ids="contents" names="contents">
        <title>
            Contents
        <bullet_list>
            <list_item>
                <paragraph>
                    <reference ids="toc-entry-1" refid="first-section">
                        first section
            <list_item>
                <paragraph>
                    <reference ids="toc-entry-2" refid="second-section">
                        second section
    <section ids="first-section" names="first\ section">
        <title refid="toc-entry-1">
            first section
    <section ids="second-section" names="second\ section">
        <title refid="toc-entry-2">
            second section

### <problematic>

The <problematic> element highlights a source part that caused a parsing problem.

Category:

  Inline Elements

Analogues:

  <problematic> has no direct analogues in common DTDs.

Processing:

  Typically displayed in red colour. If the refid attribute is present, the element should point to the referenced element.

Parents:

  all elements employing %text.model in their content models

Children:

  text data plus inline elements (%text.model)

Attributes:

  the common attributes and refid.

#### Examples

The reStructuredText parser marks ambiguous or invalid inline syntax as <problematic> and adds a reference to the associated <system_message>. The behaviour can be configured with the "report_level" setting.

The following paragraph contains unbalanced inline markup:

    a single *star

Pseudo-XML fragment from simple parsing:

    <paragraph>
        a single
        <problematic ids="problematic-1" refid="system-message-1">
            *
        star
    <system_message backrefs="problematic-1" ids="system-message-1"
                    level="2" line="1" source="example.rst" type="WARNING">
        <paragraph>
            Inline emphasis start-string without end-string.

### <raw>

The <raw> element contains non-reStructuredText data that is to be passed untouched to the Writer.

Category:

  Simple Body Elements, Inline Elements

Analogues:

  The <raw> element has no direct analogues in common DTDs.

Processing:

  Passed untouched to the Writer. The interpretation is up to the Writer. A Writer may ignore <raw> elements not matching its format.

Parents:

  all elements employing %body.elements, %structure.model, or %text.model in their content models

Children:

  only text data

Attributes:

  format, xml:space and the common attributes.

#### Examples

The reStructuredText "raw" directive [12] creates a <raw> element:

    .. raw:: html

       <hr width=50 size=10>

Pseudo-XML fragment from simple parsing:

    <raw format="html" xml:space="preserve">
        <hr width=50 size=10>

[12]

For raw data pass-through in inline context, use custom interpreted text roles derived from the "raw" role.

### <reference>

The <reference> element represents a cross reference to another element of the document or to an external ressource.

Category:

  Simple Body Elements, Inline Elements

Analogues:

  The <reference> element is analogous to the DocBook <link> element and the HTML <a> (anchor) element.

Processing:

  If possible, make the content of the link element an active link. In print media, the target might be ignored, printed after the text of the <reference>, printed as a footnote [13], or rendered in some other way.

Parents:

  all elements employing %body.elements, %text.model, or %structure.model in their content models

Children:

  text data plus inline elements (%text.model)

Attributes:

  anonymous, name (deprecated), refid, refname, refuri, and the common attributes.

[13]

See the "target-notes" directive.

#### Examples

In reStructuredText hyperlink references are indicated by a trailing underscore:

    References may use simple_ reference names,
    `phrase references`_, or `no reference name`__.

    Matching targets must exist in the document, e.g., a
    _`simple` inline target or the explicit targets below.

    .. _phrase references: doctree.rst
    __ http://example.org

Pseudo-XML fragment from simple parsing:

    <paragraph>
        References may use
        <reference refname="simple">
            simple
         reference names,
        <reference refname="phrase references">
            phrase references
        , or
        <reference anonymous="1">
            no reference name
        .
    <paragraph>
        Matching targets must exist in the document, e.g., a
        <target ids="simple" names="simple">
            simple
         inline target or the explicit targets below.
    <target ids="phrase-refs" names="phrase\ refs" refuri="doctree.rst">
    <target anonymous="1" ids="target-1" refuri="http://example.org">

Docutils uses transforms to match references and targets and replace the refname with a refid or refuri:

    <paragraph>
        References may use
        <reference refid="simple">
            simple
         reference names,
        <reference refuri="doctree.rst">
            phrase references
        , or
        <reference anonymous="1" refuri="http://example.org">
            no reference name
        .
    <paragraph>
        Matching targets must exist in the document, e.g., a
        <target ids="simple" names="simple">
            simple
         inline target or the explicit targets below.
    <target ids="phrase-refs" names="phrase\ refs" refuri="doctree.rst">
    <target anonymous="1" ids="target-1" refuri="http://example.org">

Standalone hyperlinks and clickable images generate <reference> elements, too:

    Visit https://hamburg.de.

    .. image:: michel.jpg
       :target: https://hamburg.de

Pseudo-XML fragment from simple parsing:

    <paragraph>
        Visit
        <reference refuri="https://hamburg.de">
            https://hamburg.de
        .
    <reference refuri="https://hamburg.de">
        <image uri="michel.jpg">

### <revision>

The <revision> element contains the revision number of the document. It can be used alone or in conjunction with <version>.

Category:

  Bibliographic Elements

Analogues:

  <revision> is similar to (but simpler than) the DocBook <revision> element. It closely matches the DocBook <revnumber> element, but in a simpler context.

Processing:

  Often used with the RCS/CVS keyword "Revision". See <docinfo>.

Parent:

  <docinfo>

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

In reStructuredText, "revision" is one of the registered bibliographic fields:

    Document Title
    ==============

    :Version: 1
    :Revision: b

Complete pseudo-XML result after parsing and applying transforms:

    <document ids="document-title" names="document title">
        <title>
            Document Title
        <docinfo>
            <version>
                1
            <revision>
                b

See <docinfo> for a more complete example, including processing context.

### <row>

The <row> element represents one row of a <table>. It is defined in the Exchange Table Model.

Category:

  Body Subelements (compound)

Analogues:

  <row> is analogous to the HTML <tr> element and the DocBook <row> element.

Processing:

  Render content as a table row. See row in the Exchange Table Model for details.

Parents:

  <thead>, <tbody>

Children:

  one or more <entry> elements

Attributes:

  The <row> element may contain the rowsep and valign attributes (ignored by Docutils) and (via the %tbl.row.att parameter entity) the common attributes.

#### Examples

See <table>.

### <rubric>

A <rubric> is an informal heading outside the document's section structure.

Category:

  Simple Body Elements

Analogues:

  <rubric> has no direct analogues in common DTDs. It shares some features with the <bridgehead> DocBook element.

Processing:

  Rendered similar to a section heading, traditionally highlighted in red (hence the name). Rubrics are not (auto)numbered and not included in the document's table of contents.

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Example

The reStructuredText "rubric" directive can be used to get a heading at places where a section is not allowed:

    .. sidebar:: Sidebar Title

       This is a sidebar.  It is for text outside the flow
       of the main text.

       .. rubric:: A heading inside a sidebar

       Sections are not supported in a sidebar.
       A rubric can be used to structure the content instead.

Pseudo-XML fragment from simple parsing:

    <sidebar>
        <title>
            Sidebar Title
        <paragraph>
            This is a sidebar.  It is for text outside the flow
            of the main text.
        <rubric>
            A heading inside a sidebar
        <paragraph>
            Sections are not supported in a sidebar.
            A rubric can be used to structure the content instead.

### <section>

The <section> element is the main unit of hierarchy for Docutils documents.

Category:

  Structural Elements

Analogues:

  <section> is analogous to the <section> elements in HTML and DocBook.

Parents:

  <document>, <section>

Children:

  <section> elements begin with a <title>, followed by an optional <subtitle>. They may contain structural elements, body elements, and <transition> elements:

      (title, subtitle?, %structure.model;)

Attributes:

  only the common attributes

Parameter Entities:

  %section.elements directly includes <section>, %structure.model indirectly includes <section>.

The Docutils document model uses a simple, recursive model for section structure. A <document> element may contain <section> elements. Sections in turn may contain other <section> elements, without limit. The level (depth) of a section element is determined from its physical nesting level.

Paragraphs and other body elements may occur before a <section>, but not after it.

#### Examples

reStructuredText does not impose a fixed number and order of section title adornment styles. The order enforced will be the order as encountered.

    Title 1
    =======
    Paragraph 1.

    Title 2
    -------
    Paragraph 2.

    Title 3
    =======
    Paragraph 3.

    Title 4
    -------
    Paragraph 4.

Complete pseudo-XML result after parsing:

    <document>
        <section ids="title-1" names="title 1">
            <title>
                Title 1
            <paragraph>
                Paragraph 1.
            <section ids="title-2" names="title 2">
                <title>
                    Title 2
                <paragraph>
                    Paragraph 2.
        <section ids="title-3" names="title 3">
            <title>
                Title 3
            <paragraph>
                Paragraph 3.
            <section ids="title-4" names="title 4">
                <title>
                    Title 4
                <paragraph>
                    Paragraph 4.

### <sidebar>

Sidebars are like miniature, parallel documents that occur inside other documents, providing related or reference material. Their content is outside of the flow of the document's main text.

Category:

  Structural Elements

Analogues:

  <sidebar> is analogous to the DocBook <sidebar> element and the HTML <aside> element.

Processing:

  A <sidebar> element should be set off from the rest of the document somehow, typically with a border. Sidebars typically "float" to the side of the page and the document's main text flows around them.

Parents:

  <document>, <section>.

Children:

  <sidebar> elements begin with optional <title> and <subtitle> and contain body elements and <topic> elements. There must not be a <subtitle> without title.

      ((title, subtitle?)?,
       (%body.elements; | topic)+)

Attributes:

  only the common attributes

Parameter Entities:

  %structure.model directly includes <sidebar>.

The <sidebar> element is a non-recursive <section>-like construct. <sidebar> elements cannot nest inside body elements, so you can't have a <sidebar> inside a <table> or a list, or inside another <sidebar> or <topic>.

#### Examples

A reStructuredText "sidebar" directive:

    .. sidebar:: Optional Title
       :subtitle: If Desired

       Body.

Pseudo-XML fragment from simple parsing:

    <sidebar>
        <title>
            Optional Title
        <subtitle>
            If Desired
        <paragraph>
            Body.

### <status>

The <status> element contains a status statement for the document, such as "Draft", "Final", "Work In Progress", etc.

Category:

  Bibliographic Elements

Analogues:

  <status> is analogous to the DocBook <status> element.

Processing:

  See <docinfo>.

Parent:

  <docinfo>

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

In reStructuredText, "status" is one of the registered bibliographic fields:

    Document Title
    ==============

    :Status: Work In Progress

Complete pseudo-XML result after parsing and applying transforms:

    <document ids="document-title" names="document title">
        <title>
            Document Title
        <docinfo>
            <status>
                Work In Progress

See <docinfo> for a more complete example, including processing context.

### <strong>

The <strong> element is an inline element representing text that has strong importance, seriousness, or urgency.

Category:

  Inline Elements

Analogues:

  <strong> is analogous to the HTML <strong> element.

Processing:

  Typically displayed in boldface.

Parents:

  all elements employing %text.model in their content models

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

The reStructuredText there are two alternatives to mark text with strong emphasis:

    There are :strong:`two` ways to **strongly emphasize** text.

Pseudo-XML fragment from simple parsing:

    <paragraph>
        There are
        <strong>
            two
         ways to
        <strong>
            strongly emphasize
         text.

### <subscript>

The <subscript> element is an inline element representing text which should be displayed as subscript.

Category:

  Inline Elements

Analogues:

  <subscript> is analogous to the HTML <sub> element and the DocBook <subscript> element.

Processing:

  Typically rendered with a lowered baseline using smaller text.

Parents:

  all elements employing %text.model in their content models

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

The reStructuredText "subscript" role creates a <subscript> element:

    The chemical formula for water is H\ :sub:`2`\ O.

Pseudo-XML fragment from simple parsing:

    <paragraph>
        The chemical formula for water is H
        <subscript>
            2
        O.

### <substitution_definition>

The <substitution_definition> element stores content that shall replace matching <substitution_reference> elements.

Category:

  Simple Body Elements

Analogues:

  Substitution definitions are analog to XML’s internal entities or programming language macros.

Processing:

  A <substitution_definition> is not directly rendered.

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  text data plus inline elements (%text.model)

Attributes:

  ltrim, rtrim, and the common attributes. The names attribute uses the "substitution" namespace.

#### Examples

A reStructuredText substitution definition allows to include complex inline structures within text while keeping the details out of the text flow:

    The chemical formula for water is |H2O|.

    .. |H2O| replace:: H\ :sub:`2`\ O

Pseudo-XML fragment from simple parsing:

    <paragraph>
        The chemical formula for water is
        <substitution_reference refname="H2O">
            H2O
        .
    <substitution_definition names="H2O">
        H
        <subscript>
            2
        O

The references.Substitutions transform replaces the <substitution_reference> with the content of the <substitution_definition>:

    <paragraph>
        The chemical formula for water is
        H
        <subscript>
            2
        O
        .
    <substitution_definition names="H2O">
        H
        <subscript>
            2
        O

A substitution definition can also supply an <image> for inline use:

    The |biohazard| symbol must be used on
    medical waste containers.

    .. |biohazard| image:: biohazard.png

Pseudo-XML fragment from simple parsing:

    <paragraph>
        The
        <substitution_reference refname="biohazard">
            biohazard
         symbol must be used on
        medical waste containers.
    <substitution_definition names="biohazard">
        <image alt="biohazard" uri="biohazard.png">

After running the references.Substitutions transform, we get:

    <paragraph>
        The
        <image alt="biohazard" uri="biohazard.png">
         symbol must be used on
        medical waste containers.
    <substitution_definition names="biohazard">
        <image alt="biohazard" uri="biohazard.png">

For more usage examples, see Substitution Definitions in the reStructuredText Markup Specification.

### <substitution_reference>

The <substitution_reference> element is a placeholder for the content of the matching <substitution_definition>.

Category:

  Inline Elements

Analogues:

  A <substitution_reference> is analogue to an XML entity reference.

Processing:

  Replaced by the content of a matching <substitution_definition>.

Parents:

  all elements employing %text.model in their content models

Children:

  text data plus inline elements (%text.model)

Attributes:

  the common attributes plus refname. The refname attribute uses the "substitution" namespace.

#### Examples

See <substitution_definition>.

### <subtitle>

The <subtitle> element stores the subtitle of a <document>, <section>, or <sidebar>.

Category:

  Structural Subelements

Analogues:

  <subtitle> is analogous to the DocBook <subtitle> element. In HTML, subtitles are represented by a <p> element inside a <hgroup> element.

Processing:

  A document's subtitle is usually rendered smaller than its <title>.

Parents:

  <document>, <section>, and <sidebar>

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

In reStructuredText, a lone second-level section title immediately after the “document title” can become the document subtitle:

    =======
     Title
    =======
    ----------
     Subtitle
    ----------

    A paragraph.

Complete pseudo-XML result after parsing and applying the DocTitle transform:

    <document ids="title" names="title">
        <title>
            Title
        <subtitle ids="subtitle" names="subtitle">
            Subtitle
        <paragraph>
            A paragraph.

Note how two section levels have collapsed, promoting their titles to become the document's title and subtitle. Since there is only one structural element (document), the subsection's ids and names attributes are stored in the <subtitle> element.

### <superscript>

The <superscript> element is an inline element representing text which should be displayed as superscript.

Category:

  Inline Elements

Analogues:

  <superscript> is analogous to the HTML <sup> element and the DocBook <superscript> element.

Processing:

  Typically rendered with a raised baseline using smaller text.

Parents:

  all elements employing %text.model in their content models

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

The reStructuredText "superscript" role creates a <superscript> element:

    Key events of the 20\ :sup:`th` century.

Pseudo-XML fragment from simple parsing:

    <paragraph>
        Key events of the 20
        <superscript>
            th
         century.

### <system_message>

The <system_message> element is used for feedback from the processing system.

Category:

  Compound Body Elements

Analogues:

  <system_message> has no direct analogues in common DTDs. It can be emulated with primitives and type effects.

Processing:

  Rendered similar to an <admonition>, with the generated title "System Message", its type/level and, if available, source and line.

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  one or more body elements

Attributes:

  backrefs, level, line, type, and the common attributes.

In Docutils, system messages with a level lower than the "report_level" setting are removed by the universal.FilterMessages transform.

#### Examples

An undefined or misspelled directive generates an error message:

    .. contants::

Pseudo-XML fragment from simple parsing:

    <system_message level="3" line="8" source="example.rst" type="ERROR">
        <paragraph>
            Unknown directive type "contants".
        <literal_block xml:space="preserve">
            .. contants::

See also <problematic>.

### <table>

The <table> element represents a data arrangement with rows and columns. It is defined in the Exchange Table Model.

Category:

  Compound Body Elements

Analogues:

  <table> is analogous to the <table> element in HTML and DocBook.

Processing:

  Content is arranged in rows and columns forming a grid. See table in the Exchange Table Model for details.

Parents:

  <document>, <section> and all body elements

Children:

  <table> elements begin with an optional <title> (caption) and may contain one or more <tgroup> elements:

      (title?, tgroup+)

Attributes:

  The <table> element may contain the frame, colsep, rowsep, and pgwide attributes (ignored by Docutils) and (via the %bodyatt parameter entity) the common attributes, align, and width.

#### Examples

In reStructuredText, tables can be specified via the "table", "csv-table", or "list-table" directives or directly as grid table or simple table, e.g.

    ======== ====
     bread   £2
     butter  £30
    ======== ====

Pseudo-XML fragment from simple parsing:

    <table>
        <tgroup cols="2">
            <colspec colwidth="8">
            <colspec colwidth="4">
            <tbody>
                <row>
                    <entry>
                        <paragraph>
                            bread
                    <entry>
                        <paragraph>
                            £2
                <row>
                    <entry>
                        <paragraph>
                            butter
                    <entry>
                        <paragraph>
                            £30

### <target>

The <target> element provides an end-point for a hypertext <reference>.

Category:

  Empty Body Elements, Inline Elements [14]

Analogues:

  As body element, <target> is similar to the DocBook <anchor> element. An inline <target> can be represented by a DocBook <phrase> or HTML <span> element.

Processing:

  <target> elements with refid, refname, or refuri attribute (indirect targets) act as a relay for links to one of the target's ids or names. A <target> without refid, refname, or refuri attributes provides ids or names for its content or, if empty, the next element.

Parents:

  all elements employing %body.elements, %structure.model, or %text.model in their content models

Children:

  only text data [15]

Attributes:

  anonymous, refid, refname, refuri, and the common attributes.

[14]

Inline <target> elements will be deprecated in Docutils 1.0 and invalid in Docutils 2.0. The "rst" parser will use <inline> elements for inline targets.

[15]

<target> elements with content will be deprecated in Docutils 1.0 and invalid in Docutils 2.0.

#### Examples

In reStructuredText, hyperlink targets are indicated by a leading underscore:

    .. _inline: `inline target`_
    .. _example: https//:example.org
    .. _alias:
    .. _explicit target:

    The hyperlink target above points to this paragraph
    with an _`inline target`.

Pseudo-XML fragment from simple parsing:

    <target ids="inline" names="inline" refname="inline target">
    <target ids="example" names="example" refuri="https//:example.org">
    <target ids="alias" names="alias">
    <target ids="explicit-target" names="explicit\ target">
    <paragraph>
        The hyperlink target above points to this paragraph
        with an
        <target ids="inline-target" names="inline\ target">
            inline target
        .

After applying transforms, the paragraph has two reference names and two IDs, transferred from the preceding targets:

    <target ids="inline" names="inline" refid="inline-target">
    <target ids="example" names="example" refuri="https//:example.org">
    <target refid="alias">
    <target refid="explicit-target">
    <paragraph ids="explicit-target alias" names="explicit\ target alias">
        The hyperlink target above points to this paragraph
        with an
        <target ids="inline-target" names="inline\ target">
            inline target
        .

For more examples, see <reference>.

### <tbody>

The <tbody> element identifies the rows that form the body of a <table> (as distinct from the header rows). It is defined in the Exchange Table Model.

Category:

  Body Subelements (compound)

Analogues:

  <tbody> is analogous to the <tbody> element in HTML and DocBook.

Processing:

  Render content as table body.

Parent:

  <tgroup>

Children:

  one or more <row> elements

Attributes:

  valign (ignored by Docutils) and the common attributes (via the %tbl.tbody.att parameter entity).

#### Examples

See <table>.

### <term>

The <term> element contains a word or phrase being defined in a <definition_list>.

Category:

  Body Subelements (simple)

Analogues:

  <term> is analogous to the HTML <dt> element and to the DocBook <term> element.

Processing:

  see <definition_list_item>

Parent:

  <definition_list_item>

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

See the examples for the <definition_list>, <definition_list_item>, and <classifier> elements.

### <tgroup>

The <tgroup> element identifies a logically complete portion of a <table>. It is defined in the Exchange Table Model.

Category:

  Body Subelements (compound)

Analogues:

  <tgroup> is analogous to the DocBook <tgroup> element. There is no corresponding HTML element (the <colgroup> element has a different purpose and semantics).

Processing:

  See tgroup in the Exchange Table Model.

Parent:

  <table>

Children:

  One or more <colspec> elements, followed by an optional <thead> and a <tbody> (cf. the %tbl.tgroup.mdl parameter entity). The number of <colspec>s, must not exceed the value of the cols attribute. Docutils expects one <colspec> per column.

Attributes:

  The <tgroup> element must contain a cols attribute and may contain colsep, rowsep, and align (ignored by Docutils). Via the %tbl.tgroup.att parameter entity, <tgroup> supports the common attributes.

Tables usually consist of a single <tgroup>. Complex tables with widely varying column specifications may be easier to code using multiple <tgroup>s. However, this is not supported by table markup in reStructuredText and Docutils table handling routines.

#### Examples

See <table>.

### <thead>

The <thead> element identifies the row(s) that form the head of a <table> (as distinct from the body rows). It is defined in the Exchange Table Model.

Category:

  Body Subelements (compound)

Analogues:

  <thead> is analogous to the <thead> element in HTML and DocBook.

Processing:

  Header rows are always rendered at the beginning of the table and often presented in an alternate typographic style, such as boldface. In paged media, if a table spans across multiple pages, header rows are printed at the top of each new page.

Parent:

  <tgroup>

Children:

  one or more <row> elements

Attributes:

  the valign attribute (ignored by Docutils) and (via the %tbl.thead.att parameter entity) the common attributes.

#### Examples

See <table>.

### <tip>

The <tip> element is a specific admonition, a distinctive and self-contained notice.

Category:

  Compound Body Elements

Analogues:

  <tip> is analogous to the DocBook <tip> element.

Processing:

  Rendered distinctly (inset and/or in a box, etc.), with the generated title "Tip" (or similar).

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  one or more body elements

Attributes:

  only the common attributes.

See also the generic <admonition> and the other specific admonition elements.

#### Examples

A reStructuredText "tip" directive:

    .. Tip:: 15% if the service is good.

Pseudo-XML fragment from simple parsing:

    <tip>
        <paragraph>
            15% if the service is good.

### <title>

The <title> element stores the heading of a <document>, structural elements, or a generic <admonition>. It is also used for the caption of a <table>.

Category:

  Structural Subelements, Body Subelements (simple)

Analogues:

  <title> is analogous to the DocBook <title> element. In difference to the HTML section heading elements (<h1>, …, <h6>), the heading level is solely determined by the nesting level of the parent <section>. As child of a <table>, <title> corresponds to the HTML <caption> element.

  Note

  The HTML <title> element corresponds to the document's title attribute (metadata title).

Parents:

  <admonition>, <document>, <section>, <sidebar>, <table>, and <topic>

Children:

  text data plus inline elements (%text.model)

Attributes:

  refid (used as a backlink to a table of contents entry), auto (for auto-numbered section titles), and the common attributes.

The displayed <title> of a <document> may differ from its metadata title that is stored in the title attribute.

#### Examples

Section titles are marked up with "underlines" below the title text (or underlines and matching overlines):

    A Title
    =======

    A paragraph.

    Next section's title
    ====================

Pseudo-XML fragment from simple parsing:

    <section ids="a-title" names="a\ title">
        <title>
            A Title
        <paragraph>
            A paragraph.
    <section ids="next-section-s-title" names="next\ section's\ title">
        <title>
            Next section’s title

See also the examples for <admonition>, <document>, <section>, <sidebar>, <subtitle>, <table>, and <topic>.

### <title_reference>

The <title_reference> element is an inline element representing the titles of a cited creative work.

Category:

  Inline Elements

Analogues:

  <title_reference> is analogous to the HTML <cite> element and the DocBook <citetitle> element.

Processing:

  Typically displayed in italic type.

Parents:

  all elements employing %text.model in their content models

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

The reStructuredText "title-reference" role creates a <title_reference> element:

    The term "spam" is derived from the 1970 :title:`Spam` sketch.

Pseudo-XML fragment from simple parsing:

    <paragraph>
        The term “spam” is derived from the 1970
        <title_reference>
            Spam
         sketch.

### <topic>

The <topic> element represents a non-recursive section-like construct for content that is separate from the flow of the document.

Category:

  Structural Elements

Analogues:

  <topic> is analogous to the HTML <aside> element. The DocBook <simplesect> element is similar, but you cannot place body elements after a <simplesect>.

Processing:

  A <topic> element should be set off from the rest of the document somehow, such as with indentation or a border. In contrast to a <sidebar>, it should not float.

Parents:

  <document>, <section>, and <sidebar>

Children:

  <topic> elements may begin with a <title> and contain body elements:

      (title?, (%body.elements;)+)

Attributes:

  only the common attributes

Parameter Entities:

  %structure.model directly includes <topic>.

Topics are terminal, "leaf" mini-sections, like block quotes with titles, or textual figures. A <topic> is just like a <section>, except that it has no subsections, it does not get listed in the ToC, and it doesn't have to conform to section placement rules. You may place a <topic> in the middle of a <section> and continue the same section after it --- something that cannot be done with a nested <section>.

Topics cannot nest inside topics, or body elements (tables, lists, block quotes, etc).

Tip

Use a <rubric> element to get an informal heading inside a table, list, or inside another <topic>.

Docutils uses the <topic> element also for a generated table of contents, and the "abstract" and "dedication" bibliographic fields.

#### Examples

A reStructuredText "topic" directive:

    .. topic:: Title

       Body.

Pseudo-XML fragment from simple parsing:

    <topic>
        <title>
            Title
        <paragraph>
            Body.

### <transition>

The <transition> element separates body elements and sections, dividing a <section> into untitled divisions.

Category:

  Structural Subelements

Analogues:

  <transition> is analogous to the HTML <hr> element.

Processing:

  The <transition> element is typically rendered as vertical whitespace (more than that separating paragraphs), with or without a horizontal line or row of asterisks. In novels, transitions are often represented as a row of three well-spaced asterisks or a vignette with vertical space above and below.

Parents:

  <document>, <section> (cf. %structure.model)

Children:

  none (empty)

Attributes:

  only the common attributes

Parameter Entities:

  The %structure.model directly includes <transition>.

The document model sets additional restrictions on the placement of <transitions>: [21]

- A transition may not be immediately adjacent to another transition, i.e., <transition> elements must be separated by other elements.

- A transition may not start the text of a document or section, i.e., a <transition> is invalid as first child or preceded by only <title>, <subtitle>, or invisible elements [16].

- A transition may not occur at the end of a document or section. [17] In other words, a <transition> is invalid as last child element or followed by only invisible elements [16].

See also Doctree Representation of Transitions in A Record of reStructuredText Syntax Alternatives.

[16] (1,2)

The elements <meta>, <pending>, <substitution_definition>, and <target> are not visible in the output document. The <decoration> element contains <header> and <footer> which move to the respective places.

[17]

In reStructuredText markup, a transition may appear to fall at the end of a section immediately before another section. The misc.Transitions transform recognizes this case and moves the transition so it separates the sections.

#### Examples

A transition in the reStructuredText source:

    Paragraph 1.

    --------

    Paragraph 2.

Complete pseudo-XML result after parsing:

    <document>
        <paragraph>
            Paragraph 1.
        <transition>
        <paragraph>
            Paragraph 2.

### <version>

The <version> element contains the version number of the document. It can be used alone or in conjunction with <revision>.

Category:

  Bibliographic Elements

Analogues:

  <version> may be considered analogous to the <revision>, <revnumber>, or <biblioid> DocBook elements.

Processing:

  Sometimes used with the RCS/CVS keyword "Revision". See <docinfo> and <revision>.

Parent:

  <docinfo>

Children:

  text data plus inline elements (%text.model)

Attributes:

  only the common attributes.

#### Examples

In reStructuredText, "version" is one of the registered bibliographic fields:

    Document Title
    ==============

    :Version: 1.1

Complete pseudo-XML result after parsing and applying transforms:

    <document ids="document-title" names="document title">
        <title>
            Document Title
        <docinfo>
            <version>
                1.1

See <docinfo> for a more complete example, including processing context.

### <warning>

The <warning> element is a specific admonition, a distinctive and self-contained notice.

Category:

  Compound Body Elements

Analogues:

  <warning> is analogous to the DocBook <warning> element.

Processing:

  Rendered distinctly (inset and/or in a box, etc.), with the generated title "Warning" (or similar).

Parents:

  all elements employing %body.elements or %structure.model in their content models

Children:

  one or more body elements

Attributes:

  only the common attributes.

See also the generic <admonition> and the other specific admonition elements.

#### Examples

A reStructuredText "warning" directive:

    .. WARNING:: Reader discretion is strongly advised.

Pseudo-XML fragment from simple parsing:

    <warning>
        <paragraph>
            Reader discretion is strongly advised.

## Attribute Types

### Standard Attribute Types

Standard attribute types are defined in the attribute types section of the XML 1.0 specification [xml1.0].

CDATA

  Character data. CDATA attributes may contain arbitrary text.

NMTOKEN

  A "name token". One or more of letters, digits, ".", "-", and "_".

NMTOKENS

  One or more space-separated NMTOKEN values.

EnumeratedType

  The attribute value may be one of a specified list of values.

### Custom Attribute Types

To highlight specific attribute value constraints, the Docutils Generic DTD defines custom attribute types via parameter entities that resolve to standard attribute types. In the docutils.nodes Python module, values are stored using the specified data types.

%classnames.type
  Space-separated list of class names. Resolves to NMTOKEN.
  Used in the classes attribute. Python data type: list[str].
%idref.type
  A reference to another element by one of its identifiers. Resolves to NMTOKEN. [22]
  Used in the refid attribute. Python data type: str.
%idrefs.type
  Space separated list of references to other elements by their identifiers. Resolves to NMTOKENS. [22]
  Used in the backrefs attribute. Python data type: list[str].
%ids.type
  A space-separated list of unique identifiers. Resolves to NMTOKENS. [22]
  Used in the ids attribute. Python data type: list[str].
%measure
  A number which may be immediately followed by a unit or percent sign. ReStructuredText supports CSS3 length units. Attributes may restrict the value to some range. Handling of values without unit depends on the writer/output format (see the writer-specific documentation in the user documentation for details). Resolves to CDATA.
  Used in the height and width attributes. Python data type: str.
%number
  The attribute value must be a positive interger. Resolves to NMTOKEN.
  Used in the level, morecols, morerows, scale, and start attributes. Python data type: int.
%refname.type
  A reference name. Resolves to CDATA.
  Used in the refname attribute. Python data type: str.
%refnames.type
  Space-separated list of reference names. (Backslash escaping is used for space characters inside a reference name.) Resolves to CDATA.
  Used in the names and dupnames attributes. Python data type: list[str].
%yesorno
  Boolean: False if zero ("0"), true for any other value. Resolves to NMTOKEN.
  Used in the anonymous, colsep, ltrim, rtrim, rowsep, and stub attributes. Python data type: bool.

### Common Attributes

Through the %basic.atts parameter entity, all elements except <meta> support the attributes ids, names or dupnames, source, and classes.

## Attribute Reference

### alt

Attribute type: CDATA. Default value: none.

The alt attribute is used to store a text description in the <image> element.

### align

Attribute type: EnumeratedType. Default value: none (inherit).

The align attribute is used in the <figure> and <table> elements via the %align-h.att parameter entity and in <image> via the %align-hv.att parameter entity to specify the alignment of the element within its parent element.

The Exchange Table Model uses align in the <colspec>, <entry>, and <tgroup> elements to specify the text alignment in table cells. It cannot be specified in reStructuredText and is ignored by Docutils.

### anonymous

Attribute type: %yesorno. Default value: none (implies no).

The anonymous attribute is used for unnamed hyperlinks in the <target> and <reference> elements (via the %anonymous.att parameter entity).

### auto

Attribute type: CDATA. Default value: none.

The auto attribute is used to indicate automatically-numbered <footnote>, <footnote_reference> and <title> elements (via the %auto.att parameter entity). In <footnote> and <footnote_reference> elements, it also carries information about the label type ("1": auto-numbered, "*": auto-symbol).

### backrefs

Attribute type: %idrefs.type. Default value: none.

The backrefs attribute contains a space-separated list of identifier references, used for backlinks in <footnote>, <citation>, and <system_message> elements (via the %backrefs.att parameter entity).

### bullet

Attribute type: CDATA. Default value: none.

The bullet attribute is used in the <bullet_list> element to record the style of bullet from the input data. In documents processed from reStructuredText, it contains one of "-", "+", or "*". It may be ignored in processing.

### classes

Attribute type: %classnames.type. Default value: none.

The classes attribute is a space separated list containing zero or more class names. It is one of the common attributes, shared by all Docutils elements.

The purpose of the attribute is to indicate an "is-a" variant relationship, to allow an extensible way of defining sub-classes of existing elements. It can be used to carry context forward between a Docutils Reader and Writer, when a custom structure is reduced to a standardized document tree. One common use is in conjunction with stylesheets, to add selection criteria. It should not be used to carry formatting instructions or arbitrary content.

The classes attribute's contents should be ignorable. Writers that are not familiar with the variant expressed should be able to ignore the attribute.

### char

Attribute type: CDATA. Default value: "" (no aligning character).

The char attribute is used in the <colspec> and <entry> elements to specify an alignment character.

The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.

### charoff

Attribute type: NMTOKEN. Default value: "50" (i.e. 50%).

The charoff attribute is used in <colspec> and <entry> elements to specify the horizontal offset of the alignment character when align is "char".

The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.

### colname

Attribute type: NMTOKEN. Default value: none.

The colname attribute is used in the <colspec> element to name a table column and in the <entry> element to reference a named column.

The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.

### colnum

Attribute type: NMTOKEN. Default value: none.

The colnum attribute is defined for the <colspec> element by the Exchange Table Model. It serves no functional purpose other than a consistency check.

### cols

Attribute type: NMTOKEN. Default value: none.

The cols attribute is used in the <tgroup> element to store the number of columns in a table group.

The attribute is defined in the Exchange Table Model (which see for details).

### colsep

Attribute type: %yesorno. Default value: none.

The colsep attribute is used in the <colspec>, <entry>, <table>, and <tgroup> elements to specify the presence or absence of a column separator (vertical ruling).

The attribute is defined in the Exchange Table Model It cannot be specified in reStructuredText and is ignored by Docutils.

### colwidth

Attribute type: CDATA. Default value: "1*"

The colwidth attribute is used in the <colspec> element to specify the column width.

The attribute is defined in the Exchange Table Model (which see for details) as either a proportional measure (positive number followed by "*", e.g., "5*" for 5 times the unit proportion , or just "*" for one unit proportion) or a fixed measure (e.g., 2.5cm). Docutils supports only proportional measures.

Important

Currently, Docutils stores "colwidth" values as numbers and interprets unitless values as proportional measures while the Exchange Table Model uses the default unit "pt". This will change in future versions of Docutils.

### delimiter

Attribute type: CDATA. Default value: none.

The delimiter attribute is used in the <option_argument> element and contains the text preceding the <option_argument>: either the text separating it from the <option_string> (typically either "=" or " ") or the text between option arguments (typically either "," or " ").

### dupnames

Attribute type: %refnames.type. Default value: none.

dupnames replaces the names attribute when there has been a naming conflict. It is one of the common attributes, shared by all Docutils elements.

### enumtype

Attribute type: EnumeratedType, one of "arabic", "loweralpha", "upperalpha", "lowerroman", or "upperroman". Default value: none.

The enumtype attribute is used in the <enumerated_list> element to record the intended enumeration sequence.

Supported values:
  arabic:

    1, 2, 3, ...

  loweralpha:

    a, b, c, ..., z

  upperalpha:

    A, B, C, ..., Z

  lowerroman:

    i, ii, iii, iv, ..., mmmmcmxcix [4999]

  upperroman:

    I, II, III, IV, ..., MMMMCMXCIX [4999]

### format

Attribute type: NMTOKENS. Default value: none.

The format attribute is used in the <raw> element. It contains one or more space separated output format names.

### frame

Attribute type: EnumeratedType (top|bottom|topbot|all|sides|none).
Default value: none (implied).

The frame attribute may be used in the <table> element to specify the table's outer frame.

The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.

### height

Attribute type: %measure. Default value: none.

The height attribute is used in the <image> element.

### ids

Attribute type: %ids.type. Default value: none.

The ids attribute is a space separated list containing one or more unique identifiers, typically assigned by the system. It is one of the common attributes, shared by all Docutils elements.

An XPath expression to select the element with identifier test is

    //*[contains(concat(' ', @ids, ' '), ' test ')]

(similar to selecting an element by CSS class).

### level

Attribute type: %number. Default value: none.

The level attribute is used in the <system_message> element to indicate the message's severity level. See also the "type" attribute.

### line

Attribute type: %number. Default value: none.

The line attribute is used in the <system_message> element to indicate the position of the reported problem in the document source. See also the source attribute.

### ltrim

Attribute type: %yesorno. Default value: none (implies no).

The ltrim attribute is used in the <substitution_definition> element.

### loading

Attribute type: EnumeratedType, one of "embed", "link", or "lazy". Default value: none.

The loading attribute is used in the <image> and <figure> elements to indicate the preferred handling by the Docutils writer. [18] The default depends on the writer and the "image_loading" configuration setting.

New in Docutils 0.21

[18]

Currently only recognized by the HTML5 writer. The ODF/ODT writer always embeds images in the output document, XML and LaTeX writers link to the image. The behaviour may change for the ODT and XML writers (images cannot be embedded in a LaTeX source).

### morecols

Attribute type: %number. Default value: none.

The morecols attribute is used in the <entry> element to specify an entry that spans several physical table columns. It is similar to the colspan attribute of HTML table cells (<th> and <td>).

The morecols attribute is defined in the %tbl.entry.att parameter entity.

### morerows

Attribute type: %number. Default value: none.

The morerows attribute is used in the <entry> element to specify an entry that spans several physical table rows. It is similar to the rowspan attribute of HTML table cells (<th> and <td>).

The attribute is defined in the Exchange Table Model (which see for details).

### name

Attribute type: NMTOKEN or CDATA. Default value: none.

The name attribute in the <meta> element accepts NMTOKEN values. The output format may limit valid values to a set of keywords (EnumeratedType).

The name attribute in the <reference> element holds the reference name of the referenced element. Whitespace is normalized but case is preserved.

The attribute will no longer be used with <reference> elements in Docutils 1.0.

### names

Attribute type: %refnames.type. Default value: none.

The names attribute is a space-separated list containing reference names of an element (spaces inside a name are backslash-escaped). It is one of the common attributes, shared by all Docutils elements.

Each reference name must be unique in its namespace; if there are name conflicts (two or more elements want to use the same name), the affected name will be transferred to the dupnames attribute on the duplicate element(s). The element can no longer be used as hyperlink target. [19]

An element may have both names and dupnames attributes, if the dupnames are from conflicting implicit hyperlink targets and the names from explicit hyperlink targets or a directive's name option.

[19]

See Implicit Hyperlink Targets for details of conflict resolution.

### namest

Attribute type: NMTOKEN. Default value: none.

The namest attribute is used in the <entry> element to specify the leftmost column of a span.

The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils which uses the morecols attribute instead.

### nameend

Attribute type: NMTOKEN. Default value: none.

The nameend attribute is used in the <entry> element to specify the rightmost column of a span.

The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils which uses the morecols attribute instead.

### pgwide

Attribute type: %yesorno. Default value: none (implies no).

The pgwide attribute is used in the <table> element to make the table span the full page width.

The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.

### prefix

Attribute type: CDATA. Default value: none.

The prefix attribute is used in the <enumerated_list> element to store the formatting characters used before the enumerator.

In documents originating from reStructuredText data, it will contain either "" (empty string) or "(" (left parenthesis). Writers may ignore this attribute.

### refid

Attribute type: %idref.type. Default value: none.

The refid attribute contains a reference to another element via one of its identifiers. It is used by the <citation_reference>, <footnote_reference>, <problematic>, <reference>, <target>, and <title> elements (via the %refid.att and %reference.atts parameter entities).

### refname

Attribute type: %refname.type. Default value: none.

The refname attribute contains a reference to one of the names of another element. It is used by the <citation_reference>, <footnote_reference>, <reference>, <substitution_reference>, and <target> elements (via the %refname.att and %reference.atts parameter entities).

On a <target> element, refname indicates an indirect target which may resolve to either an internal or external reference. Docutils transforms replace the refname attribute with a refid (refering to the same element) or a refuri (refering to an external ressource).

### refuri

Attribute type: CDATA. Default value: none.

The refuri attribute contains an external reference to a URI. It is used by the <target>, <reference>, <footnote_reference>, and <citation_reference> elements (via the %reference.atts parameter entity).

### rowsep

Attribute type: %yesorno. Default value: none (implies no).

The rowsep attribute may be used in the <colspec>, <entry>, <row>, <table>, and <tgroup> elements to specify the presence or absence of row separators (horizontal ruling).

The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.

### rtrim

Attribute type: %yesorno. Default value: none (implies no).

The rtrim attribute is used in the <substitution_definition> element.

### scale

Attribute type: %number. Default value: none.

The scale attribute is used in the <image> element to store a uniform scaling factor (integer percentage value).

### source

Attribute type: CDATA. Default value: none.

The source attribute stores the path, URI, or a description of the source that was used to produce the document tree. It is one of the common attributes but typically only used with the <document> and <system_message> elements.

An element's source attribute may differ from the main document source if the document is assembled from several sources (e.g. via the "include" directive).

Note

All docutils.nodes.Node instances also support internal source and line attributes for use in diagnostic output.

### start

Attribute type: %number. Default value: none (implies 1).

The start attribute is used in the <enumerated_list> element to store the ordinal value of the first item in the list, in decimal notation.

For lists beginning at value 1 ("1", "a", "A", "i", or "I"), this attribute may be omitted.

### stub

Attribute type: %yesorno. Default value: none.

The stub attribute is used in the <colspec> element to mark a table column as containing stubs (row titles, on the left). See also the "csv-table" and "list-table" directives.

The attribute is defined in the %tbl.colspec.att parameter entity.

### suffix

Attribute type: CDATA. Default value: none.

The suffix attribute is used in the <enumerated_list> element to store the formatting characters used after the enumerator.

In documents originating from reStructuredText data, it will contain either "." (period) or ")" (right parenthesis). Depending on the capabilities of the output format, this attribute may or may not affect processing.

### title

Attribute type: CDATA. Default value: none.

The title attribute is used in the <document> element to store the document's metadata title.

The attribute is set by the "title" directive or the DocTitle transform. It is typically not part of the rendered document but, for example, used as HTML <title> element and shown in a browser's title bar, a user's history or bookmarks, or search results. Its value may may differ from the displayed title which is stored in a <title> element.

### type

Attribute type: NMTOKEN. Default value: none.

The type attribute is used in the <system_message> element. It holds the name of the message's severity level (cf. the "level" attribute).

### uri

Attribute type: CDATA. Default value: none.

The uri attribute is used in the <image> and <figure> elements to refer to the image via a URI Reference [20]. [rfc3986]

Docutils applies the "root_prefix" configuration setting when a URI Reference starting with "/" is converted to a local filesystem path.

[20]

Examples are a full URI, an absolute-path reference (begins with a single slash character) or a relative-path reference (does not begin with a slash character).

### valign

Attribute type: EnumeratedType (top|middle|bottom).
Default value: none (inherit).

The valign attribute is used in the <entry>, <row>, <tbody>, and <thead> elements to specify the vertical text alignment within entries.

The attribute is defined in the Exchange Table Model. It cannot be specified in reStructuredText and is ignored by Docutils.

### width

Attribute type: %measure. Default value: none.

The width attribute is used in the <figure>, <image>, and <table> elements.

### xml:space

Attribute type: EnumeratedType, one of "default" or "preserve".
Default value: "preserve" (fixed).

The xml:space attribute is a standard XML attribute for whitespace-preserving elements. It is used by the <address>, <comment>, <doctest_block>, <literal_block>, <math_block>, and <raw> elements (via the %fixedspace.att parameter entity). It is a fixed attribute, meant to communicate to an XML parser that the element contains significant whitespace. The attribute value should not be set in a document instance.

## Parameter Entity Reference

Parameter entities are used to simplify the Docutils Generic DTD (share definitions and reduce duplication) and to allow it to be customized by wrapper DTDs (external client DTDs that use or import the`Docutils Generic` DTD).

Parameter entities may be overridden by wrapper DTDs, replacing the definitions below with custom definitions.

In addition, the Docutils Generic DTD defines parameter entities for custom attribute types.

### Attribute Entities

#### %align-h.att

The %align-h.att parameter entity contains the align attribute for horizontal alignment.

Entity definition:

    align (left | center | right) #IMPLIED

The <figure> and <table> elements directly employ the %align-h.att parameter entity in their attribute lists.

#### %align-hv.att

The %align-hv.att parameter entity contains the align attribute for horizontal and vertical alignment.

Entity definition:

    align (top | middle | bottom | left | center | right) #IMPLIED

The <image> element directly employs the %align-hv.att parameter entity in its attribute list.

#### %anonymous.att

The %anonymous.att parameter entity contains the anonymous attribute, used for unnamed hyperlinks.

Entity definition:

    anonymous %yesorno; #IMPLIED

The <reference> and <target> elements directly employ the %anonymous.att parameter entity in their attribute lists.

#### %auto.att

The %auto.att parameter entity contains the auto attribute, used to indicate an automatically-numbered footnote or title.

Entity definition:

    auto CDATA #IMPLIED

The <footnote>, <footnote_reference>, and <title> elements directly employ the %auto.att parameter entity in their attribute lists.

#### %backrefs.att

The %backrefs.att parameter entity contains the backrefs attribute, a space-separated list of id references, for backlinks.

Entity definition:

    backrefs %idrefs.type; #IMPLIED

The <citation>, <footnote>, and <system_message> elements directly employ the %backrefs.att parameter entity in their attribute lists.

#### %basic.atts

The %basic.atts parameter entity lists the common attributes. The %additional.basic.atts placeholder can be used by wrapper DTDs to extend %basic.atts.

Entity definition:

    ids      NMTOKENS  #IMPLIED
    names    CDATA     #IMPLIED
    dupnames CDATA     #IMPLIED
    source   CDATA     #IMPLIED
    classes  NMTOKENS  #IMPLIED
    %additional.basic.atts;

All elements except <meta> directly employ the %basic.atts parameter entity in their attribute lists.

#### %bodyatt

The %bodyatt parameter entity is defined in the Exchange Table Model to allow customization of the <table> element's attribute list.

The Docutils Generic DTD redefines it to add align, width, and the common attributes. (In Docutils versions ≥ 1.0, the %tbl.table.att parameter entity will be redefined instead.)

#### %fixedspace.att

The %fixedspace.att parameter entity contains the xml:space attribute, a standard XML attribute for whitespace-preserving elements.

Entity definition:

    xml:space (default | preserve) #FIXED 'preserve'

The %fixedspace.att parameter entity is directly employed in the attribute lists of the following elements: <address>, <comment>, <doctest_block>, <literal_block>, <math_block>, <raw>.

#### %reference.atts

The %reference.atts parameter entity groups together the refuri, refid, and refname attributes. The %additional.reference.atts placeholder can be used by wrapper DTDs to extend %reference.atts.

Entity definition:

    %refuri.att;
    %refid.att;
    %refname.att;
    %additional.reference.atts;

The <citation_reference>, <footnote_reference>, <reference>, and <target> elements directly employ the %reference.att parameter entity in their attribute lists.

#### %refid.att

The %refid.att parameter entity contains the refid attribute, an internal reference to the ids attribute of another element.

Entity definition:

    refid %idref.type; #IMPLIED

The <title> and <problematic> elements directly employ the %refid.att parameter entity in their attribute lists.

Via %reference.atts, the %refid.att parameter entity is indirectly employed in the attribute lists of the <citation_reference>, <footnote_reference>, <reference>, and <target> elements.

#### %refname.att

The %refname.att parameter entity contains the refname attribute, an internal reference to the names attribute of another element. On a <target> element, refname indicates an indirect target which may resolve to either an internal or external reference.

Entity definition:

    refname %refname.type; #IMPLIED

The <substitution_reference> element directly employs the %refname.att parameter entity in its attribute list.

Via %reference.atts, the %refname.att parameter entity is indirectly employed in the attribute lists of the <citation_reference>, <footnote_reference>, <reference>, and <target> elements.

#### %refuri.att

The %refuri.att parameter entity contains the refuri attribute, an external reference to a URI.

Entity definition:

    refuri CDATA #IMPLIED

Via %reference.atts, the %refuri.att parameter entity is indirectly employed in the attribute lists of the <citation_reference>, <footnote_reference>, <reference>, and <target> elements.

#### %tbl.colspec.att

The %tbl.colspec.att parameter entity is defined in the Exchange Table Model to allow customization of the <colspec> element's attribute list.

The Docutils Generic DTD redefines it to add stub and the common attributes.

#### %tbl.entry.att

The %tbl.entry.att parameter entity is defined in the Exchange Table Model to allow customization of the <entry> element's attribute list.

The Docutils Generic DTD redefines it to add morecols and the common attributes.

#### %tbl.row.att

The %tbl.row.att parameter entity is defined in the Exchange Table Model to allow customization of the <row> element's attribute list.

The Docutils Generic DTD redefines it to add the common attributes.

#### %tbl.table.att

The %tbl.table.att parameter entity is defined in the Exchange Table Model to allow customization of the <table> element's attribute list.

Docutils versions ≥ 1.0 will use %tbl.table.att (instead of the obsolete %bodyatt) to add align, width, and the common attributes.

#### %tbl.tbody.att

The %tbl.tbody.att parameter entity is defined in the Exchange Table Model to allow customization of the <tbody> element's attribute list.

The Docutils Generic DTD redefines it to add the common attributes.

#### %tbl.tgroup.att

The %tbl.tgroup.att parameter entity is defined in the Exchange Table Model to allow customization of the <tgroup> element's attribute list.

The Docutils Generic DTD redefines it to add the common attributes.

#### %tbl.thead.att

The %tbl.thead.att parameter entity is defined in the Exchange Table Model to allow customization of the <thead> element's attribute list.

The Docutils Generic DTD redefines it to add the common attributes.

### Element Category Entities

#### %bibliographic.elements

The %bibliographic.elements parameter entity contains an OR-list of all Bibliographic Elements. The %additional.bibliographic.elements placeholder can be used by wrapper DTDs to extend %bibliographic.elements.

Only the <docinfo> element directly employs the %bibliographic.elements parameter entity in its content model.

#### %body.elements

The %body.elements parameter entity contains an OR-list of all Body Elements.

The %additional.body.elements placeholder can be used by wrapper DTDs to extend %body.elements.

The %body.elements parameter entity is directly employed in the content models of the following elements: <admonition>, <attention>, <block_quote>, <caution>, <citation>, <compound>, <danger>, <definition>, <description>, <entry>, <error>, <field_body>, <footer>, <footnote>, <header>, <hint>, <important>, <legend>, <list_item>, <note>, <sidebar>, <system_message>, <tip>, <topic>, and <warning>

Via %structure.model, the %body.elements parameter entity is indirectly employed in the content models of the <document> and <section> elements.

#### %inline.elements

The %inline.elements parameter entity contains an OR-list of all Inline Elements. The %additional.inline.elements placeholder can be used by wrapper DTDs to extend %inline.elements.

The %inline.elements parameter entity is employed in the %text.model parameter entity.

#### %section.elements

The %section.elements parameter entity contains the <section> element. The %additional.section.elements placeholder can be used by wrapper DTDs to extend %section.elements.

Via %structure.model, the %section.elements parameter entity is indirectly employed in the content models of the <document> and <section> elements.

### Model Entities

#### %calstblx

The Docutils Generic DTD includes via the %calstblx parameter entity the XML Exchange Table Model DTD [tm9901] as an external DTD subset to define the elements <colspec>, <entry>, <row>, <table>, <tbody>, <tgroup>, and <thead>.

Entity definition:

    <!ENTITY % calstblx PUBLIC
        "-//OASIS//DTD XML Exchange Table Model 19990315//EN"
        "soextblx.dtd">

#### %structure.model

The %structure.model parameter entity encapsulates the hierarchical structure of a document and of its constituent parts. It contains body elements, structural elements, and the <transition> element. See the discussion in section Element Hierarchy above.

Simplified entity definition:

    ( ( %body.elements; | topic | sidebar | transition )*,
      ( %section.elements; | transition )* )

Each <document> or <section> contains zero or more body elements, topics, sidebars, or transitions, followed by zero or more sections (whose contents include this model), or transitions.

The actual entity definition is more complex,

    ( ( (%body.elements; | topic | sidebar)+, transition? )*,
      ( (%section.elements;),
        (transition?, (%section.elements;) )* )? )

because there are additional restrictions on <transition>s. [21]

The %structure.model parameter entity is directly employed in the content models of the <document> and <section> elements.

[21] (1,2)

The restrictions cannot be fully expressed in the language of DTDs without making the definition overly complicated. Docutils checks them in the misc.Transitions transform.

#### %tbl.entry.mdl

The %tbl.entry.mdl parameter entity is defined in the Exchange Table Model to allow customization of the <entry> element's content model.

The Docutils Generic DTD changes it to allow all body elements (including nested tables):

    (%body.elements;)*

#### %tbl.tgroup.mdl

The %tbl.tgroup.mdl parameter entity is defined in the Exchange Table Model to allow customization of the <tgroup> element's content model.

The Docutils Generic DTD changes it to require at least one <colspec> element:

    colspec+,thead?,tbody

#### %text.model

The %text.model parameter entity is used by simple elements that may contain phrasing content, i.e. text data mixed with inline elements.

Entity definition:

    (#PCDATA | %inline.elements;)*

The %text.model parameter entity is directly employed in the content models of the following elements: <abbreviation>, <acronym>, <address>, <attribution>, <author>, <caption>, <classifier>, <contact>, <copyright>, <date>, <doctest_block>, <emphasis>, <field_name>, <generated>, <inline>, <line>, <literal>, <literal_block>, <organization>, <paragraph>, <problematic>, <reference>, <revision>, <rubric>, <status>, <strong>, <subscript>, <substitution_definition>, <substitution_reference>, <subtitle>, <superscript>, <target>, <term>, <title>, <title_reference>, <version>

### Placeholders

The following empty placeholders are employed to allow easy extension of the corresponding parameter entity by wrapper DTDs:

%additional.basic.atts in %basic.atts,
%additional.bibliographic.elements in %bibliographic.elements,
%additional.body.elements in %body.elements,
%additional.inline.elements in %inline.elements,
%additional.reference.atts in %reference.atts, and
%additional.section.elements in %section.elements.

## Glossary

Class names

  define sub-classes of existing elements.

  Class names are used in the classes attribute (%classnames.type).

  Docutils employs the identifier normalization to ensure class names conform to both, HTML4.1 and CSS1.0 name requirements (the regular expression [a-z](-?[a-z0-9]+)*).

  In reStructuredText, custom class names can be specified using the "class" directive, a directive's class option, or custom interpreted text roles.

Identifiers

  are used for cross references in generated documents.

  Identifiers are used in the ids, refid, and backrefs attributes (%ids.type, %idref.type, or %idrefs.type) [22].

  Docutils employs the identifier normalization to comply with restrictions in the supported output formats (HTML4.1, HTML5, polyglot HTML, LaTeX, ODT, manpage, XML).

  Identifiers cannot be specified directly in reStructuredText. Docutils generates them from reference names or from the "auto_id_prefix" (prepending the "id_prefix" and appending numbers for disambiguation if required).

  [22] (1,2,3,4)

  The Docutils Generic DTD cannot use the ID, IDREF, and IDREFS standard types because elements do not adhere to the One ID per Element Type validity constraint.

Phrasing content

  is text data that may be intermixed with inline elements (cf. the %text.model parameter entity).

Pseudo-XML

  is a representation of XML where nesting is indicated by indentation and end-tags are not shown. Some of the precision of real XML is given up in exchange for easier readability. For example, the following are equivalent:

  Real XML:

      <document>
      <section ids="a-title" names="a title">
      <title>A Title</title>
      <paragraph>A paragraph.</paragraph>
      </section>
      </document>

  Pseudo-XML:

      <document>
          <section ids="a-title" names="a title">
              <title>
                  A Title
              <paragraph>
                  A paragraph.

Reference names

  are identifiers assigned in the markup.

  Reference names are used in the name, names, refname, and dupnames attributes (%refname.type or %refnames.type).

  Reference names may consist of any text. Whitespace is normalized. [23]

  Almost all elements in a document share a common namespace for reference names and match them ignoring case. Only <substitution_definition> and <substitution_reference> elements use a distinct namespace with case-sensitive but forgiving matching of reference names.

  In reStructuredText, reference names originate from internal hyperlink targets, a directive's name option, or the element's title or content and are used for internal cross-references.

  [23]

  Adjacent spaces, horizontal or vertical tabs, newlines, carriage returns, or form feeds, are replaced by a single space. Leading and trailing whitespace is removed.

Unit proportion

  is a length unit used in the definition of relative table column widths in the Exchange Table Model.

  Its definition boils down to

  > …, the unit proportion is determined by starting with the target table width […]. Reduce that by the sum of border widths, column ruling widths, and the fixed colwidths to get the available proportional width. […] Then the unit proportion is the available proportional width divided by the sum of the proportionality factors.

  > —Exchange Table Model, section 3.2.1

## Bibliography

[docutils.dtd]

Docutils Generic DTD, David Goodger, https://docutils.sourceforge.io/docs/ref/docutils.dtd.

[dpub-aria]

Digital Publishing WAI-ARIA Module 1.0, W3C Recommendation, https://www.w3.org/TR/dpub-aria-1.0/.

[epub-ssv]

EPUB 3 Structural Semantics Vocabulary, W3C Group Note, https://www.w3.org/TR/epub-ssv-11/.

[html.spec]

HTML Living Standard, WHATWG (Apple, Google, Mozilla, Microsoft), https://html.spec.whatwg.org.

[rfc3986]

Uniform Resource Identifier (URI): Generic Syntax, T. Berners-Lee, R. Fielding, and L. Masinter, STD 66, RFC 3986, January 2005, https://www.rfc-editor.org/info/rfc3986.

[tdg5.1]

DocBook 5.1: The Definitive Guide, Norman Walsh, https://tdg.docbook.org/tdg/5.1.

[tm9901]

XML Exchange Table Model Document Type Definition, Norman Walsh, OASIS Technical Memorandum 9901:1999, http://www.oasis-open.org/html/tm9901.html.

[xml1.0]

Extensible Markup Language (XML) 1.0, W3C Recommendation, https://www.w3.org/TR/xml/.