As your can see in http://talk.commonmark.org/t/metadata-in-documents/ , there was quite a debate on what metadata format to include. In conclusion, it is very useful, but tends to be very application specific.
There is quite a few request for a do not parse or show section. So with the idea from jgm and coding horror, perhaps this could be included.
A word next to the beginning on a fence is only present in the ast as an identifier that may be of use to certain applications that needs to distinguish between different non-parsed content. E.g. between YAML, and comments.
Do not parse or show this section:
Fencing is --- to --- or ***. If newline in content then should use !--- to !*** instead.
This can be located anywhere in the page, and is marked in the ast (but doesnât show in html output) . This is useful for slideshows applications, where horizontal rules is used as a delimiter between slides. Thus the --- to --- format, in that context can be seen in such applications as a âhorizontal rule + metadataâ e.g. new slide that has metadata specifying a particular css styling to use for that slide.
note: Even if commonmark doesnât specify a parser, a âbest practicesâ should be included. E.g. Front matter of a page will commonly be YAML, with a set of common parameters like author, date, title
No empty lines in content
---
CONTENT WITHOUT ANY NEW LINE INBETWEEN
E.G. YAML OR JSON CONTENT
---
or
---
CONTENT WITH NEW LINE INBETWEEN
E.G. YAML OR JSON CONTENT
...
empty line in content
:---
CONTENT WITH NEW LINE IN BETWEEN
E.G. slideshow notes
:---
or
:---
CONTENT WITHOUT ANY NEW LINE IN BETWEEN
E.G. slideshow notes
:...
nonparsed content label
---yaml
YAML: INSERT YAML HERE
---
---comment
Just a comment that will have `comment` as the label in ast
---
for stylistic purpose:
--------- yaml --------
YAML: INSERT YAML HERE
-----------------------
----------------------- comment -----------------------------
Just a comment that will have `comment` as the label in ast
-------------------------------------------------------------
This is used in in https://github.com/jonschlinkert/gray-matter
optional descriptive field.
Allows for distinguishing between metadata boxes, after content type is determined.
---yaml: slide01 ---
CSS: style.css
---
Examples
Jekyll (original inspiration)
---
layout: post
title: Blogging Like a Hacker
---
slideshow
Instead of example shown in http://remarkjs.com/#11 . We would use the no parse syntax like:
---
name: agenda 1
class: middle, center
---
# Agenda 1
The name of this slide is {{ name 1 }}.
---
name: agenda 2
class: middle, center
---
# Agenda 2
The name of this slide is {{ name 2 }}.
In remarkjs you would write like (might be nice to look, but is harder to accurately parse {for ignoring} ) this:
---
name: agenda 1
class: middle, center
# Agenda 1
The name of this slide is {{ name 1 }}.
---
name: agenda 2
class: middle, center
# Agenda 2
The name of this slide is {{ name 2 }}.