From: Jonathan Dowland <jon@dow.land>
Date: Fri, 15 Oct 2021 21:03:31 +0000 (+0100)
Subject: Todo suggestion: support pre-pended YAML metadata blocks
X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/commitdiff_plain/dab50d3b7c91c0ef444c4fc31879117e4824c406?hp=310c7a1d0b8d80aca5bdd548b3cac632d4ef7aab

Todo suggestion: support pre-pended YAML metadata blocks
---

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*