xdissent / jekyll-rst Goto Github PK

A ReStructuredText plugin for Jekyll and Octopress

License: MIT License

Ruby 9.19% Python 90.81%

jekyll-rst's Introduction

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

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

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.

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

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.

jekyll-rst's People

Contributors

Stargazers

Watchers

jekyll-rst's Issues

Post rendered to empty when :math: role is used

for example, if put the below line into a post, the post rendered to empty. However, if removed the line, everything becomes ok.

The area of a circle is :math:A_\text{c} = (\pi/4) d^2.

Accents make fail html generation

Using the plugin in Octopress, the word "référentiel" for example in the middle of a text isn't displayed and all the content after too.
If I use rst2html.py throught python in plugins/jekyll, it generate the right document.
I suspect the converter.rb or maybe RbST of this behaviour.
Infortunately, I'm not a Rubyist, so debugging the short converter.rb is a bit hard at the moment.

ValueError: unknown locale: UTF-8

Hi,

I just tried using your Jekyll plugin, but I get an error about unknown locale.

Traceback (most recent call last):
  File "/Users/hiphish/Developer/feeling-responsive/_plugins/jekyll-rst/rst2html.py", line 25, in <module>
    from transform import transform
  File "/Users/hiphish/Developer/feeling-responsive/_plugins/jekyll-rst/transform.py", line 2, in <module>
    from docutils.core import publish_parts
  File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/core.py", line 20, in <module>
    from docutils import frontend, io, utils, readers, writers
  File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/frontend.py", line 41, in <module>
    import docutils.utils
  File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/utils/__init__.py", line 20, in <module>
    import docutils.io
  File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/io.py", line 18, in <module>
    from docutils.utils.error_reporting import locale_encoding, ErrorString, ErrorOutput
  File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/docutils/utils/error_reporting.py", line 47, in <module>
    locale_encoding = locale.getlocale()[1] or locale.getdefaultlocale()[1]
  File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/locale.py", line 543, in getdefaultlocale
    return _parse_localename(localename)
  File "/opt/local/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/locale.py", line 475, in _parse_localename
    raise ValueError, 'unknown locale: %s' % localename
ValueError: unknown locale: UTF-8

I have docutils and Pygments installed via pip, otherwise the traceback would not have found them. If I remove the frontmatter from my reST file the error goes away, but it doesn't get compiled obviously. Do you have any idea what is going on?

How to define global directives

For example:

.. role:: strike
   :class: strike

Hello, :strike:`this is a striked text`.

Right now this has to be done in each and every page

Octopress link in README is surely wrong

Hey,

In your README you have a link to http://octopress.com. I'm sure you meant http://octopress.org. That octopress.com website is a joke 😂

I would have submitted a PR myself but I have no idea how you edit hyperlinks in an rst file with GitHub Web... The text is just underlined in the web editor !?

Publish as official Gem?

I admit this is arguably a non-essential request, but since this repo seems to be the original source code for the project, can you publish "official" gems?

Based on the README, the normal way to install the plugin is to include it as a sub-module to my repo. I could disassociate the sub-module from Git, and just include the flat files. I could also just suck it up and deal with sub-modules. But I think it would make this project a bit more developer friendly if one could just run gem install jekyll-rst or put gem "jekyll-rst" in their Gemfile.

Does not work with YAML Front Matter

Not sure if I'm missing something here. But when I render a .rst file, it does not render any of the content.

For instance:

--
layout: post
title: Hello

---

This is RST content

This renders an HTML page with the correct title but without any content.