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.

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

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

bibliography: [../../static/library.bib]
link-citations: true