June 2, 2015
It might help to have an up-to-date pandoc. You can probably get an installer for the most recent version here.
-o (output file name)
: where to put output--standalone
: produces a standalone document, not a code fragment (using one of these templates)--from=(format name)[+/-(extension name)]
: what to write out to (defaults to html) and optional turning on/off of various behavior, listed here--include-in-header=(file name)
: at the end of the header, e.g. css, javascript, \newcommand
, etc. (but see --css
, and gotachas for latex macros)--include-before-body=(file name)
: at the beginning of the body, e.g. navigation bars, \maketitle
, etc.--self-contained
: everything in one file (but see --mathjax
)--mathjax[=URL]
: points to the MathJax.js
script, incompatible with --selfcontained
--variable=KEY[:VAL]
: assign template variable KEY to VAL, for instance:
theme
: for beamer or reveal.js presentations--incremental
: step through lists--slide-level
: headers above this level create sections; below this create slides.--css=(URL)
: include the css linked to
A paragraph with three dots:
. . .
makes a pause.
There are various styles of presentation available.
I ended up using reveal.js
, so it’s included as a submodule, but slidy
looked pretty good, too. Here’s notes on getting the prerequisites. There are rules in the Makefile to build the rest of these.
reveal.js : pandoc 1.12 works only with reveal.js <= 2.6.2.
So, if your pandoc is old, do this:
S5 :
dzslides : No setup, but seems to be broken.
slidy : No setup, downloads from [w3c.org]
slideous : Doesn’t seem to produce a slideshow?
There are methods in the Makefile for rendering with each of these methods.
markdown::markdownToHTML( )
: lightweight but does some styling
knitr::knit2html()
knitr::knit2html( )
: calls markdown::markdownToHTML( )
, almost identical
pander::Pandoc.convert( )
: looks quite nice, brings in jquery and others
pander
is an entire schema to translate R
objects to markdownrmarkdown::render( )
: high-level, does everything, has a nice template.
Rstudio
relies on, which comes bundled with a binary for pandoc.knitr
knitr
just uses a regular expression to identify chunks of code to parse:
knitr::all_patterns$md$chunk.begin
## "^[\t >]*```+\\s*\\{[.]?([a-zA-Z]+.*)\\}\\s*$"
knitr::all_patterns$md$chunk.end
## [1] "^[\t >]*```+\\s*$"
Yihui’s trick for getting around this is to use R to insert an "" into the preamble, like so:
Parsed that?
Here’s an inline example:
inline `R` code (`` ``r "r nrow(data)"`` ``)
Alternatively, you can make the patterns knitr uses to catch code blocks more strict. Here’s from the Makefile for this presentation:
KNITR_PATTERNS = list( chunk.begin="^```+\\s*\\{[.]?(r[a-zA-Z]*.*)\\}\\s*$$", chunk.end="^```+\\s*$$", inline.code="`r +([^`]+)\\s*`")
%.md : %.Rmd
cd $$(dirname $<); Rscript -e 'knitr::knit_patterns[["set"]]($(KNITR_PATTERNS)); knitr::knit(basename("$<"),output=basename("$@"))'
Yihui says that setwd()
is evil, because it is not reproducible. knit()
works from the directory the .Rmd
file is in. You can change the directory knitr
works in using
Since this is interpreted relative to the working directory of the R session that calls knitr, it may be best to always set
in templates. (But, beware of any dependencies!)
Note: some people try to call setwd()
within their .Rmd
file. But, knitr
resets this for each chunk (and, chastises you!).
If knitr
doesn’t always make plots/output every time around the for loop, the problem might be there’s an error or something early on?
One option: use xtable
+ results="asis"
.
```{r results="asis"}
library(xtable)
dtab <- xtable( table( sample( letters, 300, replace=TRUE ) ) )
print(dtab,type='html')
```
Currently (8/17/2015), rmarkdown’s render
function cannot be used for templates that might be compiled at the same time with different data. There is no workaround. This is too bad, because render parses the YAML header, and makes the resulting html look nice. Let’s look under the hood to see how to replicate it. Here’s the call to pandoc
:
pandoc
:
+RTS -K512m -RTS
: this increases pandoc’s stack spacetest2.utf8.md
: the input file--to html
: the output format--from markdown+autolink_bare_uris+ascii_identifiers+tex_math_single_backslash-implicit_figures
: the input format
+autolink_bare_uris
: Makes all absolute URIs into links.+ascii_identifiers
: Causes the identifiers produced by auto_identifiers to be pure ASCII.+tex_math_single_backslash
: Causes \(\)
and \[\]
to be displayed as math.-implicit_figures
: An image occurring by itself in a paragraph will be rendered as a figure with a caption.--output one/one.html
: output file--smart
: curly quotes, em and en dashes, and ellipses.--email-obfuscation none
--self-contained --standalone
--section-divs
: Wrap sections in <div>
tags.--template /usr/local/lib/R/site-library/rmarkdown/rmd/h/default.html
: rmarkdown’s template--variable 'theme:bootstrap'
: variable to the template--include-in-header /tmp/RtmpLnM0EY/rmarkdown-str65b85d06d7aa.html
: this does various things:
<script src="/usr/local/lib/R/site-library/rmarkdown/rmd/h/jquery-1.11.0/jquery.min.js"></script>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<script src="/usr/local/lib/R/site-library/rmarkdown/rmd/h/bootstrap-3.3.1/js/bootstrap.min.js"></script>
<script src="/usr/local/lib/R/site-library/rmarkdown/rmd/h/bootstrap-3.3.1/shim/html5shiv.min.js"></script>
<script src="/usr/local/lib/R/site-library/rmarkdown/rmd/h/bootstrap-3.3.1/shim/respond.min.js"></script>
--mathjax --variable 'mathjax-url:https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'
: The template inserts mathjax itself.--no-highlight --variable highlightjs=/usr/local/lib/R/site-library/rmarkdown/rmd/h/highlight
: Turn off pandoc highlighting and tell the template to do the highlighting.We can trim this down to
MATHJAX=/usr/share/javascript/mathjax/MathJax.js # for local mathjax
PANDOC_OPTS="--to html --from markdown-implicit_figures \\
--standalone --self-contained --section-divs --template template.html \\
--variable 'theme:bootstrap' --include-in-header resources/header-scripts.html \\
--mathjax --variable mathjax-url:$MATHJAX?config=TeX-AMS-MML_HTMLorMML'"
So, now to turn input.Rmd
into output.html
, in a safe way, we need to get the header-scripts file and then run
R --vanilla -e 'knitr::knit("input.Rmd",output="output.md")'
pandoc output.md ${PANDOC_OPTS} --output output.html
Options:
modify a rmarkdown format
or a pandoc template
There are many options, but probably --mathjax
is the best?
Note that it is supposed to render as far as possible with unicode, but this m\(a\)y depend on the proper fonts being installed?
These are just markdown except it pays attention to linebreaks.
| Molecular & Computational Biology
| University of Southern California
| 1050 Child Way, RRI 201 (MCB)
| Los Angeles, CA 90089-2910
produces
Each term must fit on one line, which may optionally be followed by a blank line, and must be followed by one or more definitions. A definition begins with a colon or tilde, which may be indented one or two spaces.
A term may have multiple definitions, and each definition may consist of one or more block elements (paragraph, code block, list, etc.), each indented four spaces or one tab stop. The body of the definition (including the first line, aside from the colon or tilde) should be indented four spaces.
HTML documents can stitch together lots of different pieces: images, css, javascript, etcetera. These are not nice to email.
But: pandoc
can produce self-contained documents, that are email-ready. rmarkdown
does this by default.
Warning: the best way of displaying math relies on mathjax, which is a “large” javascript library, and is not included. If you use LaTeX math, you need to host a local copy of mathjax.
indentation : one tab (four spaces) indicates a code block except within lists
header attributes can be specified by appending {#identifier .class .class key=value key=value}
afterwards
{# foo .unnumbered}
makes a section that can be linked to with [link to foo](#foo)
and is unnumbered