2008-07-21 13:31:57 +02:00
|
|
|
[[!template id=plugin name=mdwn core=1 author="[[Joey]]"]]
|
|
|
|
|
[[!tag type/format]]
|
2006-08-23 07:41:07 +02:00
|
|
|
|
|
|
|
|
This plugin lets ikwiki convert files with names ending in ".mdwn" to html.
|
2007-12-08 21:59:08 +01:00
|
|
|
It uses the [[ikiwiki/markdown]] minimal markup language.
|
2006-08-23 07:41:07 +02:00
|
|
|
|
|
|
|
|
This is the standard markup language used by ikiwiki, although some others
|
|
|
|
|
are also available in other plugins.
|
2008-05-13 18:43:25 +02:00
|
|
|
|
2017-05-16 08:58:12 +02:00
|
|
|
## Implementations
|
|
|
|
|
|
2008-05-13 18:43:25 +02:00
|
|
|
There are several implementations of markdown support that can be used by
|
discount support
mdwn: Can use the discount markdown library, via the
Text::Markdown::Discount perl module.
This is preferred if available since it's the fastest currently supported
markdown library, speeding up markdown rendering by a factor of 40.
That is to say, when only rendering a lot of markdown, discount is 40x
faster. When building a ikiwiki site, ikiwiki's other overhead gets in the
way, but I still see significant speedups. Building the ikiwiki docwiki
dropped from 62 to 45 seconds, for example.
However, when multimarkdown is enabled, Text::Markdown::Multimarkdown is
still used.
While discount contains some nonstandard markdown extensions,
including tables and footnotes, AFAICS most of them are not
enabled by default in the perl bindings.
I consider sticking to non-extended markdown a desirable thing, since this
is probably not the last markdown engine. In particular, sundown is waiting
in the wings to get packaged and get a perl binding.
----
Reviewing all the showdown extensions, here are the ones that are enabled:
centered paragraphs:
->centered<-
image sizes: [dust mite](http://dust.mite =150x150)
<style>..</style> blocks are eaten. The perl binding does not provide
access to the gathered CSS. This is not legal html anyway, so unlikely
to cause breakage.
2012-01-01 21:56:32 +01:00
|
|
|
this plugin. In order of preference:
|
|
|
|
|
|
|
|
|
|
* [Discount](http://www.pell.portland.or.us/~orc/Code/discount/),
|
|
|
|
|
via the [[!cpan Text::Markdown::Discount]] perl module.
|
2017-05-14 13:51:56 +02:00
|
|
|
This implementation is considered to be the default and is strongly
|
|
|
|
|
recommended, but it is not mandatory because it requires an external
|
|
|
|
|
C library.
|
discount support
mdwn: Can use the discount markdown library, via the
Text::Markdown::Discount perl module.
This is preferred if available since it's the fastest currently supported
markdown library, speeding up markdown rendering by a factor of 40.
That is to say, when only rendering a lot of markdown, discount is 40x
faster. When building a ikiwiki site, ikiwiki's other overhead gets in the
way, but I still see significant speedups. Building the ikiwiki docwiki
dropped from 62 to 45 seconds, for example.
However, when multimarkdown is enabled, Text::Markdown::Multimarkdown is
still used.
While discount contains some nonstandard markdown extensions,
including tables and footnotes, AFAICS most of them are not
enabled by default in the perl bindings.
I consider sticking to non-extended markdown a desirable thing, since this
is probably not the last markdown engine. In particular, sundown is waiting
in the wings to get packaged and get a perl binding.
----
Reviewing all the showdown extensions, here are the ones that are enabled:
centered paragraphs:
->centered<-
image sizes: [dust mite](http://dust.mite =150x150)
<style>..</style> blocks are eaten. The perl binding does not provide
access to the gathered CSS. This is not legal html anyway, so unlikely
to cause breakage.
2012-01-01 21:56:32 +01:00
|
|
|
* The [[!cpan Text::Markdown]] perl module.
|
|
|
|
|
* The [original version of markdown](http://daringfireball.net/projects/markdown/).
|
2008-05-13 18:43:25 +02:00
|
|
|
|
2009-08-31 01:17:45 +02:00
|
|
|
[[!cpan Text::MultiMarkdown]] can be used in order to use tables, footnotes,
|
|
|
|
|
and other new features from the markdown variant called
|
2017-05-14 13:53:24 +02:00
|
|
|
[multimarkdown](http://fletcherpenney.net/MultiMarkdown/) (some of which
|
|
|
|
|
are also available in the recommended implementation, Discount). Multimarkdown is
|
2009-08-31 01:17:45 +02:00
|
|
|
not enabled by default, but can be turned on via the `multimarkdown` option
|
|
|
|
|
in the setup file. Note that multimarkdown's metadata and wikilinks
|
2017-05-14 13:51:56 +02:00
|
|
|
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.
|
2017-05-16 08:58:12 +02:00
|
|
|
|
|
|
|
|
|
|
|
|
|
## 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
|
2017-05-16 09:28:04 +02:00
|
|
|
recognise the footnote syntax originating in PHP Markdown Extra, with
|
|
|
|
|
`Footnote reference[^1]` and `[^1]: Footnote definition`. The default
|
2017-05-16 08:58:12 +02:00
|
|
|
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".
|
