jgm/pandoc — Issue #419: Metadata at the beginning of a document
Author: pvorb
Created: 2012-02-15 11:09:41+00:00
State: open

(Idea/feature request/RFC)

It would be great, if one could add some additional metadata in source files directly. As far as I know, the current approach with

```
% title
% author(s) (separated by semicolons)
% date
```

at the beginning of a file is the only way to add some basic information right now. But if you want to use other variables in your templates, you have to set them via the `--variable` flag, each time you compile your document.

I've elaborated a general format in which you may define some additional metadata for a document at it's beginning.

Here's an example from the corresponding [node module](https://github.com/pvorb/node-props):

```
title: How to use node.js
date: 2011-08-09T17:56:00
tags: [ example, node.js ]

Node.js is a new technology...
```

The first three lines contain the meta-information, whereas the remaining lines define the document. They two are divided by three line breaks (either `\n\n\n` or `\r\n\r\n\r\n`) resulting in two empty lines.

The metadata is in the [YAML][] format. I think this way, documents still look clean.

It would be great, if you could also use these variables in templates.

This is incompatible with the plain markdown specification. That's why it would be appropriate to add a `--metadata` flag or the like. Otherwise all existing documents that contain three line breaks lines in the text, would be invalid.

I think, it wouldn't be hard to implement this feature, since there already is a pretty good [YAML parser][yamlref] for haskell. Maybe I could do that in the next few days, but I haven't done any haskell programming before, so it may not be as slick as it could be.

I could also think of a variant that would align with the current approach: Adding `% ` in front of each line of the YAML front matter.

```
% title: How to use node.js
% date: 2011-08-09T17:56:00
% tags: [ example, node.js ]

Node.js is a new technology...
```

[yaml]: http://yaml.org/
[yamlref]: http://hackage.haskell.org/cgi-bin/hackage-scripts/package/YamlReference