Generating HTML from knitr and Pandoc

I like the convenience of generating output from R Markdown by the standard knitr/RStudio method, i.e. knit to markdown, then use markdown::markdown2HTML to generate HTML (this is what knit::knit2html does). However, there are some things - in particular processing citations - that Pandoc does better than the R markdown package (which is based on the Sundown markdown library, which has apparently been deprecated in favour of PageDown)

This gets into a mess of dialect differences.

• Pandoc allows citations (Schmo 1977) and footnotes¹ (It looks like citation tags are case-sensitive, unlike (?) BibTeX?)
  • however, citation tags with special characters (:,+) seem to be problematic: I can't see where this is documented.
  • there might be some problem with long references (Guy 2012a; Guy 2012b), but now I can't reproduce the problem. (Augustin, Sauleau, and Wood 2012) was failing for me, before, but now it seems to work fine. Supposedly we can do just the year reference (1977) or in-text citations such as Schmo (1977).
• Pandoc automatically adds captions to figures based on the alt-text; if you don't like this (it doesn't match the way markdownToHTML works), you can either specify meaningful alt-texts, or use -f "markdown-implicit_figures" -- but this only works with recent versions of Pandoc (>=1.10)
• I like the CSS that markdownToHTML uses, which on my system lives at

system.file("resources", "markdown.css", package = "markdown")

## [1] "/mnt/hgfs/bolker/Documents/LOCAL/lib/R/site-library/markdown/resources/markdown.css"

• by default markdownToHTML embeds the figures as Base64 within an HTML file, so it's self-contained. I like this (don't need to remember to push figures to a web file separately; people can copy the HTML as a single file).
  
• Unfortunately, self-contained and mathjax are incompatible in Pandoc. This is too bad since mathjax is pretty. I've tried out a few other options.
  • I was looking for a self-contained rendering solution (i.e. that would work off-line and without adding a Javascript chunk to the directory), which seems to rule out jsmath
  • latexmathml didn't render all of my output properly (\dots turned into something else)
  • mathml seems OK, although not as pretty as mathjax.

Some math for testing: $$\begin{array}{cc}\hfill sin\left(e^{2\pi i}\right)& =\dots \hfill \\ \hfill v& =\left(\begin{array}{ccc}\hfill 1\hfill & \hfill \varphi \hfill & \dots \\ \hfill \psi \hfill & \hfill 5\hfill & \dots \end{array}\right)\hfill \end{array}$$ (split seems to work, but I had to use $$ rather than \begin{equation} ... \end{equation})

The bottom line is that I am using

fn <- "pandoc_diffs"
css <- system.file("resources", "markdown.css", package = "markdown")
knitr::knit(paste0(fn, ".rmd"))
cmd <- paste0("pandoc -f 'markdown-implicit_figures' -s -o ", fn, ".html -c ", 
    css, " ", fn, ".md --self-contained --bibliography ", fn, ".bib --mathml")
system(cmd)

or in a Makefile

pandoc -f "markdown-implicit_figures" -s -o $*.html -c ${CSS} $*.md --self-contained --bibliography $*.bib --mathml

to process Markdown to HTML via Pandoc. To process it to PDF, I have been translating to LaTeX and using a sed script:

sed -e 's/\\DefineShortVerb/%% DefineShortVerb/' <$1

to hack the output slightly.

Augustin, Nicole H., Erik-André Sauleau, and Simon N. Wood. 2012. “On quantile quantile plots for generalized linear models.” Computational Statistics & Data Analysis 56 (8) (aug): 2404–2409. doi:10.1016/j.csda.2012.01.026. http://linkinghub.elsevier.com/retrieve/pii/S0167947312000692.

Guy, A. 2012a. “A reference.” The Journal of More Stuff.

———. 2012b. “A reference.” The Journal of More Stuff.

Schmo, J. 1977. “A reference.” The Journal of Stuff.