:title: Data Sources
:date: 2022-09-22

============
Data Sources
============

The diagram below shows the data sources and variables that can be used in
templates.

::

    ┌─────────────────┐
    │  settings.toml  ├───► site, pygments_theme ──┐
    └─────────────────┘                            │
                                                   │
    ┌─────────────────┐                   ┌────────▼────────┐
    │      *.rst      ├───► page, html ───► template.jinja2 │
    └────────┬────────┘                   └────────▲────────┘
             │                                     │
    ┌────────▼────────┐                            │
    │ Aggregated data ├───► aggr ──────────────────┘
    └─────────────────┘

\*.rst Files
============

The \*.rst files contain a part with document attributes called Docinfo (see
`field lists`_ and `bibliographic elements`_) and a part with the content of
the article.

You can come up with your own attributes. Attributes can contain only strings.

There some special attributes used by rSW:

============ =============== =========================
Attribute    Required        Deafult
============ =============== =========================
``type``     No              page
``template`` No              template.jinja2
``date``     Yes             None
``title``    No              None
============ =============== =========================

type
    Article type. Can be ​​post for blog posts or ``page`` for standalone
    pages.

template
    The template to be used when rendering the HTML page.

    The attribute value must be the path to the template file relative to the
    template directory. For example, the templates/index.jinja2 file would be:

    .. code-block:: rst

        :template: index.jinja2

    The path to the templates directory and default template can be overridden
    in **settings.toml**.

date
    Date in ISO format YYYY-MM-DD. This attribute is used to sort the list of
    posts. The date format can be overridden in **settings.toml**.

title
    Title of the article. It is not required and is not processed by rSW in
    any way, but it is desirable to fill it for use in templates.

.. note::

    The ``authors`` attribute is `special`_ and is not yet supported by rSW.
    Using ``authors`` will result in an error when building the site.

settings.toml
=============

The configuration file has a special ``site`` section, all data from which is
passed to the template unchanged. 

The structure and data types can be arbitrary. The file uses the
`TOML <https://toml.io/>`_ format.

For example, in this way you can pass basic information about the site:

.. code-block:: toml

    [site]
    title = 'My site'
    name = 'My awesome site'
    description = 'Awesome site about awesome things'
    datetime_format = '%d %b %Y'

A special variable ``pygments_theme`` is also passed to the template from the
configuration file. It contains the value of ``pygments.theme``.

Aggregated data
===============

A dictionary with aggregated data. This data is collected during site
generation before HTML-pages are rendered.

Aggregated data contains lists of blog posts and standalone pages.

The list of posts is sorted in descending order by date from the ``date``
attribute.

The next article will describe the use of this data in templates.

.. Links

.. _field lists: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html\#field-lists
.. _bibliographic elements: https://docutils.sourceforge.io/docs/ref/doctree.html#bibliographic-elements
.. _special: https://docutils.sourceforge.io/docs/ref/doctree.html#authors