Jekyll style "do not show or parse" sections


#1

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 }}.

Metadata in documents
#2

Should we avoid using --- to --- form and only support --- to *** form? This is because the first form may conflict when rendering a text file like http://www.textfiles.com/uploads/oxiclean.txt

-------------------------------------------------------------------------

                       The Truth Behind OxiClean

                             by The Keeper

			  September 20, 1999

-------------------------------------------------------------------------

After sitting through about 15 minutes of the OxiClean infomercial the
other night, I sensed that they weren't telling me the whole truth. For
one thing, they kept insisting on the "naturalness" of the product and
how safe it was for everything, because it was non-toxic. I started
thinking "What kind of product exists that is natural, yet unheard of,
for cleaning - and contains oxygen?". What immediately came to my mind,
was, of course, nothing more than hydrogen peroxide...

Hydrogen peroxide? Could it be that simple? I figured I would do a bit
of research on the web the following morning (I watched the commercial

#3

(1) The delimiters would be three hyphens ---, so your example
would not be interpreted as having a metadata block. (2) The
alternative closing delimiter is ..., not ***.


#4

thanks for the heads up about the alt closing delim, noted and corrected in first post @jgm .

Good point about keeping 3 char --- as the indicator.

What is your opinion about including 'named, do-not-show sections` like below (as an addition to the standard delimiters)?:

--------- YAML --------
YAML: INSERT YAML HERE
.......................

----------------------- comment -----------------------------
Just a comment that will have `comment` as the label in ast
.............................................................

which would allow the parser to be informed as to the type of metadata between --- and ... .

It may be more than 3 char long, and is not strictly YAML delimiters, but it shouldn’t cause any parsing conflict, since it is much different from a pure horizontal rule.


#5

I’m in favour of using --- for both the opening and closing delimiter (for consistency). It would be worth discussing the arguments for including ... as a closing delimiter as well. Perhaps it is not needed?


#6

I would be incline to remove ... as well, since we should encourage consistency of fence being made of the same characters. (In the end we are markdown derivatives not YAML) . Plus I haven’t really seen ... being used much elsewhere, while jekyll is very popular.


Btw, doesn’t this feature strike you as being very similar to Block Directives? I mean, the only difference between the two is whether the content is shown or not by default. Especially if you used the named versions.

  ------ spoiler ------
  content here
  ---------------------

  :::::: spoiler ::::::
  content here
  :::::::::::::::::::::

so maybe both can hook to an extension directive, but by default the --- doesn’t show (and thus the directive will have to explicitly create the content). While the ::: version shows the content by default (but is modified by the directive).


#7

+++ Chris Alley [Dec 02 14 00:14 ]:

I’m in favour of using --- for both the opening and closing delimiter (for consistency). It would be worth discussing the arguments for including ... as a closing delimiter as well. Perhaps it is not needed?

One reason is that it’s standard YAML for closing a YAML document inside another document. Another reason is that it sometimes looks nicer when you’re using an editor with Markdown highlighting, since a --- will often be interpreted as a setext header.


#8

+++ mofosyne [Dec 02 14 03:30 ]:

I would be incline to remove ... as well, since we should encourage consistency of fence being made of the same characters. (In the end we are markdown derivatives not YAML) . Plus I haven’t really seen ... being used much elsewhere, while jekyll is very popular.

Pandoc uses it.

Btw, doesn’t this feature strike you as being very similar to Block Directives? I mean, the only difference between the two is whether the content is shown or not by default.

No, it’s completely different. The contents of block directives would be parsed as CommonMark blocks. The contents of this section would simply be skipped.


Support for <link> and/or <head>