Hippocamplus My Second Memory

Markdown

Tips

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

Converting Markdown into nice HTML pages

I use RMarkdown. It creates a self-contained HTML document that looks nice enough and is easy to share.

Rscript -e 'rmarkdown::render("document.md")'

Converting Markdown into slides

I use RMarkdown or MarkdownSlides.

Jekyll websites

Jekyll websites are simple Markdown documents that can be converted into a website. GitHub uses it to provide a website for a repo.

Note: I now use blogdown for markdown-based websites, see below.

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

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.

R Markdown

I put R Markdown content in the R section.