From cabf1e1c24da7d7200064346a432244038e29f11 Mon Sep 17 00:00:00 2001 From: gryf Date: Sat, 4 May 2019 12:21:29 -0600 Subject: [PATCH] Readme update --- README.rst | 50 +++++++++++++++++++++++++++++++++++++------------- 1 file changed, 37 insertions(+), 13 deletions(-) diff --git a/README.rst b/README.rst index 26a4a68..a5f70e2 100644 --- a/README.rst +++ b/README.rst @@ -1,13 +1,32 @@ Overview ======== -This plugin is a fork of `jekyll-rst `_ that 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. +This plugin is a fork of `jekyll-rst `_ +that 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. -This version supports rst2html5 conversion but hasn't been tested for Octopress compatability. +This version supports rst2html5 conversion but hasn't been tested for Octopress +compatability. -The main change on this fork is that this version uses Nokogiri to extract the HTML body contents since rst2html5 doesn't return parts like rst2html. +The main change on this fork is that this version uses Nokogiri to extract the +HTML body contents since rst2html5 doesn't return parts like rst2html. + +There was also cherrypicked changes: + +* from `niktwenty3`_ + + * cbda0aa Minor edit + * fe2e42d Updated description about this fork + * e74e57e Changed converted to use rst2html5 Added rst2html5.py + +* from `yingziwu`_ + + * 5b8eef7 modify for python3 + +* from `tranch`_ + + z 830d4a4 Remove line number Requirements ============ @@ -16,11 +35,12 @@ Requirements * Docutils * Pygments * `RbST`_ +* `nokogiri`_ Installation ============ -1. Install Docutils and Pygments. +1. Install Docutils and Pygments. The most convenient way is to use virtualenv_burrito: @@ -33,9 +53,9 @@ Installation 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``. + If you use `bundler`_ with Octopress, add ``gem 'RbST'`` and ``gem + 'nokogiri'`` to your ``Gemfile`` in the ``development`` group, then run + ``bundle install``. Otherwise, ``gem install RbST nokogiri``. 3. Install the plugin. @@ -58,17 +78,17 @@ Installation .. 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 + 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``. +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 @@ -90,7 +110,7 @@ need to generate one yourself if using Jekyll:: Octopress Tips ============== -* Use ``.. more`` in your ReST documents to indicate where Octopress's +* 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 @@ -99,3 +119,7 @@ Octopress Tips .. _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/ +.. _nokogiri: https://nokogiri.org +.. _niktwenty3: https://github.com/niktwenty3/jekyll-rst2html5 +.. _yingziwu: https://github.com/yingziwu/jekyll-rst +.. _tranch: https://github.com/tranch/jekyll-rst