Restructured Text

Every page in these docs, including this one, is a plain text file with a .rst extension written in Restructured Text (reST). reST is the default markup language for Sphinx 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:

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

Section
-------

Directives commonly used across these docs:

.. 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.