115 lines
3.9 KiB
ReStructuredText
115 lines
3.9 KiB
ReStructuredText
: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
|