D.8 The default HTML template

A note from the authors: Some of the information and instructions in this book are now out of date because of changes to Hugo and the blogdown package. If you have suggestions for improving this book, please file an issue in our GitHub repository. Thanks for your patience while we work to update the book, and please stay tuned for the revised version!

In the meantime, you can find an introduction to the changes and new features in the v1.0 release blog post and this "Up & running with blogdown in 2021" blog post.

— Yihui, Amber, & Alison

As we mentioned in Section 1.6, the default output format for an Rmd document in blogdown is blogdown::html_page. This format passes a minimal HTML template to Pandoc by default:

$for(header-includes)$
$header-includes$
$endfor$
$if(highlighting-css)$
<style type="text/css">
$highlighting-css$
</style>
$endif$
$for(css)$
  <link rel="stylesheet" href="$css$" type="text/css" />
$endfor$

$for(include-before)$
$include-before$
$endfor$
$if(toc)$
<div id="TOC">
$if(toc-title)$
<h2 id="$toc-title$">$toc-title$</h2>
$endif$
$table-of-contents$
</div>
$endif$

$body$

$for(include-after)$
$include-after$
$endfor$

You can find this template file via blogdown:::pkg_file('resources', 'template-minimal.html') in R, and this file path is the default value of the template argument of html_page(). You may change this default template, but you should understand what this template is supposed to do first.

If you are familiar with Pandoc templates, you should realize that this is not a complete HTML template, e.g., it does not have the tags <html>, <head>, or <body>. That is because we do not need or want Pandoc to return a full HTML document to us. The main thing we want Pandoc to do is to convert our Markdown document to HTML, and give us the body of the HTML document, which is in the template variable $body$ . Once we have the body, we can further pass it to Hugo, and Hugo will use its own template to embed the body and generate the full HTML document. Let’s explain this by a minimal example. Suppose we have an R Markdown document foo.Rmd:

---
title: "Hello World"
author: "Yihui Xie"
---

I found a package named **blogdown**.

It is first converted to an HTML file foo.html through html_page(), and note that YAML metadata are ignored for now:

I found a package named <strong>blogdown</strong>.

Then blogdown will read the YAML metadata of the Rmd source file, and insert the metadata into the HTML file so it becomes:

---
title: "Hello World"
author: "Yihui Xie"
---

I found a package named <strong>blogdown</strong>.

This is the file to be picked up by Hugo and eventually converted to an HTML page of a website. Since the Markdown body has been processed to HTML by Pandoc, Hugo will basically use the HTML. That is how we bypass Hugo’s Markdown engine BlackFriday.

Besides $body$ , you may have noticed other Pandoc template variables like $header-includes$ , $css$ , $include-before$ , $toc$ , and $include-after$ . These variables make it possible to customize the html_page format. For example, if you want to generate a table of contents, and apply an additional CSS stylesheet to a certain page, you may set toc to true and pass the stylesheet path to the css argument of html_page(), e.g.,

---
title: "Hello World"
author: "Yihui Xie"
output:
  blogdown::html_page:
    toc: true
    css: "/css/my-style.css"
---