Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

A ReStructuredText plugin for Jekyll and Octopress

branch: master

Merge pull request #8 from vHanda/master

Use hashlib module instead of the deprecated md5 module
latest commit c6a78ef0b5
Greg Thornton authored
Octocat-spinner-32 .gitignore Initial commit December 17, 2011
Octocat-spinner-32 LICENSE.txt Initial commit December 17, 2011
Octocat-spinner-32 README.rst Fix indentation error in README December 17, 2011
Octocat-spinner-32 converter.rb Initial commit December 17, 2011
Octocat-spinner-32 directives.py Use hashlib module instead of the deprecated md5 module February 15, 2013
Octocat-spinner-32 rst2html.py Initial commit December 17, 2011
Octocat-spinner-32 transform.py Initial commit December 17, 2011
README.rst

Overview

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.
Something went wrong with that request. Please try again.