Docutils Transforms

Transform Priority Range Categories

DocInfo

Module:

frontmatter

Added by:

standalone Reader

Default priority:

340

Configuration setting:

docinfo_xform (default: True)

Given a document starting [1] with a field list, the DocInfo transform converts fields with registered bibliographic field names to the corresponding document tree elements becoming child elements of the <docinfo> element (except for "dedication" and "abstract", which become <topic> elements after <docinfo>).

For example, this document fragment:

<document>
    <title>
        Document Title
    <field_list>
        <field>
            <field_name>
                Author
            <field_body>
                <paragraph>
                    A. Name
        <field>
            <field_name>
                Status
            <field_body>
                <paragraph>
                    $RCSfile$
    ...

will be transformed to:

<document>
    <title>
        Document Title
    <docinfo>
        <author>
            A. Name
        <status>
            frontmatter.py
    ...

DocTitle

Module:

frontmatter

Added by:

standalone Reader

Default priority:

320

Configuration setting:

doctitle_xform (default: True)

Under the conditions explained below, the DocTitle transform converts the document's first section title(s) to a document title and subtitle.

1. If the document contains a single top-level section as its first body element, [2] the top-level section's title is used as document title and default metadata title. The top-level section's contents become the document's immediate contents.

2. If step 1 successfully determines the document title, the transform checks for a subtitle: If the lone top-level section itself contains a single second-level section as its first element, [2] that section's title is promoted to the document's subtitle, and that section's contents become the document's immediate contents.

The transform can be disabled with the doctitle_xform configuration setting or the corresponding --no-doc-title command line option.

Top-Level Title
===============
A paragraph.

<document>
    <section names="top-level\ title">
        <title>
            Top-Level Title
        <paragraph>
            A paragraph.

<document names="top-level\ title" title="Top-Level Title">
    <title>
        Top-Level Title
    <paragraph>
        A paragraph.

Top-Level Title
===============
Second-Level Title
~~~~~~~~~~~~~~~~~~

A paragraph.

<document names="top-level\ title">
    <title>
        Top-Level Title
    <subtitle names="second-level\ title">
        Second-Level Title
    <paragraph>
        A paragraph.

SectSubTitle

Module:

frontmatter

Added by:

standalone Reader

Default priority:

350

Configuration setting:

sectsubtitle_xform (default: False)

The SectSubTitle transform works like step 2 of the DocTitle transform, but for sections.

For example,

<section>
    <title>
        Title
    <section>
        <title>
            Subtitle
        ...

is transformed into

<section>
    <title>
        Title
    <subtitle>
        Subtitle
    ...

This transform is disabled by default.

PreBibliographic Elements

The document tree elements <comment>, <decoration>, <footer>, <header>, <meta>, <pending>, <raw>, <substitution_definition>, <subtitle>, <system_message>, <target>, and <title> are ignored when the DocTitle and DocInfo transforms check for elements before frontmatter candidates.

This means that in the reStructuredText source, comments, hyperlink targets, substitution definitions, and the directives "class", "default-role", "footer", "header", "meta", "raw", "sectnum", "sectnum", "target-notes", and "title" may be placed before the document title or bibliographic fields.

The DocTitle transform inserts document title and subtitle before these elements. DocInfo inserts the bibliographic fields before <comment>, <raw>, <substitution_definition>, and <target>.

For example, the document source:

.. a comment
.. |today| date::
.. _hypertarget: http://example.org
.. class:: spam
.. role:: ham
.. default-role:: ham
.. footer:: footer text
.. header:: header text
.. meta:: :test: value
.. raw:: html

   raw html text
.. sectnum::
.. target-notes::
.. title:: metadata document title

Top-Level Title
===============
Second-Level Title
~~~~~~~~~~~~~~~~~~

:date: |today|

is parsed and transformed to:

<document ids="top-level-title" names="top-level\ title"
          title="metadata document title">
    <title>
        Top-Level Title
    <subtitle ids="second-level-title" names="second-level\ title">
        Second-Level Title
    <meta content="value" name="test">
    <decoration>
        <header>
            <paragraph>
                header text
        <footer>
            <paragraph>
                footer text
    <docinfo>
        <date>
            2024-03-01
    <comment xml:space="preserve">
        a comment
    <substitution_definition names="today">
        2024-03-01
    <target ids="hypertarget" names="hypertarget" refuri="http://example.org">
    <raw classes="spam" format="html" xml:space="preserve">
        raw html text