ReST for Markdown and Textile Users
ReStructuredText is freaking huge so users of lighter-weight markup languages can be easily put off. This is an absolute basics quickref to ReST for those kinds of users. Eye-ball the Closing at the bottom for a bit more perspective.
Just use non-alphanumeric characters to underline (or under-and-overline) your heading. It doesn’t matter what you use, just be consistent with the character you use for each header level:
========= Chapter 1 ========= Section 1.1 =========== Section 1.2 ----------- Section 1.3 +++++++++++ ========= Chapter 2 =========
Block quotes are just:
> Indented paragraphs, > >> and they may nest.
Use double backticks for inline code blocks like
`this example where otherwise *special characters* aren't processed`. Dig?
:: A paragraph containing only two colons (or ending in two colons) followed by an indented text block starts a code block. No ReST processing will happen in this block, so feel free to use funny characters. `!@#$%^&*()_+
ReST will automatically hyperlink any bare URLs.
Inline hyperlinks can be somewhat hard to read like this surrounded by text:
Inline hyperlinks can be somewhat hard to read `like this <http ://the-meaning-of-life.info/>`_ surrounded by text.
Fortunately reference-style links look_ very legible in text-format. And can even `span multiple words`_ (like you would expect!). .. _span multiple words: http://yourockthepartythatrocksthebody.com .. _look: http://the-universe-and-everything.info/
#. Lists are a bit trickier in ReST #. than in Markdown or Textile #. Place a blank line #. between sub-lists #. And line the bullet up #. exactly with the farthest left column of text of the parent list * Unordered lists work in exactly the same way * Just be careful to line the bullets up with the first text column of the parent list. Also, you can do multi-line bullet items if you're careful of the indentation. Definition Lists are easy Just indent the definition!
You can easily include images, along with some useful attributes (carefully line up subsequent lines with the parent!):
.. image:: http://path/to/image.png :alt: alternate text :class: class names
Banging out simple tables is also very quick:
===== ===== ====== Inputs Output ------------ ------ A B A or B ===== ===== ====== False False False True False True False True True True True True ===== ===== ======
If this quickref piqued your interest hit up the ReST
specification. It’s not very
easy to read, but it’s worth it. You can use alternate syntaxes for
marking-up lists, for example. There are many built-in mechanisms for
marking-up meta data such as for HTML
<meta> tags. There’s a robust
footnote and citation syntax. ReST generates references to key elements
in your document so you can link to them. Docutils'
start numbering headings at any level so you can seamlessly fit ReST
docs into your site hierarchy.
The reason ReST is preferable to Markdown or Textile is that it can be written as simply as the lighter-weight markup languages if you’re working on simple docs–but it doesn’t have to be. You may appreciate that down the road when you find you suddenly need one of your docs in PDF or XML format.