Universal syntax for Markdown

[Alan J. Hogan]

On document meta:

On Aug 13, 2011, at 7:14 PM, Waylan Limberg <waylan at gmail.com> wrote:


> Interestingly, after having this feature for a few years, I would

> instead prefer a separate library (like say YAML) which  reads and

> removes the metadata before passing the document on to markdown. In

> fact, the metadata could even alter some of the arguments passed to

> markdown, or perhaps skip calling markdown at all (basically like

> Jekyll - used by Github Pages). To me this is much more flexible and

> doesn't require markdown to define a metadata syntax at all. Just let

> YAML (or whatever spec is chosen) determine the syntax and we

> automatically get the benefits of that spec's well developed data

> structure.


Hyde (Jekyll in Python) does this too and it really feels nice. The ability to embed complex arbitrary data in some documents' metadata was very handy (when used in conjunction with the theme and other non-markdown languages).

Quoth Michel:


> I'd certainly not put metadata in a Markdown standard. I never felt like this feature belongs in Markdown at all, and I think Waylan has just put the decisive argument: what if in your metadata you want to specify a text format other than Markdown for the text body? It won't work. Localization of "standard" metadata keys is also an issue.

> 

> I know it's tempting to have one tool to do it all, but you can still built that do-it-all tool by calling Markdown for parsing the body of the document as needed. And that tool will have more power because it's not limited to Markdown.



Hard to argue against that.

And yet in some cases it may be useful to define, in a Markdown-successor standard, the area in which such metadata may exist.

For instance, when I used Hyde, the format was always:

---
metadata: here
more: meta
---

That is, the first line was three hyphens, then you had your metadata, then a line with three hyphens.

Now consider Simplenote (http://simple-note.appspot.com/). They have a feature called "live publishing" where your note becomes accessible, in a read-only manner, as a web page. With Markdown mode on, the published page is first run through Waylan's library.  And because your Simplenote can sync with any number of things and programs - from Scrivener and various third-party apps to your Dropbox or whatever else - it's possible you might want metadata in your Markdown note. Currently Simplenote doesn't do anything special with it, and the last line of your metadata will probably become an H2 when published. Yuck. But if the Markdown successor recognized that top area as being for metadata, then Simplenote could simply discard it (and pull out a `title` attribute if they felt ambitious). 

Or consider an ebook with metadata in each chapter's file, with those files also being published as webpages -- same thing, it would be great if the website automatically knew that the first bit of the file between the three-hyphen lines was metadata, OK to ignore or attempt to use as desired/instructed.

YAML is a fairly mature format and well-suited for document meta; whether that would be the preferred meta syntax, if any, is another whole discussion.  I just wanted to point out the benefits of a recognized approach to inserting metadata into documents.

Alan Hogan