Home / All Plugins

Available Plugins (52)


Top Contributors

Most Forked

Most Watched

Most Starred

Grok is a full stack web shop with engineers specializing in Ruby, Rails, PHP, javascript, databases, and general software architecture based in San Antonio, Texas.

We grok the web!

Plugin Information

jekyll-rst

A ReStructuredText plugin for Jekyll and Octopress


README.md

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
    $ git submodule add https://github.com/xdissent/jekyll-rst.git _plugins/jekyll-rst

    For Octopress:

    ::

    $ cd
    $ 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/