From dab50d3b7c91c0ef444c4fc31879117e4824c406 Mon Sep 17 00:00:00 2001 From: Jonathan Dowland Date: Fri, 15 Oct 2021 22:03:31 +0100 Subject: [PATCH] Todo suggestion: support pre-pended YAML metadata blocks --- doc/todo/support_mdwn_front_matter.mdwn | 36 +++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 doc/todo/support_mdwn_front_matter.mdwn diff --git a/doc/todo/support_mdwn_front_matter.mdwn b/doc/todo/support_mdwn_front_matter.mdwn new file mode 100644 index 000000000..88bc7e5f8 --- /dev/null +++ b/doc/todo/support_mdwn_front_matter.mdwn @@ -0,0 +1,36 @@ +A number of static site generators and/or Markdown implementations +support the notion of a "front matter", a (normally) YAML list pre- +pended before the document text, containing document metadata. E.g.: + + --- + title: how to blog + author: Joe Bloggs + --- + document goes here + +IkiWiki has (currently) made a deliberate decision not to support these (or +more precisely, the similar but different Pandoc-style block with lines +prefixed by '%'). Quoting `mdwn.pm` (here in the section that handles +*Discount*): + + # Disable Pandoc-style % Title, % Author, % Date + # Use the meta plugin instead + $always_flags |= Text::Markdown::Discount::MKD_NOHEADER(); + +It would be good to support YAML-formatted pre-pended metadata, +translating recognised keys into [[meta]] definitions, to aid +migration between IkiWiki and other static site generators: it +would aid the same source files being useable in multiple systems. + +This would require the `mdwn` plugin to be more closely-coupled to +the `meta` plugin, but not the reverse. I think this wouldn't be a +big problem, as the prospect of an IkiWiki site that was using the +`mdwn` plugin but *not* the `meta` plugin is fairly remote. And we +could make front-matter handling configurably on or off. + +References: + * [Pandoc extension yaml_metadata_block](https://pandoc.org/MANUAL.html#extension-yaml_metadata_block) + * [Hakyll 'pages and metadata'](https://jaspervdj.be/hakyll/tutorials/02-basics.html#pages-and-metadata) + * [Jekyll 'front matter'](https://jekyllrb.com/docs/front-matter/) + +*— [[Jon]], 2021-10-15* -- 2.39.2