From 97be3fbcf9e279c63a7cd5252b711664505e9f7a Mon Sep 17 00:00:00 2001
From: "Kyle J. McKay" <mackyle@gmail.com>
Date: Tue, 17 Nov 2020 18:49:53 -0700
Subject: [PATCH] syntax.md: document YAML front matter
Explain the syntax of the optional YAML front matter.
Include a few examples that demonstrate the known keys.
Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
---
syntax.md | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 108 insertions(+)
diff --git a/syntax.md b/syntax.md
index 1c3c751..e65b46b 100644
--- a/syntax.md
+++ b/syntax.md
@@ -30,6 +30,7 @@ Markdown: Syntax
* [Automatic Links]
* [Backslash Escapes]
* [XML Comments]
+ * [YAML Front Matter]
**Note:** This document is itself written using Markdown; you
@@ -1443,3 +1444,110 @@ comments from the final output.
[xml]: <https://www.w3.org/TR/xml/#sec-comments>
"XML Comments Specification"
+
+
+~~~~~~~~~~~~~~~~~
+YAML Front Matter
+~~~~~~~~~~~~~~~~~
+
+Unless disabled (see `Markdown.pl --help`), by default any YAML
+front matter that may be present will be stripped and processed
+before handling the rest of the document.
+
+To add YAML front matter, the very first line of the document
+must be exactly three (3) hyphens (`---`).
+
+The YAML front matter continues until a line consisting of
+exactly three (3) hyphens (`---`) or dots (`...`) or the end
+of the document is encountered.
+
+For maximum compatibility with some other markdown processors,
+end the YAML front matter with three (3) hyphens (`---`).
+
+Only very basic YAML processing directives are recognized:
+
+ * Blank lines
+ * YAML comments
+ * `key: ` _<value>_
+
+The _<value>_ part may be either bare or inside double quotes
+(in which case standard escapes are recognized).
+
+For example this document:
+
+ ---
+ # This is a YAML comment
+ title: This Is The Title
+ ...
+ This is the first *markdown* format line.
+
+contains YAML front matter that specifies a "title" value of
+"This Is The Title".
+
+This document:
+
+ ---
+ title: "Yes, Quoted\tTitle"
+ header_enum: true # comments allowed here too
+
+ # If display_metadata is set to true, then
+ # all YAML front matter values will be shown in
+ # a table prefixed to the output document.
+ #
+ # If display_metadata is set to false, then
+ # no such table will ever be prefixed to the output.
+ #
+ # If display_metadata is not set, then a table will
+ # only be prefixed if any unknown settings are encountered.
+
+ display_metadata: true
+ ---
+ # Main Header
+ first paragraph
+
+ Sub Header
+ ----------
+
+ first sub paragraph
+
+ ## Another Sub
+
+ second sub paragraph
+
+ Second Header
+ =============
+
+ third sub
+ ---------
+
+ sub sub para
+ ~~~~~~~~~~~~
+
+ first sub sub paragraph
+
+will produce this output:
+
+ <table>
+ <tr><th>display_metadata</th><th>header_enum</th><th>title</th></tr>
+ <tr><td>true</td><td>true</td><td>Yes, Quoted Title</td></tr>
+ </table>
+ <h1>1 Main Header</h1>
+ <p>first paragraph</p>
+ <h2>1.1 Sub Header</h2>
+ <p>first sub paragraph</p>
+ <h2>1.2 Another Sub</h2>
+ <p>second sub paragraph</p>
+ <h1>2 Second Header</h1>
+ <h2>2.1 third sub</h2>
+ <h3>2.1.1 sub sub para</h3>
+ <p>first sub sub paragraph</p>
+
+Notice that a table of metadata was prefixed because `header_enum`
+was set to `true` in the YAML front matter.
+
+Additionally, the headers were automatically numbered in a hierarchical
+fashion.
+
+If the output document was generated using `Markdown.pl --stub` then the
+title as shown in the prefixed table would have been used for the `<title>`
+of the document -- notice how the `\t` was expanded to a real tab character.