Assets

I am getting closer to the best way to handle external assets used by slidify. However, there are still a couple of issues to be ironed out, a few decisions to be made, which is the reason behind this note.

To keep the discussion focused, I am going to use highlighters as an example. Highlighters are a type of widget which provide syntax highlighting to a slide deck. Slidify currently supports three highlighters highlight.js, prettify and highlight. Widgets similar to highlighters are comments and analytics and in all cases, only one of the many options can be used and each option will have multiple configuration items.

Here are two approaches I could use

Approach 1

Use a single config.yml file in the highlighters folder that contains everything. Here are the pros and cons of this approach

Pros

1. Single config file to manipulate.
2. Simplifies code to access elements.

Cons

1. Mixes HTML and configuration items.
2. Less modular since plug and play is no longer possible.

highlighter: highlight.js
highlight.js:
  theme: hemisu-light
  css:
    <link href="{{url.highlighters}}/highlight.js/css/{{hitheme}}.css" rel="stylesheet">
  js:
    after:
      <!-- LOAD HIGHLIGHTER JS FILES -->
      <script src="{{url.highlighters}}/highlight.js/highlight.pack.js"></script> 
      <script>hljs.initHighlightingOnLoad();</script>
      <!-- DONE LOADING HIGHLIGHTER JS FILES -->

prettify:
  theme: sons-of-obsidian
  linenums: true
  js:
    after:
       <!-- Google Prettify --> 
      <script src="http://cdnjs.cloudflare.com/ajax/libs/prettify/188.0.0/prettify.js"></script>
      <script>
       var pres = document.getElementsByTagName("pre");
       for (var i=0; i < pres.length; ++i) {
         pres[i].className = "prettyprint {{# config.linenums }}linenums{{/config.linenums}}";
       }
       prettyPrint();
      </script>
      <!-- End Google Prettify -->

Approach 2

In this approach, each highlighter comes with its own config.yml file which contains configuration details as well as details on assets to include. The config.yml in the root folder only specifies the highlighter to be used.

The advantages of this approach are multifold:

1. Keep things highly modular, permitting a plug and play approach.
2. Does not complicate code to access configuration.

The only flip side is the multitude of config.yml files to deal with.

In both these approaches, HTML and configuration items are mixed up. A third approach that can be followed is along the lines of ruhoh. It uses html files in the layouts directory to specify javascript assets and theme.yml to specify css files to load. I see two problems with this approach:

1. I don't like the idea of splitting specifications across multiple config files. I would rather allow the configuration to be overridden from a global config.yml file rather than allowing themes to control things.
2. There is no way to specify at which point in the file should a javascript asset be included. This becomes important especially for jQuery scripts which require jQuery to be loaded before they can run.

My current approach suffers from two problems.

1. It auto includes all CSS files in the css directory which may not be the use case always.
2. It does not allow user to control placement of javascript assets.