reStructuredText

The plugin flamingo.plugins.reStructuredText adds support for reStructuredText using docutils.

title: hello world


Hello World!
============

Lorem ipsum

Settings

RST_SETTINGS_OVERRIDES = {}

The parser sets some defaults in the reStructuredText parser settings. You can override them here. List of all settings: [link]

DEFAULT_IMAGE_TEMPLATE = 
'image.html'
DEFAULT_GALLERY_TEMPLATE = 
'gallery.html'
RST_IMAGE_EXTRA_OPTION_SPEC = {}
RST_GALLERY_EXTRA_OPTION_SPEC = {}
RST_IMAGE_DIRECTIVE_NAMES = ['img', 'image']
RST_GALLERY_DIRECTIVE_NAMES = ['gallery']
RST_IMAGE_CAPTION_RAW = False

When set to True no inline rst is allowed in image captions

RST_REMOVE_SYSTEM_MESSAGES_FROM_OUPUT = True

By default reStructuredText adds system messages to the HTML output

Images

Images get handled by a directive. All extra options can be left out. The first argument of the directive has to be the path to your image. If the path starts with a /, the path has to be absolute to the CONTENT_ROOT, if not, relative to the content file, the image is used in.

Image support gets handled by flamingo.plugins.rstImage.

.. image:: foo.png

.. image:: bar.png
    :template: 'image.html'  # if not set DEFAULT_IMAGE_TEMPLATE gets used
    :align: left  # possible values: 'left', 'center', 'right'
    :clear: both
    :width: 200px
    :height: 200px
    :link: www.example.org
    :alt: My bar image
    :title: My bar image

    This is the caption of my bar image.

Extending the image directive

If you need more options, you don't have to create a new image directive, you can extend the existing one.

# settings.py
from docutils.parsers.rst import directives

RST_IMAGE_EXTRA_OPTION_SPEC = {
    'licence': directives.unchanged,
}
.. image:: foo.png
    :license: Apache2
    :template: licensed_image.html
<!-- theme/templates/licensed_image.html -->
<img src="{{ content.url }}">
<p>This image is licensed under {{ content.license }}</p>

Galleries

Galleries are used to group images together.

.. gallery::

    .. image:: image1.png

        This is the first image of this gallery.

    .. image:: image1.png

        This is the second.

Code blocks

Code blocks are add support for pygments. To use code blocks flamingo has to be installed with pygments support.

# REQUIREMENTS.txt

flamingo[pygments]
.. code-block:: python

    for i in range(10):
        print(i)