Btw just noticed that ascii doc way of doing document declaration is
**Writing Documentation using AsciiDoc
Joe Bloggs <email@example.com>
v2.0, February 2003:
Rewritten for version 2 release.**
perhaps we can auto recognize YAML blocks under a header( as metadata) or the start of a page (as document declaration).
First 3 line is the document declaration for the whole page. There is also a local meta data under the first header “The beginnings of time”
Title: Title for the top bar of any browser
The beginnings of time
Date_Edited: 24th of jan 2043
Last_Edit_by: Burko Ruffo
In the beginnings there were only darkness. But then with a keystroke, there was light.
metadata placed in div
<div title="Title for the top bar of any browser" date="32-4-2002" >
<div style="metadata date_edited">24th of jan 2043</div>
<div style="metadata last_edit_by">Burko Ruffo</div>
<h1> The beginnings of time </h1>
In the beginnings there were only darkness.
But then with a keystroke, there was light.
Hmmm… the document declaration metadata would probably be encased in meta tag and placed on top of html page.
This has the advantage of allowing sectioning of the page based on header or rules. E.g. with ruling for slideshow.
Should we use <section> ? or is div good enough? For this example, I’ll use section tag.
note: this is a test slide
# slide title
normal text here
<section id="slide1" style="slidestyle" >
<div class="metadata note" >
this is a test slide
<h1> slide title </h1>
normal text here
Initially thought for html representation of metadata, is to put it in attribute. But then I noticed that in resumes, people would type address and contact details in the same format. So I switch to div tags, but that seems rather limiting.
The beginnings of time
Date Edited: 24th of jan 2043
Last Edit by: Burko Ruffo
Will not be detected as a description list.
The beginnings of time
: 24th of jan 2043
Last Edit by
: Burko Ruffo
But this one would. However it seems rather verbose line wise. And most people type like the first one above. Plus it’s not very YAML like. I was aiming to keep to YAML syntax (or as close to it) as possible. There need to be another way… but alas I’m out of idea for today.
(edit: surely an exception could be made for metadata entries that are right after a header?)
The description list marker is similar to the other list markers (for ordered and unordered lists) in that it has to be at the start of the line to avoid clashes with the marker character mid-sentence. Very few lines would use a number+full stop combination, hyphen, asterisk, plus sign, or a colon at the start of a line, so it’s relatively safe to place them there. Even for lines that directly follow a heading there’s a good chance that the list marker characters will be used in the middle of the line. This would lead to all sorts of awkward character escaping which I think we can all agree is unappealing to look at.
I’d like to warn about YAML use. Though YAML is very nice for humans, it’s very difficult for correct implementation. Placing it to spec “as is” will create ass pain for client-side parsers. Mostly because of big size. I say this, as author of js-yaml - the most popular js implementation.
It worth to “officially” restrict some YAML features like omap, set, anchros, merge, custom types. That will make possible to create more fast and compact parser for YAML subset. IMHO, it would be enougth to support JSON types and (may be) Date.
Is there a “slim YAML” version? As in a minimal spec YAML for embedded use? (e.g. “commonmark core” and Lua)
Alternatively, we can just define our own restricted metadata syntax. But I think it would be nicer if the is a common standard for small parsing engine for metadata. Maybe I’ll shoot them an email (done. was sent to their mailing list).
Some naming idea for slim/restricted subset of YAML:
If I were to build a web app that uses markdown, I would make separate text fields for metadata anyway. I think the YAML metadata header is mainly useful if you work directly with (plain-text/markdown) files instead of web apps with potentially multiple text fields.
As such, metadata blocks should certainly be extensions and not “core spec”, because it doesn’t really make sense for client-side implementation, and as @vitaly said is hard to implement. This would save us the confusion of differentiating between a full YAML and a mini YAML, either an implementation supports it or it doesn’t, both is fine.
No. YAML spec contains definitions of reduced schemas, but those are not practical and do not cover restrictions on anchors and so on. There are some movement to JSON in upcoming YAML 2.0, but it’s upcoming > 2 years and there are no estimates when this finish
At first glance, it can be enougth if metadata contains stupid pairs:
If not - then “restricted” YAML should cover all needs.
I guess it depends on whats the purpose of including metadata support in documents.
Maybe the default metadata support should be restricted to the top of the page “document declaration”, which will be our own style of metadata that is YAML inspired. Much like how <meta> tag is only allowed in head tag of HTML. This is because I think that metadata placed haphazardly across the page is bad design, without explicit declaration of !YAML:.
As for full support for metadata. We should include it only as a recommended but not mandatory inclusion of a !YAML or !json generic directive.
e.g. example of a simple document declaration. You’ll put this on the top of the page. Maybe we put all the restricted YAML structured data here.
author: Bane Liciea
title: Why you should hire me
arrayName: [ val1, val2, val3 ]
Based on observation, this one supports the ---... fencing. Each entry can be either a Scalar key:value pair, or a sequence/list (via -), or map (restricted to scalar entries). Only supports a limited set of core types (Strings, Number, Date, Boolean, Null, space).
Pretty much perfect for usage as document declaration metadata. And should cover most use case of a typical writer (at least for me).