Data Science Resources

2020-01-26 · Elizabeth

How to set up a blogdown project

Photo by Element5 Digital on Unsplash

First things first

Are you writing this so you have a blog post set up on your new site?

Yes - I admit. The new site is looking a little bare and, like most data scientists, I’d prefer to produce something new than to laboriously convert all our old content

But also, as I’ve transitioned our blog to the blogdown, hugo, github and netlify stack I’ve found some great resources and spent too long figuring out where to put stuff so it all hangs together. Hopefully these notes will assist someone else out there to get started.

Why blogdown?

I’ve hosted our website on Squarespace for about a decade and they are one of my favourite providers - simple and very pretty websites. However, using a hosted content management system meant we had to jump too many hoops every time we wanted to include a html-widget or embed shiny code, etc.

So we’ve split out all our techical resources and writings into a blogdown site, hosted on netlify. Now any of our data scientists can use the same branch-write-pull request-review process we use for our code to publish to the blog also.

Some resources to start with

I’m not going to go through all the basics of blogdown and Hugo in this post. If you are just starting out I highly recommend:

  1. The blogdown book: Your go-to reference guide
  2. Up and running with blogdown: A great beginners tutorial
  3. Awsome blogdown: Get inspired by other sites
  4. Mike Dane's Hugo playlist: Highly recommend this if you want to dig a little deeper into Hugo itself.

Blogdown Q&A

1. Where’s my site??

So, you’ve started a blogdown project, selected a theme, set up some posts, and connected your github and netlify accounts so your site renders when you push your code to the master branch.

You git push and wait…

…everything seems ok on netlify….but no posts are visible.

Before you go off rebuilding or reconfiguring API keys or any number of other sophisticated debugging steps, check that you haven’t got draft: true set in your post YAML header. blogdown::serve_site will show you draft and published posts by default, but drafts won’t show up online…because they are drafts…..

Who would make this kind of mistake, you ask?

……(hangs head)…let’s move on.

2. There seem to be duplicate files everywhere - where do I start??

This tweet from Alison Hill sums up the rules perfectly:


Here’s a cut down version of what our folders look like

|-- content/ 
    |-- post/
         |-- blog posts e.g. `2020-01-26-set-up-a-blogdown-project.Rmd`
|-- layouts/
    |-- partials/  (html files that I have copied and modified from the theme folder)
    |-- shortcode/ (html snippets for shortcodes)
|-- static
    |-- css/   (custom css)
    |-- env/   (.gitignored folder containing tokens and api keys etc.)
    |-- img/ 
        |-- cover/ (cover images for posts, named the same as the blogpost for reference)
        |-- post/  (other static images for posts)
    |-- post
        |-- `2020-01-26-set-up-a-blogdown-project_files` 
               |- chunk outputs, image files, widgets and other static content associated with the blogpost
    |-- rmarkdown-libs
        |- widget requirements, generated by rendering the posts

A few guidelines to get started:

  • Edit config.toml to set things like the site name, menu options, social media. What you can do varies a lot between themes, which is why starting with the example site is helpful and switching themes usually doesn’t work.
  • Make new posts using the RStudio add-in. If you’re copying posts, put them in content/post. Other pages (like about) can be added to content.
  • Don’t edit the theme files in the themes directory. Copy files you want to edit to the layouts folder in the main directory and edit files there. This will override whatever is in the themes.
  • Images and other files served statically go in the static directory.
  • Don’t add anything to public.
  • The static/post/mypost_files folders are generated by rendering your posts. They can be deleted (e.g. if you run blogdown::clean_site() so don’t store images and other content in there).

How do I reference things in the static folder?

I went around in circles a bit trying to find the right way to reference different types of information from within my posts. This is how I now understand it, but please let me know if there’s a different or better way to do things.

How do I include a picture file?

Say I have a file prettypicture.png in static/img/post/2020-01-01-mypost-prettypicture.png. I want to include it in my post as a full width image with a caption underneath. I simply insert

![caption text](/post/2020-01-01-mypost-prettypicture.png){width=100%}

Blogdown/Hugo assumes the links are relative to the root directory of the public folder. When the site is served / built all the folders under static are copied to the public folder. Have a poke around in your public folder once you’ve built a site and you’ll see what I mean.

How do I read in data (including API tokens etc)?

If your data is stored locally under static/data/mypost/data.rds you need to reference it from R using the relative path.

If your blog is set up as an RStudio project, I recommend the here package to construct the links for you. They will be relative to the base folder of the project. In this example, you would run:

  ```r
  library(here)
  dat <- readRDS( here::here("static", "data", "mypost", "mydata.rds"))
  print(dat)
  ```