doc/plugins/mdwn.mdwn

   1 [[!template id=plugin name=mdwn core=1 author="[[Joey]]"]]
   2 [[!tag type/format]]
   3
   4 This plugin lets ikwiki convert files with names ending in ".mdwn" to html.
   5 It uses the [[ikiwiki/markdown]] minimal markup language.
   6
   7 This is the standard markup language used by ikiwiki, although some others
   8 are also available in other plugins.
   9
  10 ## Implementations
  11
  12 There are several implementations of markdown support that can be used by
  13 this plugin. In order of preference:
  14
  15 * [Discount](http://www.pell.portland.or.us/~orc/Code/discount/),
  16   via the [[!cpan Text::Markdown::Discount]] perl module.
  17   This implementation is considered to be the default and is strongly
  18   recommended, but it is not mandatory because it requires an external
  19   C library.
  20 * The [[!cpan Text::Markdown]] perl module.
  21 * The [original version of markdown](http://daringfireball.net/projects/markdown/).
  22
  23 [[!cpan Text::MultiMarkdown]] can be used in order to use tables, footnotes,
  24 and other new features from the markdown variant called
  25 [multimarkdown](http://fletcherpenney.net/MultiMarkdown/) (some of which
  26 are also available in the recommended implementation, Discount). Multimarkdown is
  27 not enabled by default, but can be turned on via the `multimarkdown` option
  28 in the setup file. Note that multimarkdown's metadata and wikilinks
  29 features are disabled when it's used with ikiwiki. Also note that if the
  30 `multimarkdown` option is enabled, it takes priority over Discount, which
  31 might cause formatting that is understood by Discount to be ignored.
  32
  33
  34 ## Advanced options
  35
  36 * `nodiscount`: If set to 1, Text::Markdown::Discount will not be used
  37   even if it is available. The default is to use Discount if available,
  38   and this is recommended.
  39 * `multimarkdown`: If set to 1, Text::MultiMarkdown will be used in
  40   preference to Text::Markdown::Discount. The default is to not use
  41   MultiMarkdown, and this is recommended.
  42 * `mdwn_footnotes`: If set to 1, implementations that support it will
  43   recognise the footnote syntax originating in PHP Markdown Extra, with
  44   `Footnote reference[^1]` and `[^1]: Footnote definition`. The default
  45   is 1.
  46 * `mdwn_alpha_lists`: If set to 1, Text::Markdown::Discount will
  47   accept letters as well as numbers in ordered list markers. The
  48   default is 0, to avoid unintended parsing of lines that happen
  49   to begin with a letter and a dot, such as "C. S. Lewis was an
  50   author" or "M. Descartes was a philosopher".