X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/fba4a198b58bdfb33590bda5eaf89bf96ed60099..6790e1804b66fb6623406ff33050db12412337f7:/doc/plugins/mdwn.mdwn

diff --git a/doc/plugins/mdwn.mdwn b/doc/plugins/mdwn.mdwn
index 07b59c3cf..e22f68eda 100644
--- a/doc/plugins/mdwn.mdwn
+++ b/doc/plugins/mdwn.mdwn
@@ -1,5 +1,5 @@
-[[template id=plugin name=mdwn core=1 author="[[Joey]]"]]
-[[tag type/format]]
+[[!template id=plugin name=mdwn core=1 author="[[Joey]]"]]
+[[!tag type/format]]
 
 This plugin lets ikwiki convert files with names ending in ".mdwn" to html.
 It uses the [[ikiwiki/markdown]] minimal markup language.
@@ -7,14 +7,44 @@ It uses the [[ikiwiki/markdown]] minimal markup language.
 This is the standard markup language used by ikiwiki, although some others
 are also available in other plugins.
 
+## Implementations
+
 There are several implementations of markdown support that can be used by
-this plugin. The [original version of
-markdown](http://daringfireball.net/projects/markdown/) can be used, or the
-[[cpan Text::Markdown]] perl module.
-
-[[cpan Text::Markdown]] also includes a markdown varient called
-[multimarkdown](http://fletcherpenney.net/MultiMarkdown/), which supports
-tables, footnotes, and other new features. Multimarkdown is not enabled by
-default, but can be turned on via the `multimarkdown` option in the setup
-file. Note that multimarkdown's metadata and wikilinks features are
-disabled when it's used with ikiwiki.
+this plugin. In order of preference:
+
+* [Discount](http://www.pell.portland.or.us/~orc/Code/discount/),
+  via the [[!cpan Text::Markdown::Discount]] perl module.
+  This implementation is considered to be the default and is strongly
+  recommended, but it is not mandatory because it requires an external
+  C library.
+* The [[!cpan Text::Markdown]] perl module.
+* The [original version of markdown](http://daringfireball.net/projects/markdown/).
+
+[[!cpan Text::MultiMarkdown]] can be used in order to use tables, footnotes,
+and other new features from the markdown variant called
+[multimarkdown](http://fletcherpenney.net/MultiMarkdown/) (some of which
+are also available in the recommended implementation, Discount). Multimarkdown is
+not enabled by default, but can be turned on via the `multimarkdown` option
+in the setup file. Note that multimarkdown's metadata and wikilinks
+features are disabled when it's used with ikiwiki. Also note that if the
+`multimarkdown` option is enabled, it takes priority over Discount, which
+might cause formatting that is understood by Discount to be ignored.
+
+
+## Advanced options
+
+* `nodiscount`: If set to 1, Text::Markdown::Discount will not be used
+  even if it is available. The default is to use Discount if available,
+  and this is recommended.
+* `multimarkdown`: If set to 1, Text::MultiMarkdown will be used in
+  preference to Text::Markdown::Discount. The default is to not use
+  MultiMarkdown, and this is recommended.
+* `mdwn_footnotes`: If set to 1, implementations that support it will
+  recognise the footnote syntax originating in PHP Markdown Extra, with
+  `Footnote reference[^1]` and `[^1]: Footnote definition`. The default
+  is 1.
+* `mdwn_alpha_lists`: If set to 1, Text::Markdown::Discount will
+  accept letters as well as numbers in ordered list markers. The
+  default is 0, to avoid unintended parsing of lines that happen
+  to begin with a letter and a dot, such as "C. S. Lewis was an
+  author" or "M. Descartes was a philosopher".