custom pandoc templates (learning resources)

[zac-garland]

I'd like to create a few custom pandoc templates (all html output) and was curious where I could find additional information on the default template.

I'm familiar with the custom pandoc section in the bookdown site and have familiarized myself with this folder rstudio/rmarkdown/inst/rmd/h in the rmarkdown package, but could use some additional clarification.

I thought if I used the rmd/h/default.html as the yaml template: I'd get the same result as the default render, but as per below, the results were slightly different.

Granted, the differences are minor, but it made me curious to learn more about the general structure, code, and thought process that goes into building a template.

Questions:

• What code chunks are necessary to render R code (e.g. plots, tables, htmlwidgets)?
• What style rules does rmarkdown apply by default, and why?
• What software dependencies does it currently rely on? Could any be removed without impacting other processes?
• Would it be possible to use the R engine for anything that you can do in html/js/css? Are there any limitations?
• How could you approach creating a template based on a JS package (for example, fullPage.js or an html template (e.g. bootstrap example template)
• How does runtime: shiny work and how could it be integrated into a new template?

I realize there are a lot of questions there, so I thought I'd try to approach it as more of a discussion board. I'd love to see any additional examples, attempts, or in dev thoughts around this topic.

[cderv]

About pandoc template, you can find some more informations in the new book

R Markdown Cookbook

There is a chapter on HTML template and Latex template.

Best documentation remains the one from the PANDOC manual, https://pandoc.org/MANUAL.html#templates

Regarding the how it works, and the difference you observed, rmarkdown is done to work well with the default template that includes some specific component. That means if another template than the default (so something different that template = "default" )` is provided, some pieces of code won't activate. There is also the highlighting that could come into play. I think that explains the small difference I think. (seems to be something with the font and the highligting in your case)

So custom pandoc template are just html files that contains the syntax describe by pandoc and for which you can pass variable though the yaml header (or pandoc command line also).

Regarding your questions, some part of answers

• You can do anything that you can with R in R code chunks
• Rmarkdown integrates bootstrap in its template for the styling
• I think you can build any template to change the look and feel. See other examples like https://github.com/juba/rmdformats where rendered html are completly different than the default.
• You can do pretty much with R, but you can also include CSS, JS and HTML directly or though CSS or JS chunk in the Rmd document.
• For including JS libraries, you can look at how rmarkdown does it with its default template.
• I think runtime shiny will just render the html UI based on the Rmarkdown and the rest is just shiny, so I think it would work with a new template too.

As examples, you can look at all the different format implementation that are describe in the book

R Markdown: The Definitive Guide

among them the community formats https://bookdown.org/yihui/rmarkdown/community.html or custom formats like presentations or flexdashboard

Hope it helps

[zac-garland]

That is an awesome response @cderv ! It seems like I need to take a dive deep into pandoc and you've provided great resources. I will mark that as a solution, but have a question prior to closing.

My last follow up question - if we take the simple pandoc html template below, and render the default content from the rmarkdown skeleton.Rmd, you'll see that it doesn't render the R content (e.g. plots, code chunks, htmlwidgets, etc.)

What code chunks are missing that make the "magic" happen? In other words, I'm looking to start nearly from scratch (outside of rendering R content). Have you seen any bare bones base templates like this anywhere?

Thanks again!

<html>
  <head>
    <title>$title$</title>
  </head>

  <body>
  $body$
  </body>
</html>

[cderv]

What code are you running to do the conversion ?

Are you using rmarkdown::render on a Rmd file with R code chunk inside and providing specific template in YAML header of the Rmarkdown ?

R code is evaluated and transformed to markdown content by knitr in the process of markdown rendering. This is explained in chapter 2 https://bookdown.org/yihui/rmarkdown-cookbook/conceptual-overview.html

[zac-garland]

Apologies, I should have been more specific. And my question should be modified, what portions are missing to properly render htmlwidgets

This is the Yaml:

---
title: "Bare Bones"
author: "Zac Garland"
date: "8/14/2020"
output:
  html_document:
    template: bare-bones.html
---

bare-bones.html

<html>
  <head>
    <title>$title$</title>
  </head>

  <body>
  $body$
  </body>
</html>

Rmd Content

library(tidyverse)
library(plotly)
library(leaflet)

plotly::plot_ly(mtcars,x = ~cyl,y = ~mpg)

leaflet::leaflet() %>% 
  leaflet::addTiles()

Output