Hippocamplus My Second Memory


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.

Markdown tips

  • Insert images with ![](image.jpg).
  • / to add some vertical space/break (e.g. in slides).
  • Use two ` and a space to escape ` in inline code. E.g `` `pwd` `` gives `pwd`.
  • --- to add horizontal line/separation.
  • Comments using: [//]: # (This is a comment) or <!-- This is a comment -->
  • Insert page breaks with \newpage (also works on some non-LaTeX-based outputs).

YAML header

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

Markdown to PDF report

Some YAML header options (see documentation for more):

    keep_tex: true
    toc: true
    toc_depth: 2
      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.

Custom document header

For example, for grants with custom templates that include information at the top of the page.

In the yaml header:

  - margin=2cm
  - top=1cm
  - includehead
  - headheight=1.1cm

In the header.tex, define a “table” for the header:

%% make header

% clear all headers and footers
% set the C(entre) header location but no O or E
    {\large GRANT23} & \multicolumn{2}{l|}{\bf\large PROJECTNAME} & {\large GRANTNAME} \\
    Coordinated by: & Jean MONLONG \hspace{12em} & X months &   Funding requested: \\
    \multicolumn{3}{|l|}{COMMITEE} &  3 000 000 000 € \\
%% shift title


Define the LaTeX commands in the header.tex:

\setlength{\marginparwidth}{4em} %% avoid the todo notes going out of the margin

Then use in the text as \note{A note} and \comment{a comment} for inline notes and comments in the margin, respectively.

Custom tables

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:

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") %>%

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

Markdown to Word document

Some YAML header options:

output: word_document

Markdown to HTML pages

RMarkdown creates self-contained HTML documents that look good and are easy to share.

Some YAML header options:

    toc: true
    toc_depth: 2
    toc_float: true
    code_folding: hide

Markdown to slides

PDF slides

Using Beamer:

    slide_level: 2
    theme: "default"
    colortheme: "dolphin"
    fonttheme: "structurebold"

Pick a theme from https://hartwork.org/beamer-theme-matrix/ (for example).

HTML slides

Some YAML header options:

    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 {
    height: auto;

In this mode, the user can use key bindings such as f (fullscreen), w (widescreen), o (overview), p (presenter notes).

Incremental bullet points

Use the blockquote syntax:

> - First things first
> - But also this


blogdown websites

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.

Table of Contents

In the YAML header of a page:

    toc: true

Draft posts

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().

Math formulas

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">

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.

Jekyll websites (deprecated)

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.


There are several themes available. My favorites are the two Poole themes, Hyde and Lanyon.

Table of Contents

kramdown automatically creates TOC if it sees :

* Is replaced by the TOC

To make it a bit nicer I created a toc.html file in the _include folder with:

  <h4>Table of Contents</h4>
  * TOC

Then I call the TOC in each markdown document using (without the \):

\{\% include toc.html \%\}

Math formulas

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}\).

R Markdown

I put information about running R code in a R Markdown document in the R section.