Alternate R Markdown Templates
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.
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
— 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, the other is based on the Skeleton CSS framework 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 exampleRmd
“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. 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.
R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.