Restructured Text
=================

Every page in these docs, including this one, is a plain text file with a ``.rst`` extension written in
`Restructured Text <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ (reST). reST is the
default markup language for `Sphinx <https://www.sphinx-doc.org/en/master/>`_ and is used instead of Markdown because
it natively supports the directives (``toctree``, ``code-block``, ``note``, ``post``, etc.) that Sphinx and ABlog rely on.

Cheatsheet: https://spl.hevs.io/spl-docs/writing/rst/cheatsheet.html

Section titles are underlined (and optionally overlined) with punctuation that is at least as long as the title.
Heading levels are set by the order in which each style first appears in a file, not by the character itself;
these docs use ``=`` for the page title and ``-`` for sections:

.. code-block:: rst

    Page Title
    ==========

    Section
    -------

Directives commonly used across these docs:

.. code-block:: rst

    .. toctree::
        :maxdepth: 1

        page_one
        page_two

    .. code-block:: bash

        $ echo "hello"

    .. note::

        A callout box.

    .. post:: 2024-01-01
        :tags: example
        :category: Docs
        :author: Sam Khalilian

        The ``post`` directive is provided by :doc:`ablog` and attaches blog metadata
        (date, tags, category, author) to a page so it shows up in the blog feed, archives
        and tag/category pages.