skip to navigation
skip to content

Not Logged In

rst2html5 1.7.5

Generates (X)HTML5 documents from standalone reStructuredText sources

rst2html5

rst2html5 generates (X)HTML5 documents from standalone reStructuredText sources. It is a complete rewrite of the docutils’ rst2html and uses new HTML5 constructs such as <section> and <aside>.

Usage

$ rst2html5 [options] SOURCE

Options:

--no-indent Don’t indent output
--stylesheet=<URL or path>
 Specify a stylesheet URL to be included. (This option can be used multiple times)
--script=<URL or path>
 Specify a script URL to be included. (This option can be used multiple times)
--script-defer=<URL or path>
 Specify a script URL with a defer attribute to be included in the output HTML file. (This option can be used multiple times)
--script-async=<URL or path>
 Specify a script URL with a async attribute to be included in the output HTML file. (This option can be used multiple times)
--html-tag-attr=<attribute>
 Specify a html tag attribute. (This option can be used multiple times)
--template=<filename or text>
 Specify a filename or text to be used as the HTML5 output template. The template must have the {head} and {body} placeholders. The “<html{html_attr}>” placeholder is recommended.

Examples

Consider the following rst snippet:

Title
=====

Some text and a target to `Title 2`_. **strong emphasis**:

* item 1
* item 2

Title 2
=======

.. parsed-literal::

    Inline markup is supported, e.g. *emphasis*, **strong**, ``literal
    text``,
    _`hyperlink targets`, and `references <http://www.python.org/>`_

The html5 produced is clean and tidy:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
</head>
<body>
    <section id="title">
        <h1>Title</h1>
        <p>Some text and a target to <a href="#title-2">Title 2</a>. <strong>strong emphasis</strong>:</p>
        <ul>
            <li>item 1</li>
            <li>item 2</li>
        </ul>
    </section>
    <section id="title-2">
        <h1>Title 2</h1>
        <pre>Inline markup is supported, e.g. <em>emphasis</em>, <strong>strong</strong>, <code>literal
text</code>,
<a id="hyperlink-targets">hyperlink targets</a>, and <a href="http://www.python.org/">references</a></pre>
    </section>
</body>
</html>

No stylesheets or classes are spread over the html5 by default. However:

  1. Stylesheets and javascripts URLs or paths can be included through stylesheet and script options.

    $ rst2html5 example.rst \
    --stylesheet css/default.css \
    --stylesheet css/special.css \
    --script https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js
    
    <!DOCTYPE html>
    <html>
    <head>
        <meta charset="utf-8" />
        <link href="css/default.css" rel="stylesheet" />
        <link href="css/special.css" rel="stylesheet" />
        <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>
    ...
    
  2. Script attributes defer and async:

    $ rst2html5 example.rst \
    --script js/test1.js \
    --script-defer js/test2.js \
    --script-async js/test3.js
    
    <!DOCTYPE html>
    <html>
    <head>
        <meta charset="utf-8" />
        <script src="js/test1.js"></script>
        <script src="js/test2.js" defer="defer"></script>
        <script src="js/test3.js" async="async"></script>
    ...
    
  3. Html tag attributes can be included through html-tag-attr option:

    $ rst2html5 --html-tag-attr 'lang="pt-BR"' example.rst
    
    <!DOCTYPE html>
    <html lang="pt-BR">
    ...
    
  4. Classes can be explicitly associated to rst elements (see ref):

    .. class:: special
    
    This is a "special" paragraph.
    
    .. class:: exceptional remarkable
    
    An Exceptional Section
    ======================
    
    This is an ordinary paragraph.
    

    which results in:

    <p class="special">This is a "special" paragraph.</p>
    <section class="exceptional remarkable" id="an-exceptional-section">
        <h1>An Exceptional Section</h1>
        <p>This is an ordinary paragraph.</p>
    </section>
    
  5. Custom html5 template via the --template option. Example:

    $ template='<!DOCTYPE html>
    <html{html_attr}>
    <head>{head}    <!-- custom links and scripts -->
        <link href="css/default.css" rel="stylesheet" />
        <link href="css/pygments.css" rel="stylesheet" />
        <script src="http://code.jquery.com/jquery-latest.min.js"></script>
    </head>
    <body>{body}</body>
    </html>'
    
    $ echo 'one line' > example.rst
    
    $ rst2html5 --template "$template" example.rst
    
    <!DOCTYPE html>
    <html>
    <head>
        <meta charset="utf-8" />
        <!-- custom links and scripts -->
        <link href="css/default.css" rel="stylesheet" />
        <link href="css/pygments.css" rel="stylesheet" />
        <script src="http://code.jquery.com/jquery-latest.min.js"></script>
    </head>
    <body>
        <p>one line</p>
    </body>
    </html>
    

Installation

$ pip install rst2html5

rst2html5 Changelog

Here you can see the full list of changes between each rst2html5 releases.

1.7.4 - 2015-04-09

  • fixes deleted blank lines in <table><pre> during Genshi rendering
  • Testing does not depend on ordered tag attributes anymore

1.7.3 - 2015-04-04

  • fix some imports
  • Sphinx dependency removed

1.7.2 - 2015-03-31

  • Another small bugfix related to imports

1.7.1 - 2015-03-31

  • Fix 1.7 package installation. requirements.txt was missing

1.7 - 2015-03-31

  • Small bufix in setup.py
  • LICENSE file added to the project
  • Sublists are not under <blockquote> anymore
  • Never a <p> as a <li> first child
  • New CodeBlock directive merges docutils and sphinx CodeBlock directives
  • Generated codeblock cleaned up to a more HTML5 style: <pre data-language=”…”>…</pre>

1.6 - 2015-03-09

  • code-block’s :class: value should go to <pre class=”value”> instead of <pre><code class=”value”>
  • Fix problem with no files uploaded to Pypi in 1.5 version

1.5 - 2015-23-02

  • rst2html5 generates html5 comments
  • A few documentation improvementss

1.4 - 2014-09-21

  • Improved packaging
  • Using tox for testing management
  • Improved compatibility to Python3
  • Respect initial_header_level_setting
  • Container and compound directives map to div
  • rst2html5 now process field_list nodes
  • Additional tests
  • Multiple-time options should be specified multiple times, not with commas
  • Metatags are declared at the top of head
  • Only one link to mathjax script is generated

1.3 - 2014-04-21

  • Fixes #16 | New –template option
  • runtests.sh without parameter should keep current virtualenv

1.2 - 2014-02-16

  • Fix doc version

1.1 - 2014-02-16

  • rst2html5 works with docutils 0.11 and Genshi 0.7

1.0 - 2013-06-17

  • Documentation improvement
  • Added html-tag-attr, script-defer and script-async options
  • Dropped option-limit option
  • Fix bug with caption generation within table
  • Footer should be at the bottom of the page
  • Indent raw html
  • field-limit and option-limit are set to 0 (no limit)

0.10 - 2013-05-11

  • Support docutils 0.10
  • Force syntax_hightlight to ‘short’
  • Conforming to PEP8 and PyFlakes
  • Testing structure simplified
  • rst2html5.py refactored
  • Some bugfixes

0.9 - 2012-08-03

  • First public preview release
 
File Type Py Version Uploaded on Size
rst2html5-1.7.5.tar.gz (md5) Source 2015-05-14 54KB
rst2html5-1.7.5.zip (md5) Source 2015-05-14 64KB
  • Downloads (All Versions):
  • 28 downloads in the last day
  • 511 downloads in the last week
  • 2940 downloads in the last month