* Add first draft at a Restructured Text (rst) plugin, by Sergio

[ikiwiki.git] / doc / plugins / rst.mdwn

diff --git a/doc/plugins/rst.mdwn b/doc/plugins/rst.mdwn
new file mode 100644 (file)
index 0000000..0f0d6f9
--- /dev/null
+++ b/doc/plugins/rst.mdwn
@@ -0,0 +1,24 @@
+This plugin lets ikwiki convert files with names ending in ".rst" to html.
+It uses the [reStructuredText](http://docutils.sourceforge.net/rst.html)
+markup syntax. You need to have the python-docutils module installed to use
+it.
+
+Note that this plugin does not interoperate very well with the rest of
+ikiwiki. Limitations include:
+
+* reStructuredText does not allow raw html to be inserted into
+  documents, but ikiwiki does so in many cases, including
+  [[WikiLinks|WikiLink]] and many
+  [[PreprocessorDirectives|PreprocessorDirective]].
+* It's slow; it forks a copy of python for each page. While there is a
+  perl version of the reStructuredText processor, it is not being kept in
+  sync with the standard version, so is not used.
+
+So while you may find this useful for importing old files into your wiki,
+using this as your main markup language in ikiwiki isn't recommended at
+this time.
+
+This plugin is included in ikiwiki, but not enabled by default.
+It was contributed by Sergio Talens-Oliag.
+
+[[tag type/format]]