doc/ikiwiki/markdown/discussion.mdwn

   1 There is an ongoing [effort to standardise Markdown][sm]; I think it would be nice to check whether this implementation is compliant with it.
   2
   3 [sm]: http://standardmarkdown.com/
   4
   5 http://standardmarkdown.com/
   6
   7 > IkiWiki's [[plugins/mdwn]] plugin does not contain an implementation
   8 > of Markdown: it relies on external libraries. It can currently use
   9 > any of these, most-preferred first:
  10 >
  11 > * [[!cpan Text::MultiMarkdown]], only if explicitly requested via
  12 >   `$config{multimarkdown}`
  13 > * [[!cpan Text::Markdown::Discount]], if not explicitly disabled
  14 >   via `$config{nodiscount}`
  15 > * [[!cpan Text::Markdown]]
  16 > * [[!cpan Markdown]]
  17 > * `/usr/bin/markdown`
  18 >
  19 > In practice, Discount is the implementation pulled in by the
  20 > Debian package dependencies, and (I suspect) the most
  21 > commonly used with IkiWiki.
  22 >
  23 > If the selected external library (whatever it happens to be)
  24 > complies with a particular interpretation of Markdown, then
  25 > IkiWiki will too. If not, it won't. The only influence
  26 > IkiWiki has over its level of compliance with a particular
  27 > interpretation is in how we choose which external library
  28 > we prefer.
  29 >
  30 > As such, if you want IkiWiki to change its interpretation of
  31 > Markdown, the way to do that is to either change Discount's
  32 > interpretation of Markdown, or contribute a patch to make
  33 > `mdwn.pm` prefer a different (and presumably "more compliant")
  34 > Markdown implementation.
  35 >
  36 > IkiWiki has one syntax extension beyond Markdown, which is
  37 > that text enclosed in double-square-brackets is an IkiWiki
  38 > [[ikiwiki/wikilink]] or [[ikiwiki/directive]]. This applies
  39 > to any markup language used with IkiWiki, not just Markdown.
  40 >
  41 > (There also doesn't seem to be any consensus that labelling
  42 > any particular fork of Markdown as "standard" can make it the
  43 > truth, or that this particular fork is the Correct™ fork and not
  44 > just <https://xkcd.com/927/>; but that's between the authors of
  45 > Markdown implementations and those who want to standardize
  46 > Markdown, and it isn't IkiWiki's job to police that.)
  47 >
  48 > --[[smcv]]