]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/commitdiff
Todo suggestion: support pre-pended YAML metadata blocks
authorJonathan Dowland <jon@dow.land>
Fri, 15 Oct 2021 21:03:31 +0000 (22:03 +0100)
committerJonathan Dowland <jon@dow.land>
Fri, 15 Oct 2021 21:04:12 +0000 (22:04 +0100)
doc/todo/support_mdwn_front_matter.mdwn [new file with mode: 0644]

diff --git a/doc/todo/support_mdwn_front_matter.mdwn b/doc/todo/support_mdwn_front_matter.mdwn
new file mode 100644 (file)
index 0000000..88bc7e5
--- /dev/null
@@ -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*