Alternate R Markdown Templates

The `knitr`/R markdown system is a great way to organize reports and analyses. However, the built-in ones (that come with RStudio/the `rmarkdown` package) rely on Bootstrap and also use jQuery. There’s nothing wrong with that, but the generated standalone HTML documents (which are a great way to distribute reports) don’t really need all that cruft and it’s fun & informative to check out new frameworks from time-to-time. Also, jQuery is a heavy crutch I’m working hard to not need anymore.

To that end, I created a package — [`markdowntemplates`](https://github.com/hrbrmstr/markdowntemplates) — that contains three alternate templates that you can use out of the box or (hopefully) clone, customize and use in your future work. One template is based on the [Bulma CSS framework](http://bulma.io), the other is based on the [Skeleton CSS framework](http://getskeleton.com) and the last one is a super-minimal template with no formatting (i.e. it’s a good one to build on).

The github repo has screenshots of the basic formatting.

I tried to keep with the base formatting of each theme, but I went a bit crazy and showed how to have a fixed banner in the Skeleton version.

### How it works

There are three directories inside `inst/rmarkdown/templates` each has a similar structure:

– a `resources` directory with CSS (and potentially javascript)
– a `skeleton` directory which holds example `Rmd` “skeleton” files
– a `base.html` file which is the parameterized HTML template for the Rmd
– a `template.yaml` file which is how RStudio/`knitr` knows there’s one or more R markdown templates in your package

The `minimal` `base.html` is small enough to include here:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"$if(lang)$ lang="$lang$" xml:lang="$lang$"$endif$>
 
<head>
 
<meta charset="utf-8">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1">
 
<title>$if(title)$$title$$endif$</title>
 
$for(header-includes)$
$header-includes$
$endfor$
 
$if(highlightjs)$
<style type="text/css">code{white-space: pre;}</style>
<link rel="stylesheet"
      href="$highlightjs$/$if(highlightjs-theme)$$highlightjs-theme$$else$default$endif$.css"
      $if(html5)$$else$type="text/css" $endif$/>
<script src="$highlightjs$/highlight.js"></script>
<script type="text/javascript">
if (window.hljs && document.readyState && document.readyState === "complete") {
   window.setTimeout(function() {
      hljs.initHighlighting();
   }, 0);
}
</script>
$endif$
 
$if(highlighting-css)$
<style type="text/css">code{white-space: pre;}</style>
<style type="text/css">
$highlighting-css$
</style>
$endif$
 
$for(css)$
<link rel="stylesheet" href="$css$" $if(html5)$$else$type="text/css" $endif$/>
$endfor$
 
</head>
 
<body>
<div class="container">
 
<h1>$if(title)$$title$$endif$</h1>
 
$for(include-before)$
$include-before$
$endfor$
 
$if(toc)$
<div id="$idprefix$TOC">
$toc$
</div>
$endif$
 
$body$
 
$for(include-after)$
$include-after$
$endfor$
 
</div>
 
$if(mathjax-url)$
<!-- dynamically load mathjax for compatibility with self-contained -->
<script>
  (function () {
    var script = document.createElement("script");
    script.type = "text/javascript";
    script.src  = "$mathjax-url$";
    document.getElementsByTagName("head")[0].appendChild(script);
  })();
</script>
$endif$
 
</body>
</html>

I kept a bit of the RStudio template code for source code formatting, but grokking the actual template language should be pretty straightforward. You should be able to pick out `$title$` in there and you can add as many parameters to the `Rmd` YAML section as you like (with corresponding counterparts in that template). I added a corresponding, exported R function for each supported template to show how easy it is to customize the parameters while also accepting further customizations in the YAML of each `Rmd`.

Imagine building a base template with your personal or organization’s branding *and* having it set apart from the cookie-cutter RStudio `rmarkdown` Bootstrap/jQuery template. Or, create course-specific templates like the [`s20x` package](https://github.com/cran/s20x). Once you peek behind the curtain to see how things are done, it’s not so complex and the sky is the limit.

I’ll try to get these in CRAN as soon as possible. If you have a preference for another CSS framework (I’m thinking of adding a “Metro” CSS kit and a Google web starter CSS kit), shoot me an issue or PR and I’ll incorporate it. The more examples we have the easier it will be for folks to create new templates.

Any & all feedback is most welcome.

10 Comments

- Jemus42
- Posted 2016-02-05 at 11:37
- Permalink
- Reply
Very cool. Please keep adding templates so I don’t have to get my hands dirty with HTML and CSS
(ﾉ◕ヮ◕)ﾉ*:･ﾟ✧

Also, have you considered ioslides templates, if they are even possible? I’m regularly trying to customize my presentations and realize again and again that my lack of comfort with CSS keeps biting me in the butt.
- - hrbrmstr
  - Posted 2016-02-05 at 11:43
  - Permalink
  - Reply
  ioslides is already an option if you choose it from the “Presentation” option in RStudio.
- Jemus42
- Posted 2016-02-05 at 11:49
- Permalink
- Reply
Uh, yeah, sorry that’s not what I meant. I meant customizations/variations of the existing islides template.
- - hrbrmstr
  - Posted 2016-02-05 at 11:56
  - Permalink
  - Reply
  Ah! Yes. I’d have to make a separate ioslides template but that’s doable (I borrow some of the asstes/code from the RStudio rmarkdown::ioslides function/template) (though I think it uses lua so I’ll have to try to work around that). I was also thinking of adding one for “deck.js”.
- Michael Whitaker
- Posted 2016-02-05 at 16:28
- Permalink
- Reply
Fantastic! I would second adding web or polymer starter kit from Google.

The one thing that isn’t clear to me is when I choose

output:
markdowntemplates::skeleton:
self_contained: FALSE

the linked css files are in “/Library/Frameworks/R.framework/Versions/3.2/Resources/library/markdowntemplates/rmarkdown/templates/default/resources/CUSTOMIZE_ME.css”

Could these but put in folder like lib_dir: “lib” in my working directory?
- - hrbrmstr
  - Posted 2016-02-06 at 07:23
  - Permalink
  - Reply
  fixed in the latest release + an extra feature added to the bulma template
- hrbrmstr
- Posted 2016-02-05 at 17:08
- Permalink
- Reply
Hrm. I hadn’t tried the non-self-contained option (thx for testing that :-). I’ll add it as an issue and figure out the incantation to get it to do what the rmarkdown templates do.
- nelson
- Posted 2016-02-05 at 18:22
- Permalink
- Reply
This is fantastic. I’ve been working on sending knitr/rmarkdown report via email, in which case the default jquery/bootstrap stuff does not work well. I think your solution could be used to make an email-friendly styling (all-inline) that approximates the default styling.

(related SO post: http://stackoverflow.com/questions/34230391/how-to-send-r-markdown-report-in-body-of-email)
- Thomas Speidel
- Posted 2016-02-06 at 19:58
- Permalink
- Reply
Fantastic and thank for contributing. Have you tested with html widgets? I’m having some rendering issues with DT table widget (tested with output: markdowntemplates::bulma)
- hrbrmstr
- Posted 2016-02-06 at 20:01
- Permalink
- Reply
Thx. I haven’t tried it yet, but there are more than a few widgets that assume Bootstrap (which is a shame). Can you post an issue with a link to a gist with a sample Rmd?

One Trackback/Pingback

By Alternate R Markdown Templates – Mubashir Qasim on 05 Feb 2016 at 6:18 am

[…] article was first published on R – rud.is, and kindly contributed to […]

rud.is