R Markdown and Pandoc Template: releasing your super powers

They also discovered that Pandoc allow users to provide custom templates. Now, Alice and Bob have a hypothesis: can they use Pandoc’s custom template to save time?

Hypothesis Investigation

Pandoc’s documentation says

A custom template can be specified using the --template option. You can also override the system default templates for a given output format FORMAT by putting a file templates/default.FORMAT in the user data directory.

It also says

--data-dir=DIRECTORY Specify the user data directory to search for pandoc data files. If this option is not specified, the default user data directory will be used. This is, in Unix:

$HOME/.pandoc

(…)

and in Windows Vista or later:

C:\Users\USERNAME\AppData\Roaming\pandoc

Pandoc sets some variables by default when it reads the input document and those variables can be used in the template by surrounding the variable name with the dollar sign, $.

With that information and all their R knowledge, Alice and Bob wrote on their lab notebook

1. Clone the Git repository with the last paper.

   Run git clone git@gitlab.com:rgaiacs/rmd-and-pandoc-template.git at the command line.

2. Create the directory _pandoc/templates inside the directory rmd-and-pandoc-template.

   Run cd rmd-and-pandoc-template, mkdir _pandoc and mkdir _pandoc/templates at the command line.

3. Get one LaTeX templates from Overleaf and store it inside _pandoc/templates.

   Visit Overleaf’s APA6 template, copy it and save as _pandoc/templates/apa6.tex.

4. Change _pandoc/templates/apa6.tex to make use of Pandoc’s variables title, author and body. Also include some necessary LaTeX packages.

   The necessary LaTeX packages are

   % Common used
   \usepackage[english]{babel}
   \usepackage[utf8x]{inputenc}
   \usepackage{amsmath}
   
   % Required by knitr
   \usepackage{framed}
   \usepackage{graphicx}
   \usepackage{listings}
   \usepackage{longtable,booktabs}
   \usepackage{textcomp}
   \usepackage{xcolor}
   

5. Add Pandoc arguments into paper.Rmd.

   output:
    pdf_document:
      pandoc_args: [
        "--data-dir", "_pandoc",
        "--template", "apa6.tex",
        "--output", "apa6.pdf"
      ]
   

6. Run Knit from the RStudio interface.

   RStudio log will show

   /usr/lib/rstudio/bin/pandoc/pandoc +RTS -K512m -RTS paper.utf8.md --to latex --from markdown+autolink_bare_uris+ascii_identifiers+tex_math_single_backslash --output paper.pdf --template /home/raniere/R/x86_64-pc-linux-gnu-library/3.4/rmarkdown/rmd/latex/default-1.17.0.2.tex --highlight-style tango --latex-engine pdflatex --variable graphics=yes --data-dir _pandoc --template apa6.tex --output apa6.pdf --variable 'geometry:margin=1in' 
   output file: paper.knit.md
   
   
   Output created: paper.pdf
   Error in tools::file_path_as_absolute(output_file) : 
     file 'paper.pdf' does not exist
   Calls: <Anonymous> -> <Anonymous>
   Execution halted
   

   Looks like that something went wrong but this is only because we change the output expected by RStudio with --output apa6.pdf.

7. Open apa6.pdf with your favourite PDF reader.

8. Repeat steps 3-7 with a different LaTeX templates.

   You can use Overleaf’s IEEE Photonics Journal Paper template. You will need to download the IEEEphot.cls.

Looks like that Alice and Bob can use Pandoc’s custom template to save time!

--data-dir versus $HOME/.pandoc

Alice and Bob successfully verified that they could use $HOME/.pandoc instead of --data-dir but they agreed that using --data-dir would make easy for reproduce their work at the cost of duplicated files.

HTML

Alice and Bob also tested Pandoc templates for HTML documents. They wrote _pandoc/templates/university-of-manchester.html and added

html_document:
  template: "university-of-manchester.html"
  pandoc_args: [
    "--data-dir", "_pandoc",
  ]

into paper.Rmd.

Note: As explained in rmarkdown issue #1142, use --template inside pandoc_args will not work.

PDF from HTML

Chrome 59 or later has headless support which allows users, among other things, to create PDF by running chrome --headless --disable-gpu --print-to-pdf https://website.to.print/.

Microsoft Word and LibreOffice Writer

Pandoc supports custom template for Microsoft Word and LibreOffice Writer documents. Unfortunately, write a custom template for this formats can be a little more challenge.

Conclusion

Now is time for Alice and Bob wear they red cape and go share their new super power.

Appendix

File does not exist

R Markdown/RStudio doesn’t offer a great support to output_file argument, --output as Pandoc argument, as explained by Yihui Xie in Stack Overflow. You can follow his suggestion and use “the undocumented knit hook”.

Mathematical expressions

As mentioned on Pandoc’s documentation,

To write a literal $ in a template, use $$.

GitLab, GitLab CI and GitLab Pages

If you host your R Markdown file in GitLab, you can use GitLab CI to convert it to HTML, or any other format, and publish it on GitLab Pages. You can do it for a single document or for more, maybe organised as a blog.

Tags:

• Jekyll