Skip to content
/ proserial Public

A format to include structured data into prose. Use markdown for text and optional yaml below for data.

License

Notifications You must be signed in to change notification settings

klml/proserial

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

32 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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:

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.

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.

About

A format to include structured data into prose. Use markdown for text and optional yaml below for data.

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published