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
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.
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.
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:
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
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.
This tweet from Alison Hill sums up the rules perfectly:
An #rstats #blogdown file hierarchy cheatsheet:— Alison Hill (@apreshill) December 28, 2018
├─ archetypes <- edit me!
├─ config.toml <- edit me!
├─ content <- edit me!
├─ data <- edit me!
├─ layouts <- edit me!
├─ public <- ignore me!
├─ static <- use me! (png/pdf/csv/xls)
├─ themes <- don't touch! pic.twitter.com/gvVA703Lwa
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:
static/post/mypost_filesfolders 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).
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.
Say I have a file
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
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.
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) ```