Create a blog with Distill

Tutorial to build a blog with Distill. A RStudio package which allows to write scientific and technical articles in a suitable format for the web. ‘Distill’ articles feature attractive, reader-friendly typography, flexible layout options for visualizations, and full support for footnotes and citations.

Uwe Sterr http://uwesterr.de
01-16-2020

Table of Contents

How to set the blog up

For me as a go between R and Python it is still a big argument for R that it is so easy to create html reports which can be distributed without the need of any software installation on the receiving side. That is why I used R to create my blog, however, it might very well that I am just unaware of an equally good or better option with Python.

Following the instructions on https://rstudio.github.io/distill/blog.html using RStudio and the programming language R it took about 2h to get the blog up and running on gitHubPages. The integration of distill in RStudio makes it even easier to start a blog. Creating a blog from within RStudio is done in the “new project” dialog.

Example blog TensorFlow for R Blog

A impressive example of a distill based blog isTensorFlow for R Blog https://blogs.rstudio.com/tensorflow/

The code of the blog can be found at https://github.com/rstudio/tensorflow-blog

Create new posts

To create a new blog the command in RStudio is


library(distill)
create_post("The Sharpe Ratio")

This will create a sub-directory for your post within the _posts directory, add a stub Distill article, and open the article for editing.

If you want to write a draft first add the option


create_post("The Sharpe Ratio", draft = TRUE)

Add preview image

How to define the image in the preview of the blog check the “Preview images” section at https://rstudio.github.io/distill/blog.html

html widgets

Including htmlwidgets within a Distill article is as easy as including an R plot. For example, the following code embeds a Leaflet map:

You can also use figure layout options with htmlwidgets. For example, here we set layout=“l-page” to specify that we want the widget to span the width of the page:

more info on how to add html widgets can be found at https://rstudio.github.io/distill/interactivity.html

Add citations

BibTeX is the supported way of making academic citations. To include citations, first create a BibTeX file and refer to it from the bibliography field of the YAML front-matter. For example:

title: “Create a blog with Distill”
description: |
Tutorial to build a blog with Distill.
preview: images/CreateDistillBlog.png
bibliography: bib/bibliographyGeneral.bib

References can be included by [@wei2019benchmarking] which is displayed in the webpage as: (Wei, Brooks, and others 2019)
A reference is added at the end of the page. The text of the reference is shown while hoovering over the number.

Add footnote

A foodnote can be added with

^[This is a footnote added to a distill blog post] which is displayed in the webpages as:1
A footnote is added at the end of the page. The text of the footnote is shown while hoovering over the number.

Two columns layout

If you want to have two columns you can follow the instructions given in https://stackoverflow.com/questions/31753897/2-column-section-in-r-markdown

Alternative Python static web page generator Nikola

An alternative to distill would be Nikola https://getnikola.com

Theme blog with css

To theme a blog using css add to _site.yml


  distill::distill_article:
     self_contained: false
     css: styles.css

add the file style.css in the same folder as the .Rmd file


p.hometown { 
  background: yellow;
}

and in the .Rmd file


<p>My name is Donald.</p>
<p class="hometown">I live in Ducksburg.</p>

<p>My name is Dolly.</p>
<p class="hometown">I also live in Ducksburg.</p>

to get:

Further information on distill and blogging

Learn more about using Distill at https://rstudio.github.io/distill
Creating a Blog is described in https://rstudio.github.io/distill/blog.html

Acknowledgments

Thanks RStudio for developing this oppertunity to write blogs easily.

Wei, Gu-Yeon, David Brooks, and others. 2019. “Benchmarking Tpu, Gpu, and Cpu Platforms for Deep Learning.” arXiv Preprint arXiv:1907.10701.

  1. We’ll be using DP as an acronym for both the noun phrase “differential privacy” and the adjective phrase “differentially private”.↩

References

Citation

For attribution, please cite this work as

Sterr (2020, Jan. 16). Uwe's Blog: Create a blog with Distill. Retrieved from http://uwesterr.de/posts/2020-01-17-create-a-blog-with-distill/

BibTeX citation

@misc{sterr2020create,
  author = {Sterr, Uwe},
  title = {Uwe's Blog: Create a blog with Distill},
  url = {http://uwesterr.de/posts/2020-01-17-create-a-blog-with-distill/},
  year = {2020}
}