README.md

PROSErial

under construction

Most staticsitegenerators use plain file to store their content in a mix from prose and structure. Front Matter is widely used by several other systems, like Jekyll or HUGO.

There are some confusing disadvantages for "normal" users:

• it is mandatory, if you just want to write text, users will stumble over the YAML front matter block
• files must begin with YAML Front Matter.

form

A "human-readable-writable content format" should start with a plain part in Markdown (or any other light markup) and after a delimiter structured content (for attributes, metadata, tagging etc). The position of structured content should be below the prose, prose is always more important.

Front-matter requires a start_delimiter and an end_delimiter. You can omit the delimiter next to end-of-file (or beginning) and use just one delimiter.

And structured content should be not be mandatory, somtimes you just want to have text. If you have only structured content, just start with the delimiter (like a shebang).

The structured content should use YAML. Beside yaml you could use JSON, xml or csv. Define this in the delimiter.

delimiter

To separate prose from yaml-structure you have to use a separator. This should be a string not already used, but easy to remember. Jekyll uses the yaml separator ''---'', but mandatory and before the prose.

Lets use the shebang (''#!'') and the used markup.

#!yaml
metakeywords: "some us less words used not by dr who"
pagetitle: "Some alternative title"

non yaml

If you want to use an alternative to yaml for structure:

#!json
{
  "metakeywords": "some us less words used not by dr who",
  "pagetitle": "Some alternative title"
}

or even

#!xml
<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <metakeywords>some us less words used not by dr who</metakeywords>
  <pagetitle>Some alternative title</pagetitle>
</root>

To have it more easier for users, use some, well known, syntax from prose. Often you need only key-values like wordpress custom fields. The html definition list is supported by some markdown implementations.

#!md
pagetitle
: Some alternative title
metakeywords
: some us less words used not by dr who

The advantage is, users could use the same syntax for key-values in prose text as for document structure.

Cons

Of course there are some disadvantages:

• not well formed like xml, (but it is possible to parse this md-yaml mixup)
• no datatype specification for structured data (but in most blogs or wikis most metadata are strings and dates)

In the wild

Not exactly PROSErial, but hitting my main requirement: optionality and end-of-file.

• pandoc extension-yaml_metadata_block

Status of this document

I thought about this while I was getting user feedack on my ssg drfly. I am very open for comments or change requests.