doc/todo/support_mdwn_front_matter.mdwn

   1 A number of static site generators and/or Markdown implementations
   2 support the notion of a "front matter", a (normally) YAML list pre-
   3 pended before the document text, containing document metadata. E.g.:
   4
   5     ---
   6     title: how to blog
   7     author: Joe Bloggs
   8     ---
   9     document goes here
  10
  11 IkiWiki has (currently) made a deliberate decision not to support these (or
  12 more precisely, the similar but different Pandoc-style block with lines
  13 prefixed by '%'). Quoting `mdwn.pm` (here in the section that handles
  14 *Discount*):
  15
  16     # Disable Pandoc-style % Title, % Author, % Date
  17     # Use the meta plugin instead
  18     $always_flags |= Text::Markdown::Discount::MKD_NOHEADER();
  19
  20 It would be good to support YAML-formatted pre-pended metadata,
  21 translating recognised keys into [[meta]] definitions, to aid
  22 migration between IkiWiki and other static site generators: it
  23 would aid the same source files being useable in multiple systems.
  24
  25 This would require the `mdwn` plugin to be more closely-coupled to
  26 the `meta` plugin, but not the reverse. I think this wouldn't be a
  27 big problem, as the prospect of an IkiWiki site that was using the
  28 `mdwn` plugin but *not* the `meta` plugin is fairly remote. And we
  29 could make front-matter handling configurably on or off.
  30
  31 References:
  32  * [Pandoc extension yaml_metadata_block](https://pandoc.org/MANUAL.html#extension-yaml_metadata_block)
  33  * [Hakyll 'pages and metadata'](https://jaspervdj.be/hakyll/tutorials/02-basics.html#pages-and-metadata)
  34  * [Jekyll 'front matter'](https://jekyllrb.com/docs/front-matter/)
  35
  36 *— [[Jon]], 2021-10-15*