Sorry for delaying describing my suggestion. I can think of three different approaches to metadata I like. Weighing them all #3 seems most attractive to me, but I’ll go through all three hoping it makes sense to anyone who cares.
-
The first is what Pandoc does, use --- for the beginning marker, and ... for the end marker. This alligns well with YAML’s syntax definition, and if you find a --- that doesn’t have a complementry ... you can treat it as an HR for compatiility.
If you look at the source code for the CommonMark Spec you’ll find an example of this.
But its is important to note that Pandoc is alone in treating this combination as metadata. Since this approach clearly doesn’t produce the intended result in most implementations, calling it “Common” seems a big stretch to me.
-
The second and third approach avoid trying to overload the triple-dash, The second approach is using HTML/SGML declaration format to encapsulate YAML metadata. Same basic idea, just using delimiters that are far older: <! and >. In general Markdown-like languages just ignore this passing it on to the browser, and browsers ignore declarations they don’t recognize, so we make sure the browser won’t recognize it by starting with our very own new word: CommonMark. Then, for example, document metadata could look like this:
<!CommonMark:Metadata
Title: Testing Metadata
Author: foo bar
>
# Testing Metadata
The reaction of existing processors to this is mixed, but has more visually pleasing variations than the first, and both Markdown.pl and stmd generate HTML that displays pretty well on browsers I tested. Check it out on the preview tag of the above link:
As I see it stmd already handles that example exactly right. The only problem being it does require the blank line shown before correctly handling a heading. So using this notation, for metadata could be considered a convention, and not an extension. Mardown.pl renders it well too, except that it wraps this construct in a <p> element. In practice, the visual result of the extra <p> tag is mostly harmless, especially in context.
Drawbacks to the second approach include not being able to include either > or -- in the metadata since they are special in declarations. Since -- might be used as a part of a document seperator in YAML, and there seems to be no provision for escaping a > that isn’t the closing delimiter, this isn’t a great solution in terms of robustness and risk.
3. Possibly the best approach would be use of HTML/SGML Processing Instruction tags with an unrecognized namespace prefix, like CommonMark:… . This is much the same as the previous approach, except it uses <? and ?> as the delimiters. Browsers generally ignore processing instructions they don’t recognize too, and since the close delimiter is an unusual two-character combination, the risks are lower. Similar lack of special-treatment of the double-hyphen makes this the safest option I considered:
<?CommonMark:Metadata
Title: Testing Metadata
Author: foo bar
?>
# Testing Metadata
which seems to be rendered as well or better than the declaration syntax. This leaves me in a slight quandry because metadata is semantically closer to declaration than processing instruction, but as in in most cases I prefer safety over the semantics of somthing I know the browser will ignore.
The root cause that drives the required blank line is already under consideration, and I think its likely it can go away may go-away if the alternative described in Appendix B is invested in.
P.S. Some might suggest there’s a similar fourth alternatives, HTML comments. I don’t disagree, but being an old-timer, I consider comments a special case of declarations, and thus fits under #2 in the above list. Under HTML 5, that may no longer be technically true, but the difference in practice is nill, so don’t worry about it.