doc/todo/configurable_markdown_path.mdwn

   1 [[!template id=gitbranch branch=wtk/mdwn author="[[wtk]]"]]
   2
   3 summary
   4 =======
   5
   6 Make it easy to configure the Markdown implementation used by the
   7 [[plugins/mdwn]] plugin.  With this patch, you can set the path to an
   8 external Markdown executable in your ikiwiki config file.  If you do
   9 not set a path, the plugin will use the usual config options to
  10 determine which Perl module to use.
  11
  12 > This adds a configuration in which a new process has to be worked
  13 > for every single page rendered. Actually, it doesn't only add
  14 > such a configuration, it makes it be done by *default*.
  15 >
  16 > Markdown is ikiwiki's default, standard renderer. A configuration
  17 > that makes it slow will make ikiwiki look bad.
  18 >
  19 > I would not recommend using Gruber's perl markdown. It is old, terminally
  20 > buggy, and unmaintained. --[[Joey]] [[!tag reviewed]]
  21
  22 ----
  23
  24 I wasn't trying to make an external markdown the default, I was trying
  25 to make the currently hardcoded `/usr/bin/markdown` configurable.  It
  26 should only use an external process if `markdown_path` is set, which
  27 it is not by default.  Consider the following tests from clean checkouts:
  28
  29 Current ikiwiki trunk:
  30
  31     $ PERL5LIB="." time ikiwiki --setup docwiki.setup
  32     ...
  33     38.73user 0.62system 1:20.90elapsed 48%CPU (0avgtext+0avgdata 103040maxresident)k
  34     0inputs+6472outputs (0major+19448minor)pagefaults 0swaps
  35
  36 My mdwn branch:
  37
  38     $ PERL5LIB="." time ikiwiki --setup docwiki.setup
  39     ...
  40     Markdown: Text::Markdown::markdown()
  41     ...
  42     39.17user 0.73system 1:21.77elapsed 48%CPU (0avgtext+0avgdata 103072maxresident)k
  43     0inputs+6472outputs (0major+19537minor)pagefaults 0swaps
  44
  45 My mdwn branch with `markdown_path => "/usr/bin/markdown"` added in
  46 `docwiki.setup` (on my system, `/usr/bin/markdown` is a command-line
  47 wrapper for `Text::Markdown::markdown`).
  48
  49     $ PERL5LIB="." time ikiwiki --setup docwiki.setup
  50     ...
  51     Markdown: /usr/bin/markdown
  52     ...
  53     175.35user 18.99system 6:38.19elapsed 48%CPU (0avgtext+0avgdata 92320maxresident)k
  54     0inputs+17608outputs (0major+2189080minor)pagefaults 0swaps
  55
  56 So my patch doesn't make ikiwiki slow unless the user explicitly
  57 requests an extenral markdown, which they would presumably only do to
  58 work around bugs in their system's Perl implementation.
  59  -- [[wtk]]
  60
  61 > I was wrong about it being enabled by default, but I still don't like
  62 > the idea of a configuration that makes ikiwiki slow on mdwn files,
  63 > even if it is a nonstandard configuration. How hard can it be to install
  64 > the Text::Markdown library? --[[Joey]]