This plugin adds ReStructuredText_ support to Jekyll_ and Octopress_. It renders ReST in posts and pages, and provides a custom directive to support Octopress-compatible syntax highlighting.

Requirements

• Jekyll or Octopress >= 2.0
• Docutils
• Pygments
• RbST_

Installation

1. Install Docutils and Pygments.

   The most convenient way is to use virtualenv_burrito:

   ::

   $curl -s https://raw.github.com/brainsik/virtualenv-burrito/master/virtualenv-burrito.sh | bash$ source /Users/xdissent/.venvburrito/startup.sh $mkvirtualenv jekyll-rst$ pip install docutils pygments

2. Install RbST.

   If you use bundler_ with Octopress, add gem 'RbST' to your Gemfile in the development group, then run bundle install. Otherwise, gem install RbST.

3. Install the plugin.

   For Jekyll:

   ::

   $cd <jekyll-project-path>$ git submodule add https://github.com/xdissent/jekyll-rst.git _plugins/jekyll-rst

   For Octopress:

   ::

   $cd <octopress-project-path>$ git submodule add https://github.com/xdissent/jekyll-rst.git plugins/jekyll-rst

4. Start blogging in ReStructuredText. Any file with the .rst extension will be parsed as ReST and rendered into HTML.

   .. note:: Be sure to activate the jekyll-rst virtualenv before generating the site by issuing a workon jekyll-rst. I suggest you follow Harry Marr's advice_ and create a .venv file that will automatically activate the jekyll-rst virtualenv when you cd into your project.

Source Code Highlighting

A code-block ReST directive is registered and aliased as sourcecode. It adds syntax highlighting to code blocks in your documents::

.. code-block:: ruby

  # Output "I love ReST"
  say = "I love ReST"
  puts say

Optional arguments exist to supply a caption, link, and link title::

.. code-block:: console :caption: Read Hacker News on a budget :url: http://news.ycombinator.com :title: Hacker News

  $ curl http://news.ycombinator.com | less

Octopress already includes style sheets for syntax highlighting, but you'll need to generate one yourself if using Jekyll::

$ pygmentize -S default -f html > css/pygments.css

Octopress Tips

• Use .. more in your ReST documents to indicate where Octopress's excerpt tag should split your content for summary views.

.. _ReStructuredText: http://docutils.sourceforge.net/rst.html .. _Jekyll: http://jekyllrb.com/ .. _Octopress: http://octopress.com/ .. _RbST: http://rubygems.org/gems/RbST .. _bundler: http://gembundler.com/ .. _Harry Marr's advice: http://hmarr.com/2010/jan/19/making-virtualenv-play-nice-with-git/