7.9 Use a custom HTML template (*)

We mentioned LaTeX templates in Section 6.10. You can also specify a custom HTML template for Pandoc to convert Markdown to HTML. Below is a brief example template:

  1. <html>
  2.   <head>
  3.     <title>$title$</title>
  4.     $for(css)$
  5.     <link rel="stylesheet" href="$css$" type="text/css" />
  6.     $endfor$
  7.   </head>
  8.   <body>
  9.   $body$
  10.   </body>
  11. </html>

You can see that the template contains a few variables such as $title$ and $body$. You can find the full list of Pandoc variables and their meanings at https://pandoc.org/MANUAL.html#templates.

The template gives you the ultimate power to customize the HTML output. For example, you can include arbitrary CSS stylesheets or JavaScript code or libraries in the <head> area. For example, we could use a Boolean variable draft to indicate whether the document is a draft or a final version:

  1. <head>
  2. <style type="text/css">
  3. .logo {
  4.   float: right;
  5. }
  6. </style>
  7. </head>
  9. <body>
  10. <div class="logo">
  11. $if(draft)$
  12. <!-- use draft.png to show that this is a draft -->
  13. <img src="images/draft.png" alt="Draft mode" />
  14. $else$
  15. <!-- insert the formal logo if this is final -->
  16. <img src="images/logo.png" alt="Final version" />
  17. $endif$
  18. </div>
  20. $body$
  21. </body>

Then we can set the variable draft to true or false in the YAML metadata of the Rmd document, e.g.,

  1. ---
  2. title: "An Important Report"
  3. draft: true
  4. ---

To apply a template to an Rmd document, you can save the template to a file, and pass the file path to the template option of html_document, e.g.,

  1. output:
  2.   html_document:
  3.     template: my-template.html

The rmarkdown package uses a custom HTML template shipped with the package, which is different from Pandoc’s default template. To use the latter, you can specify template: null.