Allow metadata specification in document using YAML front matter

[ramnathv]

I think it would be useful to allow a metadata block in the document where the title, author and date can be specified. I have two options on how to go about it. The main tradeoff is simplicity vs. extensibility. The pandoc style title blocks are very simple, but lack the ability to be extended. The jekyll or MMD style YAML front matter provides a lot of flexibility in the metadata that can be provided.

I think I am going to go with YAML front matter, due to the flexibility it offers. I need to think about importing YAML or just leaving it as a suggested package.

Pandoc Style Title Blocks

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

YAML Front Matter

Title:   A Sample MultiMarkdown Document  
Author:  Fletcher T. Penney  
Date:    February 9, 2011  
Comment: This is a comment intended to demonstrate  
         metadata that spans multiple lines, yet  
         is treated as a single value.  
Test:    And this is a new key-value pair  

[ramnathv]

The key design question is how to override options. By allowing YAML front matter in the document, I am allowing the user three options to specify metadata

1. Using the options parameter to slidify.
2. An external slidify.yml config file.
3. YAML front matter inside document.

Are so many options really needed? If I follow the philosophy of knitr, the key to making a document reproducible is to make it self contained. Moreover, more the options, the more complex the code becomes. I need to think through this one.

[ramnathv]

In order to keep slidify simple, I cannot rely on the user having to specify all metadata in the YAML block. So there has to be a have a set of defaults, which get overruled by the YAML front matter. The issue then is, if I allow (1) - (3) to specify YAML front matter, in what order do they overrule defaults.

Ideas

1. A simple way to merge (1) and (2) would be to allow options to accept either a named list or the name of a config file. Then it would be a simple matter of checking the class of options and read them accordingly.

[ramnathv]

Here are some more thoughts on the order in which configuration options can be checked

1. Options provided to slidify (either config file or list)
2. YAML front matter.
3. Config file slidify.yml

get_slidify_config <- function(options){
  deck <- get_slidify_defaults()
  if (!is.null(options)){
    if (is.list(options)){
      deck <- modifyList(deck, options)
    } else if(file.exists(options)){
      deck <- modifyList(deck, yaml.load_file(options))
    }
  }
}

[ramnathv]

The more I think of it, it appears that rendering a title slide is a specific instance of a template. So the user can specify any arbitrary parameters in the YAML front matter which will be available to use.