.. include:: ../header.txt ============================ The Docutils Document Tree ============================ A Guide to the Docutils DTD *************************** :Author: David Goodger :Contact: docutils-develop@lists.sourceforge.net :Revision: $Revision: 9115 $ :Date: $Date: 2022-07-28 19:06:24 +0200 (Do, 28. Jul 2022) $ :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. This document does not discuss implementation details. Those can be found in internal documentation (docstrings) for the ``docutils.nodes`` module, where the document tree data structure is implemented in a class library. 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 `Introducing the Extensible Markup Language (XML)`_. The reStructuredText_ markup 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`_. .. _Docutils: https://docutils.sourceforge.io/ .. _Docutils Generic DTD: .. _Docutils DTD: .. _docutils.dtd: docutils.dtd .. _Introducing the Extensible Markup Language (XML): http://xml.coverpages.org/xmlIntro.html .. _reStructuredText: https://docutils.sourceforge.io/rst.html .. _A ReStructuredText Primer: ../user/rst/quickstart.html .. _reStructuredText Markup Specification: rst/restructuredtext.html ------------------- Element Hierarchy ------------------- .. contents:: :local: Below is a simplified diagram of the hierarchy of elements in the Docutils document tree structure. An element may contain any other elements immediately below it in the diagram. Notes are written in square brackets. Element types in parentheses indicate recursive or one-to-many relationships; sections may contain (sub)sections, tables contain further body elements, etc. :: +--------------------------------------------------------------------+ | document [may begin with a title, subtitle, decoration, docinfo] | | +--------------------------------------+ | | sections [each begins with a title] | +-----------------------------+-------------------------+------------+ | [body elements:] | (sections) | | | - literal | - lists | | - hyperlink +------------+ | | blocks | - tables | | targets | | para- | - doctest | - block | foot- | - sub. defs | | graphs | blocks | quotes | notes | - comments | +---------+-----------+----------+-------+--------------+ | [text]+ | [text] | (body elements) | [text] | | (inline +-----------+------------------+--------------+ | markup) | +---------+ The Docutils document model uses a simple, recursive model for section structure. A document_ node may contain body elements and section_ elements. Sections in turn may contain body elements and sections. The level (depth) of a section element is determined from its physical nesting level; unlike other document models (``