.. include:: ../header.txt
============================
The Docutils Document Tree
============================
A Guide to the Docutils DTD
***************************
:Author: David Goodger
:Contact: docutils-develop@lists.sourceforge.net
:Revision: $Revision: 9715 $
:Date: $Date: 2024-05-18 10:45:24 +0200 (Sa, 18. Mai 2024) $
:Copyright: This document has been placed in the public domain.
.. contents:: :depth: 1
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 DTD`_ XML document type definition, `docutils.dtd`_,
which is the definitive source for details of element structural
relationships.
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").
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.
.. raw:: html
.. table::
:class: e-hierarchy
:width: 65%
:widths: 1 2 1 1
:align: center
+------------------------------------------+
| `root element`_ (`\`_) |
+---+------------------------------+---+---+
| [`structural elements`_] | | |
+---+------------------------------+---+ +
| | [`structural subelements`_] | |
+---+----------------------------------+---+
| [`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.
.. contents:: :local:
Alternatively, we may classify elements by their content model:
.. class:: description
_`Compound elements`
| may contain child elements but no text data.
| Examples: `\`_, `\`_, `\
`_
_`Simple elements`
| may contain text data.
| Most simple elements have a mixed content model (`%text.model`_).
However, only `inline elements`_ may be intermixed with text. [#]_
| Examples: `\`_ (mixed), `\`_ (text-only)
_`Empty elements`
| contain neither child elements nor text.
| Category members: `\`_, `\`_, `\`_,
`\`_, `\`_
.. [#] 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.
.. class:: field-indent-11em
:Category members: `\`_
: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`_.
.. class:: field-indent-11em
:Category members: `\`_, `\`_, `\`_
:Docutils class: ``nodes.Structural``
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).
.. class:: narrow run-in
:Category members:
.. class:: narrow run-in
:empty: `\`_, `\`_
:simple: `\`_, `\`_
:compound: `\`_, `\`_
:Docutils classes: ``nodes.SubStructural``, ``nodes.SubRoot``
Decorative Elements
-------------------
Decorative elements are used to generate page headers and footers. They
are child elements of `\`_ and contain `body elements`_.
.. class:: field-indent-11em
:Category members: `\