really generate HTML5 by default

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

diff --git a/doc/plugins/mdwn.mdwn b/doc/plugins/mdwn.mdwn
index af05310591356863a70613a20d25ed60c484fa1c..e22f68eda071d9bb7630bc644df311871e885bdd 100644 (file)
--- a/doc/plugins/mdwn.mdwn
+++ b/doc/plugins/mdwn.mdwn
@@ -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.
 
 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
 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.
+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
 
 [[!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/). Multimarkdown is
+[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
 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.
+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".