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]
.
I tweaked the Nature style to be more minimal (only one author, the title, journal + year, and DOI url), see minimal-nature-style.csl
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.For example, for grants with custom templates that include information at the top of the page.
In the yaml header:
geometry:
- margin=2cm
- top=1cm
- includehead
- headheight=1.1cm
In the header.tex
, define a “table” for the header:
%% make header
\usepackage{fancyhdr}
\pagestyle{fancy}
\renewcommand{\headrulewidth}{0pt}
\fancypagestyle{plain}
% clear all headers and footers
\fancyhead{}
\renewcommand{\arraystretch}{1.2}
% set the C(entre) header location but no O or E
\fancyhead[C]{
\begin{tabular}[c]{|l|l|l|r|}
\hline
{\large GRANT23} & \multicolumn{2}{l|}{\bf\large PROJECTNAME} & {\large GRANTNAME} \\
\hline
Coordinated by: & Jean MONLONG \hspace{12em} & X months & Funding requested: \\
\cline{1-3}
\multicolumn{3}{|l|}{COMMITEE} & 3 000 000 000 € \\
\hline
\end{tabular}
}
%% shift title
\usepackage{titling}
\setlength{\droptitle}{-3em}
\posttitle{\par\end{center}\vspace{-5em}}
To better control the table formatting, I write the content of the table in a file (e.g. TSV), then read it in a R code chunk and format it with knitr and kableExtra.
The code chunk, for example with echo=FALSE, message=TRUE, warnings=FALSE
parameters, might look like:
library(knitr)
library(kableExtra)
df = read.table('table1.tsv', as.is=TRUE, header=TRUE, sep='\t',
quote="", comment.char = "", check.names=FALSE)
kable(df, format='latex', booktabs=FALSE) %>%
kable_styling(latex_options="scale_down", position='left') %>%
column_spec(2:3, width = ".7in") %>%
column_spec(4, width = "3in") %>%
column_spec(1, border_left = T) %>%
column_spec(ncol(df), border_right=T, width = "1.5in") %>%
row_spec(0,bold=TRUE)
Note: it’s possible to adapt the table’s format to the output format of the document. For example, to use markdown formatting for Word documents:
if(knitr::opts_knit$get("rmarkdown.pandoc.to") == 'docx'){
kable(df, format='markdown')
} else {
## SEE ABOVE
}
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.
Comments
Define the LaTeX commands in the
header.tex
:Then use in the text as
\note{A note}
and\comment{a comment}
for inline notes and comments in the margin, respectively.