I compile markdown documents using the RMarkdown R package (which uses Pandoc).
Rscript -e 'rmarkdown::render("document.md")'
The output format is either defined in the YAML header (see below), or can be specified with output_format=
.
Note: In Emacs, I use a custom key binding to run this command on the current buffer.

./
to add some vertical space/break (e.g. in slides).`
and a space to escape `
in inline code. E.g `` `pwd` ``
gives `pwd`
.---
to add horizontal line/separation.[//]: # (This is a comment)
or <!-- This is a comment -->
\newpage
(also works on some non-LaTeX-based outputs).Common info for the YAML header
---
title: My title
subtitle: My subtitle
author: Jean Monlong
date: Oct 23, 2023
---
To use BibTeX references from a library.bib
file, add to the YAML header:
---
bibliography: library.bib
csl: style.csl
link-citations: true
---
A lot of CSL styles can be found at the Zotero Style Repository.
Cite with @bibtexid
or [@bibtexid]
(to add parenthesis).
Multi-citations with [@id1; @id2]
.
Some YAML header options (see documentation for more):
---
output:
pdf_document:
keep_tex: true
toc: true
toc_depth: 2
includes:
in_header: header.tex
linkcolor: NavyBlue
urlcolor: NavyBlue
documentclass: article
papersize: a4
fontsize: 11pt
geometry: margin=2cm
---
header.tex
can be used to define custom LaTeX packages/commands to use.Some YAML header options:
---
output: word_document
---
RMarkdown creates self-contained HTML documents that look good and are easy to share.
Some YAML header options:
---
output:
html_document:
toc: true
toc_depth: 2
toc_float: true
code_folding: hide
---
Using Beamer:
---
output:
beamer_presentation:
slide_level: 2
theme: "default"
colortheme: "dolphin"
fonttheme: "structurebold"
---
Pick a theme from https://hartwork.org/beamer-theme-matrix/ (for example).
Some YAML header options:
---
output:
ioslides_presentation:
widescreen: true
css: style.css
---
I used the style.css
file to make sure the images are sized properly and don’t overflow.
For example, this CSS code seemed to help:
img {
max-width:100%;
max-height:400px;
height: auto;
width:auto;
}
In this mode, the user can use key bindings such as f
(fullscreen), w
(widescreen), o
(overview), p
(presenter notes).
Use the blockquote syntax:
> - First things first
> - But also this
blogdown is a R package extending R Markdown to build Hugo static websites. Hugo is easier to install than Jekyll and apparently faster. Most importantly blogdown makes it easier to write posts with R code like in a RMarkdown document.
I still use GitHub Pages to deploy the website.
GH Pages doesn’t support Hugo, so I build the website in a docs
folder (publishDir = "docs"
in config.toml
) which I set up on the website settings to be the source of the static website.
There are several themes available. I keep using the Poole themes, Hyde and Lanyon, that have been made available for Hugo.
In the YAML header of a page:
output:
blogdown::html_page:
toc: true
Most of the time I would like to build the website with minimal recompilation and I don’t want the draft posts to show (except for previews).
build_site()
builds the site without showing posts with YAML draft: true
.
But it also recompiles everything and that can be a pain.
serve_site()
recompiles only the Rmd documents newer than the corresponding HTML but it builds all posts, even if they have the draft parameter.
For minimal recompilation and hidden draft posts I do hugo_build()
after a serve_site()
.
Using MathJax JavaScript display engine, I followed the instruction in the blogdown documentation and added to the footer partial:
<script src="//yihui.name/js/math-code.js"></script>
<script async src="//cdn.bootcss.com/mathjax/2.7.1/MathJax.js?config=TeX-MML-AM_CHTML">
</script>
Then inline formulas are surronded by $ (for equations use two $), and they follow LaTeX syntax.
In the YAML header:
bibliography: [../../static/library.bib]
link-citations: true
I also use a script to reduce the BibTeX file used (see this post). Otherwise, large BibTeX files or large author lists make the rendering extremely slow.
Note: I now use blogdown for markdown-based websites, see above.
Jekyll websites are simple Markdown documents that can be converted into a website. GitHub uses it to provide a website for a repo.
kramdown
automatically creates TOC if it sees :
* Is replaced by the TOC
{toc}
To make it a bit nicer I created a toc.html
file in the _include
folder with:
<nav>
<h4>Table of Contents</h4>
* TOC
{:toc}
</nav>
Then I call the TOC in each markdown document using (without the \
):
\{\% include toc.html \%\}
I use MathJax JavaScript display engine. I added to the head of the pages:
<script type="text/javascript" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" ></script>
Then inline formulas are defined by \\(...\\)
(for equations, use \\[...\\]
), and they follow LaTeX syntax.
For example, \\(\int_{-\infty}^\infty e^{-x^2}\mathrm{d}x = \sqrt{\pi}\\)
produces \(\int_{-\infty}^\infty e^{-x^2}\mathrm{d}x = \sqrt{\pi}\).
I put information about running R code in a R Markdown document in the R section.