Extension:RstToHtml
 |
WARNING: The code or configuration described here poses a major security risk.
Site administrators: You are advised against using it until this security issue is resolved. Problem: Vulnerable to register_globals attacks. Solution: Always initialize every global variable. |
|
WARNING: The code or configuration described here poses a major security risk.
Site administrators: You are advised against using it until this security issue is resolved. Problem: Vulnerable to code injection attacks, because it passes user input directly to executable statements, such as exec(), passthru() or include(). This may lead to arbitrary code being run on your server, among other things Solution: strictly validate user input and/or apply escaping to all characters that have a special meaning in executable statements |
 |
This extension stores its source code on a wiki page. Please be aware that this code may be unreviewed or maliciously altered. They may contain security holes, outdated interfaces that are no longer compatible etc. Note: No localisation updates are provided for this extension by translatewiki.net. |
 Release status: beta |
|
|---|---|
| Implementation | Tag |
| Description | Use reStructuredText in MediaWiki pages |
| Author(s) | Paul Kippes |
| Last version | 0.1b (2008-01-31) |
| MediaWiki | 1.5 and up |
| License | No license specified |
| Download | No link |
| Check usage and version matrix; to HTML stats | |
Contents |
What is reStructuredText?[edit]
reStructuredText is a lightweight markup language intended to be highly readable in source format. A parser is implemented as a component of the Docutils text processing framework in Python. For help on creating reStructuredText, see reStructuredText Primer.
What does this extension do?[edit]
The extension hooks into your MediaWiki installation. A new tag <rst> invokes the reST parser to process the text into HTML.
Example[edit]
When this extension is installed, the following reST text would be formatted and presented in HTML. (A <source> tag prevents any parsing on this site.)
<rst>
Example Documentation
=====================
reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get plaintext
markup syntax and parser system. It is useful for inline program documentation
(such as Python docstrings), for quickly creating simple web pages, and for
standalone documents. reStructuredText_ is a proposed revision and
reinterpretation of the StructuredText_ and Setext_ lightweight markup systems.
reStructuredText_ is designed for extensibility for specific application
domains. Its parser is a component of Docutils_.
.. _StructuredText: http://www.zope.org/DevHome/Members/jim/StructuredTextWiki/FrontPage
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Setext: http://docutils.sourceforge.net/mirror/setext.html
.. _Docutils: http://docutils.sourceforge.net
More Examples
-------------
Tables are quite simple to read and create with reStructureText. Two table
formats, grid and simple, are supported.
Grid Table Example
~~~~~~~~~~~~~~~~~~
+------------+------------+-----------+
| Header 1 | Header 2 | Header 3 |
+============+============+===========+
| body row 1 | column 2 | column 3 |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may | - Cells |
+------------+ span rows. | - contain |
| body row 4 | | - blocks. |
+------------+------------+-----------+
Simple Table Example
~~~~~~~~~~~~~~~~~~~~
===== ===== ======
Inputs Output
------------ ------
A B A or B
===== ===== ======
False False False
True False True
False True True
True True True
===== ===== ======
Still More Examples
-------------------
Various formatting such as *emphasis* and **strong emphasis** and ``inline
literal`` are supported. Links to external websites may be fully listed,
http://www.google.com, or presented as anonymous_ links.
.. _anonymous: http://www.google.com
Lists are also easy to read and create:
- item 1
- item 2
- item 3
When literal text is required, it can be created::
Whitespace, newlines, blank lines, and
all kinds of markup (like *this* or
\this) is preserved by literal blocks.
</rst>
Where do I get the source?[edit]
Well....here. Save the following code to a file named rsttohtml.php.
NB. When installing this code (very nice thank you Paul) to MediaWiki 1.12.0 (and presumably others) it seems necessary to leave off the closing ?> tag else php returns headers after this script runs and the response object in mediawiki throws errors subsequently.
<?php # reStructuredText to HTML # version 0.1b (2008-01-31) # by Paul Kippes # Requires local installation of reStructuredText parser # See: http://docutils.sourceforge.net/rst.html # Update $rst2html for the appropriate location of rst2html.py $rst2html = '/usr/bin/rst2html.py'; $wgExtensionCredits['parserhook'][] = array( 'name' => 'RSTtoHTML', 'author' => 'Paul Kippes', 'url' => 'https://www.mediawiki.org/wiki/Extension:RstToHtml', 'description' => 'This extension parses reStructured Text into HTML'); $wgExtensionFunctions[] = 'rstRstToHtmlSetup'; function rstRstToHtmlSetup() { global $wgParser; $wgParser->setHook('rst', 'rstRstRender'); } function rstRstRender($input, $args, $parser) { global $rst2html; if (count($args)) { return "<strong class='error'>" . "reStructureText extension: arguments not supported" . "</strong>"; } if (!is_executable($rst2html)) { return "<strong class='error'>" . "reStructureText extension: No executable at $rst2html" . "</strong>"; } # If pipe errors are reported, enable output to the file. # But make certain the file doesn't already exist or else # the webserver may not have permission to create it. $io_desc = array( 0 => array('pipe', 'r'), 1 => array('pipe', 'w'), /* 2 => array('file', '/tmp/error-output.txt', 'a') */); $res = proc_open($rst2html . " --stylesheet-path='' " . "--initial-header-level=2 --no-doc-title " . "--no-file-insertion --no-raw", $io_desc, $pipes, '/tmp', NULL); if (is_resource($res)) { fwrite($pipes[0], $input); fclose($pipes[0]); $html = stream_get_contents($pipes[1]); fclose($pipes[1]); $html = preg_replace('/.*<body>\n(.*)<\/body>.*/s', '${1}', $html); } else { $html = "<strong class='error'>" . "reStructureText extension: error opening pipe" . "</strong>"; } return $html; } ?>
Docutils Installation[edit]
This extension requires docutils to be installed. As of this writing (18 January 2012), for example, the Ubuntu 11.10 package for Python 2.7 can be installed with
sudo apt-get install python-docutils
Once installed, the rst2html script will be installed to /usr/bin/rst2html. So with Ubuntu 11.10, the above MediaWiki script must be modified to this path. Use the whereis rst2html to locate the proper script if necessary.
The rst2html Python script can be verified by querying its version with rst2html --version.
Installation[edit]
Save the PHP source as rsttohtml.php to your extensions directory. Include the script in the LocalSettings.php file:
# Add support for reST to HTML extension
require_once('extensions/rsttohtml.php');
Issues[edit]
There seems to be no way to create an
[[internal link]]
(within the wiki, among pages) inside
<rst>...</rst>
The closest thing is:
<rst> `other page <index.php/Other_Page>`_ </rst>
and this is represented as an external link.
