ReStructuredText on Jekyll

Written by
Date: 2012-12-30 13:41:00 00:00

ReStructuredText is a markup format to give format to documents.

When as a child I started with WordStar and then WordPerfect I liked how you can control the final format with markup symbols. Therefore I think is better to manage your documents as plain text documents with some markup language, then parse your document through a software that will output the HTML, PDF or whatever output format you would like.

With this blog I use John Gruber's Markdown, but it is rather limite (what also makes it simple), then, I think I will explore some other options, one of them may be ReStructuredText.

reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents. reStructuredText is designed for extensibility for specific application domains. The reStructuredText parser is a component of Docutils. reStructuredText is a revision and reinterpretation of the StructuredText and Setext lightweight markup systems.

The primary goal of reStructuredText is to define and implement a markup syntax for use in Python docstrings and other documentation domains, that is readable and simple, yet powerful enough for non-trivial use. The intended purpose of the markup is the conversion of reStructuredText documents into useful structured data formats.

– Docutils

What I like about ReStructuredText is its ability to create tables, better indented text, and definition lists.

Well, to install it, you will need to first install some extra software like: Docutils and RbST.

Installing Docutils:

pip install docutils

Installing RbST

gem install RbST

Now that you have all needed software, lets install the plugin.

Download it from here

And save it to your _plugins folder.

After that, all you need to do, is to start writing documents using ReStructuredText syntax and name those documents with .rst extension, Jekyll will parse them with the right parser.