Specifying Configuration

[ramnathv]

There are two ways I could go about letting users specify configurations

The first is what I am doing currently. It has the benefit of simplicity, however throws the field wide open for namespace conflicts.

framework: io2012
theme: default
highlighter: highlight.js
hitheme: monokai

The alternate approach is to use what jekyll and ruhoh advocate. It is a little more complicated, but has the advantage of being robust to namespace conflicts. In addition, it allows the use of semantically correct names. For example, I can use theme both for the framework as well as the highlighter since they are namespaced.

framework: deck.js
deck.js:
  theme: swiss
  transition: horizontal-slide
highlighter: highlight.js
highlight.js:
  theme: hemisu-light

[ramnathv]

It also makes sense to let each widget specify its own configuration file which can be overridden by YAML front matter specified by the user. For example, the highlighter widget (once I re-implement it as a widget) can have the following config file

layout: prettify
prettify:
  theme: sons-of-obsidian
highlight.js: 
  theme: hemisu-light

During the first pass, I can read the default config.yml files from all widgets and add it to the payload and then use the user specified options to override these defaults.

[ramnathv]

Here is another case in point for more verbose config variables. I was thinking I could let user specified config override widget specified configuration. Continuing with the example from before, suppose I want to override the theme and highlighter. I would specify the following YAML front matter in my Rmd file.

highlighter: 
  layout: highlight.js
  highlight.js:
    theme: hemisu-light

The idea is that this will override the default configuration specified by the highlighter widget.

[ramnathv]

Let me think what happens if I allow user to override specs based on this YAML chunk

highlighter: highlight.js
highlight.js:
  theme: hemisu-light

Will it lead to conflicts in namespace?

[ramnathv]

It is very important to deal with namespace conflicts robustly. The main problem arises due to letting users override options through the slide deck directly. One option is to use a config.yml file in the root directory to specify these. The idea then would be that the main config.yml file overrides the config.yml files specified by each of the modules. I see several advantages with this approach:

1. It keeps the slide Rmd file uncluttered with config variables.
2. It allows multiple slide decks to share the same configuration (overriding can be provided easily)
3. It keeps the code base simpler and minimizes namespace conflicts.

[ramnathv]

Another advantage of having a config.yml file is that I can always run slidify from the root directory. Paths to libraries can be adjusted based on location of the Rmd file relative to the root, which minimizes unnecessary configuration options like url$lib.

Both showoff and landslide which I consider to be the best-of-the-breed (as far as markdown to html5 converters are concerned) use config files. While YAML front matter in the deck is a great idea, having a config file to specify additional configuration options makes a lot of sense, since they are likely to be used only by people who like to customize, who would naturally have the knowledge of tweaking YAML.

[ramnathv]

Here is a further complication. Let us suppose I run the following command

slidify('examples/test2.Rmd')

I would need to adjust paths. I can adjust paths to system assets by appending .. to all config urls. Now, knitr will run code chunks in the root directory, and save the md file to the root directory thereby avoiding all path issues. However, if I specify the output file as examples/test2.md, then knitr will save the file in the directory examples, but the code chunks will still be run from the root.

One solution is to set root.url to examples.

[ramnathv]

Here is another thought. I could allow arbitrary yaml files to feed data to the slide deck/blog. Each file can be namespaced by the file name so that conflicts don't arise. This idea will extend to widget config files too. For example, I can namespace highlighter config files with highlighter. Need to give this some more thought.