Using Less and ReSt to make nice looking documents

---

Not so long ago the only right way to transform markdown style documents into something decent was via LaTeX and thence into pdf.

These days HTML and CSS are the way to go it seems. Its just good enough and the toolchain is far far more likely to be available on your machine right now.

First steps

Lets see what a simple ReSt document looks like. We have the demo ReSt for the docutils project.

.. This is a comment. Note how any initial comments are moved by
   transforms to after the document title, subtitle, and docinfo.

================================
 reStructuredText Demonstration
================================

.. Above is the document title, and below is the subtitle.
   They are transformed from section titles after parsing.


Literal Blocks
--------------

Literal blocks are indicated with a double-colon ("::") at the end of
the preceding paragraph (over there ``-->``).  They can be indented::

    if literal_block:
        text = 'is left as-is'
        spaces_and_linebreaks = 'are preserved'
        markup_processing = None

Now this looks like the page here - a bit plain and boring.

But we want to sprinkle magic Bootstrap dust over it. Now boring people might suggest the correct way to do this is to alter the HTML-formatter in docutils and so get that to output HTML divs that bootstrap expects. This is actually the right way to do it but I wont for several reasons.

1. This is an article about configuring bootstrap, not docutils
2. docutils is a really dense impenetrable forest of code and I do not understand it nearly well enough to make a quick change.
3. I am pretty sure I can do this with a few lines of less. If so, result !