The Docutils Document Tree (original) (raw)

A Guide to the Docutils Generic DTD

David Goodger

Contact:

docutils-develop@lists.sourceforge.net

Revision:

10092

Date:

2025-04-17

This document has been placed in the public domain.

Contents

Element Hierarchy
Element Reference
Attribute Types
Attribute Reference
Parameter Entity Reference
Glossary
Bibliography

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 theDocutils 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 Pythonmodule 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 thereStructuredText 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 ()
[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.

Element Categories

Alternatively, we may classify elements by their content model:

Compound elements

may contain child elements but no text data.

Examples: <bullet_list>, ,

Simple elements

may contain text data.

Most simple elements support have a mixed content model. However, onlyinline elements may be intermixed with text (%text.model). [1]

Examples: (mixed), <literal_block> (text-only)

Empty elements

contain neither child elements nor text.

Category members: , , ,,

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:

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:

, ,

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:

simple:

Pseudo-XML:

A Title <paragraph> A paragraph. <p>Reference names</p> <p>are identifiers assigned in the markup.</p> <p>Reference names are used in the <a href="#name" title="null">name</a>, <a href="#names" title="null">names</a>, <a href="#refname" title="null">refname</a>, and <a href="#dupnames" title="null">dupnames</a>attributes (<a href="#refname-type" title="null">%refname.type</a> or <a href="#refnames-type" title="null">%refnames.type</a>).</p> <p>Reference names may consist of any text. Whitespace is normalized. <a href="#whitespace-normalization" title="null">[19]</a> <a href="rst/restructuredtext.html#hyperlinks" title="null" rel="noopener noreferrer">Hyperlinks</a>, <a href="rst/restructuredtext.html#footnotes" title="null" rel="noopener noreferrer">footnotes</a>, and <a href="rst/restructuredtext.html#citations" title="null" rel="noopener noreferrer">citations</a> all share the same namespace for reference names. Comparison ignores case.<a href="rst/restructuredtext.html#substitution-definitions" title="null" rel="noopener noreferrer">Substitutions</a> use a distinct namespace. Comparison is case-sensitive but forgiving.</p> <p>In reStructuredText, <a href="rst/restructuredtext.html#reference-names" title="null" rel="noopener noreferrer">reference names</a>originate from <a href="rst/restructuredtext.html#internal-hyperlink-targets" title="null" rel="noopener noreferrer">internal hyperlink targets</a>, a directive's <a href="rst/directives.html#name" title="null" rel="noopener noreferrer">name option</a>, or the element's title or content and are used for internal cross-references.</p> <h2 id="bibliography"><a class="anchor" aria-hidden="true" tabindex="-1" href="#bibliography"><svg class="octicon octicon-link" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg></a><a href="#toc-entry-7" title="null">Bibliography</a><a href="#bibliography" title="link to this section"></a></h2>