Day 1: Getting started with blogdown
by Danielle Navarro, 27 Apr 2018
On the one hand I feel pretty foolish choosing the blogdown package as the place to start. As awesome as it sounds to have an R package that lets me write blog posts as R Markdown documents and knits everything to a nice neat static website that I can push online, I am a little intimidated by the complexity of the beast. Lurking beneath the pretty exterior is some nightmarish chimera of pandoc, Hugo, CSS/HTML that might not play very well with the server side code that I barely understand. So my feelings going is that I am Messing with Powers Beyond My Comprehension…
On the other hand, I did this once already when setting up the R-Ladies Sydney blog, and as yet I have not brought down the wrath of the gods. Last time around I used the minimalist XMin theme to create the site. This time around I’m going to try using the Academic theme for Hugo. It looks quite elaborate, and I’m worried that it might be a bit much for the site that I want this blog to be…
Okay, so when I did this last time I Googled around a bit, ignored almost all the instructions, made a bunch of silly mistakes, went back to the beginning and read the documentation for blogdown, and eventually got it to work. It was messy but after a while I started to get a feel for it. So, let’s get started:
blogdown::new_site(theme = "gcushen/hugo-academic")
Not surprisingly, this created a bunch of new directories! Somehow, despite the fact that I saw the exact same thing happen last time it’s still a bit overwhelming. Oh well, let’s see what we’ve got. Let’s see… there’s an
index.html file in the
public directory. Wonder what that looks like? Yes, that’s the home page that blogdown generates:
That looks promising, but I think this is going to need a lot of simplifying before I’m going to be comfortable with it.
Taking a look at the files, I see that a bunch of directories have popped up everwhere. First, I guess we have
static directory that will be used to store any files not generated via R Markdown…
content directory that I guess will be used to store all my posts and pages. At a glance though it looks like it’s doing something a bit fancier than what the simpler XMin theme was doing. I’ll have to take a closer look I guess?
Finally there’s a
public directory that will presumably be where the to-be-published site files will appear.
Adding some static files
Okay, so the first thing I do is take some screenshots (so that I can publish them in this post), and place them in the
static/img folder. Easy enough!
1st thought: One thing that is immediately obvious to me – and was really apparent when I did the same thing with the XMin theme – is that I’m going to have to be really careful not to dump my static and content files into the
publicfolder by accident, since so many of the folder names are the same
2nd thought: I’m going to need to be super careful in how I specify my file paths to static files. When writing this post, it’s really tempting to link to
static/img/blogdown-examplesite.png. After all, that’s where I placed the static file, but it’s not where the file is going to end up when the site gets generated. Instead, it turns out that the
publicversion of the file ends up at
img/blogdown-examplesite.pngso if I want my post to link properly that’s how I have to specify it. Still, that’s mostly a matter of being careful. It’s not conceptually difficult, though I’m going to bet that’ll be a recurring problem for me!
Creating a post
Anyway, next step is to create a R Markdown document (this document that I am now writing, in fact), which I’ll call
2018-04-27-starting-blogdown.Rmd, place it in the
content/post folder, and start writing. Of course, I could do this using the
blogdown::new_post() function too, which would have the advantage of giving me the nice GUI, but it’s also nice to to it manually to get a sense of what it does.
- 3rd thought: This is kind of cool. As I do play around with this, blogdown is constantly serving the site, so I can look at how it renders on the fly. For instance, this is what the page looked like at the time I was writing this:
So far, so good?
Playing nicely with Google App Engine?
All my sites are hosted using App Engine. That’s kind of overkill for a static site, since you need to write server side code, but I’ve gotten used to that because I use GAE to run psychology experiments, and hey, maybe some day I’ll make use of it. In the meantime, I’ll just place the
app.yaml file and other GAE bits and pieces in the static directory and let blogdown move them into the right places when I want to deploy the site. I tried that with the R-Ladies Sydney site and that seems to work. Eh. It’ll probably blow up in my face later.
So many bells and whistles!
Next up, there is just waaaay too much going on in this theme for my tastes. I already have an academic website for my lab and I don’t want another. As much as I love the fact that the academic theme has all the bits and pieces you might want to use to set up a full featured academic website, I want something a little more modest. I mostly use this site to write blog posts about stats/science stuff or host a few miscellaneous pages for work that don’t really belong on my lab website or on the R-Ladies Sydney blog, so I’m going to start deleting things :-)
- 4th thought: Actually, hold on. This is a mistake I’ve made before. First I’ll quietly back up a copy because I’m certain to do something stupid like delete the template files. Second I’ll take a quick read over the documentation for the Academic theme and then I’ll start deleting stuff.
…all right, it doesn’t say anything about accidentally summoning the Erinyes…
…so we’re probably okay.
Hm. Apparently the Academic theme has a system for managing publications? Nope don’t want that. I already have a publication list on my webpage, so let’s delete the
content/publication directory…. and… well, that certainly did something, but there are still some empty sections for “selected publications” and “recent publications”.
Well, looking at the
home/ folder, I see that there are lots of different markdown files with names suspiciously similar to the sections listed in the example theme. Let’s take a look at the
publications_selected.md file. Here’s what it says…
+++ # Selected Publications widget. # This widget displays publications from `content/publication/` which have # `selected = true` in their `+++` front matter. widget = "publications_selected" active = true date = 2016-04-20T00:00:00 title = "Selected Publications" subtitle = "" # Order that this section will appear in. weight = 10 BLAH BLAH BLAH +++
Okay, that makes sense. This document defines a widget that displays the selected publications, and it contains information about where it should appear in the list. So I guess each widget defines a “section” within the main page. Fair enough, and I suppose I’d play with this if I cared, but I don’t so into the trash these widgets go!
That was viscerally satisfying!
…but those sections are still there. I suppose if I were a nicer person I would restore those files, but let’s be realistic. I’m never going to use them for this site. No turning back!
So let’s move onto the next hypothesis… maybe the answer is buried in the config file. Let’s open up
- 5th thought: In retrospect, I feel like I should have started by looking at the config file since that’s sort of an obvious place for this kind of thing? But on the other hand, I never really feel like I understand what a config file is doing until I’ve started playing around with things – and usually broken something! – so it probably wouldn’t have done me any good. Still, I feel like it’s a good thing this blog isn’t mission critical software for me, because I’m really not taking this process very seriously :-)
Anyway… Wow, there’s a lot of tweakable parameters. Yep, there’s a bunch associated with publications. Okay, cool. Deleted, and the sections are now gone too.
While we’re at it, let’s get rid of this irrelevant menu item:
[[menu.main]] name = "Publications" url = "#publications_selected" weight = 2
Yep, that works. The menu no longer shows any publications. Now, while I’m here, let’s get rid of the teaching and contact menu items (again, those are alreadty on my lab webpage), as well as the corresponding widgets.
- Parameters specfying the talks from the config file? DELETE
This is starting to look nicer. The site is now stripped down to something closer to what I want. There’s a header, a brief biographical section, a recent posts section, and a projects section. The tags appear at the bottom of the page. The menu only displays those sections, so that’s good.
Okay, if my theory about the site is right, I should be able to close RStudio, delete everything in the
public folder, open it up and serve the site and it will re-generate everything from the beginning. Maybe I’ll just take a backup again :-)
… it works!!!
Well, mostly. I’m mildly annoyed that it’s still generating a directory for “publication_types”. I don’t really want that. Another peruse of
config.toml reveals this section:
# Taxonomies. [taxonomies] tag = "tags" category = "categories" publication_type = "publication_types"
Ah, I bet that’s it. We have three separate classification systems for content, but I only want one. So out go the
All the styling disappears when you get rid of
category, so that’s obviously doing something I don’t understand. Let’s leave it for now and just get rid of publication types.
That’s better. I’m happier with the general structure of the site.
Next on the hit list: the visual styling. The whitespace-to-content rato on this page has too much whitespace for my liking, and there’s so much going on with the images.
config.toml file lets you do quite a lot. Even just changing the colour theme and the font started to make me feel better about the look and feel of the site. I do this …
color_theme = "ocean" font = "playfair"
… and it gives me this …
Definitely an improvement in my opinion. Still not convinced and I’ll probably tweak it eventually, but it’s good enough for now. Let’s come back to this later.
Simplifying the site further
There’s a lot of other minor tweaks I want to make:
- Go to the
about.mdwidget, and delete the sections on interests and education. I already have a CV, and my interests will be revealed by the tags and my description. I’m much happier with the minimal profile that this leaves
- Go to the
hero.mdwidget: get rid of the “call to action” button because I don’t want anyone to take action when they arrive on the sit. This is just a side blog, I don’t have a product to sell :-)
- Add a new profile pic and change the link to it in
sharing = falsein
config.tomlto get rid of annoying social media buttons :-)
The site is starting to look nicer…
The projects widget
At the bottom of the page we have a collection of “cards” or something? Each one shows a project. So let’s open up the files associated with each of the projects…
So… it looks like the Academic theme allows you to have projects that are just an external link
(and don’t generate a new page) as well as projects that have their own page. A quick peek at the format of a project page in the example
content/project/deep-learning.md suggests this is pretty easy to tweak. One thing that would be nice is to have a “project” that displays the talk schedule for the UNSW School of Psychology colloquium series (since I currently organise that!) in a nice, somewhat professional way. Here goes…
+++ # Date this page was created. date = 2018-04-27 # Project title. title = "Psychology Colloquium Series 2018" # Project summary to display on homepage. summary = "Schedule of speakers for the 2018 colloquium series at UNSW psychology" # Optional image to display on homepage (relative to `static/img/` folder). image_preview = "thumbnail-unsw.jpg" # Tags: can be used for filtering projects. tags = ["colloquia","2018","unsw"] # Optional external URL for project (replaces project detail page). external_link = "" # Does the project detail page use math formatting? math = false # Optional featured image (relative to `static/img/` folder). [header] image = "headers/unsw-wide.png" +++
That’s the complete header information. So now my jobs are pretty simnple…
- Cut and paste the actual content from the existing markdown document that I’ve been using to track the colloquium schedule. Done. That took 2 seconds :-)
- Quickly put together a UNSW brand-standard compliant banner (
unsw-wide.png), and smaller one to go on the home page (
thumbnail-unsw.jpg). That took a few minutes.
- Place the files in the appropriate static directories: dropped in to the static folders at
static/img/thumbnail-unsw.jpg. A few more seconds!
[EDIT: So, some questions for “yesterday Dani”… why the heck did you make one of these a PNG and the other a JPG?? And why are these file names inconsistent with each other? Were you feeling okay? ¯\_(ツ)_/¯ ]
Done! Here’s what the card looks like on the home page:
And here’s a screenshot of the page itself:
It’s not quite ready for prime time yet. The blue and yellow clash horribly (I’m so sorry University of Michigan, but it’s true – I still love you though!) Plus I suspect that placing the UNSW logo below the site title is probably a violation of brand standards. I’ll have to fix that later, but it might require some thought so let’s keep moving.
Now that I’ve worked that out, it’s easy to work out how to add a project that links to the R-Ladies Sydney blog without generating a page. Repeat for a few more examples, and the projects widget looks like this:
Back to the blogging…
So now I go back to my new blog post, and edit the headers:
--- title: "Day 1: Getting Started with Blogdown" author: "Danielle Navarro" date: 2018-04-27T22:00:00-00:00 tags: ["R Markdown", "blogdown"] header: image: "headers/blogdown-hex-wide.png" caption: "Yay! It works! :heart:" ---
I quickly create a new header image and place it in the
static/img/headers folder, and all of a sudden the “posts” widget looks like this:
There’s still a lot of things that bother me about the visual style, but honestly it’s pretty good. I’ve deleted almost everything I didn’t want, modified the bits I do want, and I’ve got a system that I can use to write posts easily!
Let’s push it to App Engine and…
… oh, right, Google App Engine isn’t merely intended to serve static sites. If I were smart I’d have used github pages or netlify, but okay, it’s not so bad. All I need to do is add some lines to my
app.yaml file corresponding to the static directories, like this
- url: /post static_dir: /post
and a couple more for the few static files that sit in the root directory
- url: /404\.html static_files: 404.html upload: 404\.html
and it’s all good. Everything associated with the blog is now being served as a static website, but the back end is still there doing all this extra super cool stuff (i.e., absolutely nothing at all for this website…)
YES WE ARE DONE
I’m going to call that a win. I’m a little scared of what I have unleashed but oh well. It works. I am exhausted. I’m pleased with how it worked out. I think I have earned a drink :-)
Tomorrow, I’m going to pick something with emojis or kittens or something.