Hippocamplus My Second Memory

Markdown

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

Bibliography

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].

Markdown to PDF report

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.

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:

---
output: 
  html_document:
    toc: true
    toc_depth: 2
    toc_float: true
    code_folding: hide
---

Markdown to slides

PDF slides

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

HTML slides

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

Incremental bullet points

Use the blockquote syntax:

> - First things first
> - But also this

Websites

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.

Themes

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:

output:
  blogdown::html_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">
</script>

Then inline formulas are surronded by $ (for equations use two $), and they follow LaTeX syntax.

Bibliography

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.

Themes

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
{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 \%\}

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.