1
0
mirror of https://github.com/gryf/jekyll-rst.git synced 2025-12-19 04:20:21 +01:00

Readme update

This commit is contained in:
2019-05-04 12:21:29 -06:00
parent 11e2d51499
commit cabf1e1c24

View File

@@ -1,13 +1,32 @@
Overview Overview
======== ========
This plugin is a fork of `jekyll-rst <https://github.com/xdissent/jekyll-rst>`_ that adds `ReStructuredText`_ support to `Jekyll`_ and `Octopress`_. This plugin is a fork of `jekyll-rst <https://github.com/xdissent/jekyll-rst>`_
It renders ReST in posts and pages, and provides a custom directive to that adds `ReStructuredText`_ support to `Jekyll`_ and `Octopress`_. It
support Octopress-compatible syntax highlighting. 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 Requirements
============ ============
@@ -16,11 +35,12 @@ Requirements
* Docutils * Docutils
* Pygments * Pygments
* `RbST`_ * `RbST`_
* `nokogiri`_
Installation Installation
============ ============
1. Install Docutils and Pygments. 1. Install Docutils and Pygments.
The most convenient way is to use virtualenv_burrito: The most convenient way is to use virtualenv_burrito:
@@ -33,9 +53,9 @@ Installation
2. Install RbST. 2. Install RbST.
If you use `bundler`_ with Octopress, add ``gem 'RbST'`` to If you use `bundler`_ with Octopress, add ``gem 'RbST'`` and ``gem
your ``Gemfile`` in the ``development`` group, then run 'nokogiri'`` to your ``Gemfile`` in the ``development`` group, then run
``bundle install``. Otherwise, ``gem install RbST``. ``bundle install``. Otherwise, ``gem install RbST nokogiri``.
3. Install the plugin. 3. Install the plugin.
@@ -58,17 +78,17 @@ Installation
.. note:: Be sure to activate the ``jekyll-rst`` virtualenv before generating .. note:: Be sure to activate the ``jekyll-rst`` virtualenv before generating
the site by issuing a ``workon jekyll-rst``. I suggest you follow `Harry 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. activate the ``jekyll-rst`` virtualenv when you ``cd`` into your project.
Source Code Highlighting 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:: It adds syntax highlighting to code blocks in your documents::
.. code-block:: ruby .. code-block:: ruby
# Output "I love ReST" # Output "I love ReST"
say = "I love ReST" say = "I love ReST"
puts say puts say
@@ -90,7 +110,7 @@ need to generate one yourself if using Jekyll::
Octopress Tips 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. ``excerpt`` tag should split your content for summary views.
.. _ReStructuredText: http://docutils.sourceforge.net/rst.html .. _ReStructuredText: http://docutils.sourceforge.net/rst.html
@@ -99,3 +119,7 @@ Octopress Tips
.. _RbST: http://rubygems.org/gems/RbST .. _RbST: http://rubygems.org/gems/RbST
.. _bundler: http://gembundler.com/ .. _bundler: http://gembundler.com/
.. _Harry Marr's advice: http://hmarr.com/2010/jan/19/making-virtualenv-play-nice-with-git/ .. _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