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.