Getting Started With Blogdown

It took me a couple of days to get going with Blogdown, but now that I’ve got not one, but two Blogdown blogs set up - https://www.znmeb.mobi/ and https://www.algocompsynth.com - here’s my process.

In what follows, I’m assuming you have RStudio, you’ve installed Blogdown, and you’ve read the Blogdown eBook.

Set up your Git repository

If the blog is a public project, you’ll probably want to host it on GitHub for discoverability. For a private one, you might well choose GitLab or Bitbucket, where private repositories are free.

If it’s a public project, I strongly recommend adding a README.md, a LICENSE, a code of conduct and a contributor’s guide. You can see those for algocompsynth.com at README.md, LICENSE, CONDUCT.md, and CONTRIBUTING.md. IMHO it’s vital to set those expectations up front.

Choose your Hugo theme

Be prepared to spend a few days on this, including reading some Hugo documentation. Blogdown uses Hugo under the hood, and if you’ve never used a static site generator before, some things won’t make sense until you know how Hugo works.

At the time of this writing, there are 89 themes to choose from at https://themes.gohugo.io/ tagged with blog. You probably want one that’s responsive, and if you’re planning to modify it, you’ll need to pay attention to the theme’s license.

When you see one you like, click on it to go to the theme page. There should be a writeup on how to use it, a demo button and a download button. Click the demo button to see the theme in action. Click on the download button to visit the theme’s GitHub repository.

Make a note of the repository path. You’ll need it to install the theme. Also, make sure the theme has an exampleSite folder.

In the end, I chose Icarus. I like the way it looks, it is extremely well documented, it has all the blogging features I need without requiring any extra front-end / Node.js tooling, and it is the base used for R Views

Theme selection checklist

  • Is the theme tagged blog and responsive?
  • Can you abide by the license?
  • Is the documentation usable?
  • Does it have an exampleSite?
  • Do you like the way it looks?

Create the blog directory

First, clone your blog repository and open RStudio in it. Don’t create a project yet.

Next, in the console, type blogdown::new_site("<blog-directory>", theme = "<theme-path>"). <blog-directory> is the name of a new folder to hold the blog. Blogdown won’t create a website in your root folder because it already has files in it - the README.md, etc. Use the name of the blog for the directory name.

<theme-path> is the last two components of the GitHub repository path. For example, Icarus is at https://github.com/digitalcraftsman/hugo-icarus-theme, so <theme-path> would be "digitalcraftsman/hugo-icarus-theme".

Blogdown will serve up the new site by default. It should look exactly like the demo page did; it has the content from the theme’s exampleSite, not yours! Press the red Stop button to stop the server.

Create an RStudio project

Now use the RStudio New Project dialog to create the project with Use existing directory in <blog-directory>. Then open the project options and edit the Build tools. Uncheck Preview site after building.

In the Sweave section, set the Weave dropdown to knitr. If you’re using R Markdown documents with LaTeX equations, you may need to install XeLaTeX and set that option in the Typeset dropdown. I got some Pandoc errors when I had it set to pdfLaTeX.

Edit config.toml

In your <blog-directory> you’ll find a file named config,toml. Blogdown copied it from the theme’s exampleSite, so it will have variables defined for the sample. Each theme has different parameters so you’ll need to consult the documentation for the theme you’re using.

For Icarus, you’ll at least need to change * the baseurl to the URL where your blog will be deployed, * the title, * the information in Tell me who you are, and * the identifiers in the social media fields.

Unless you’re an experienced blogger, I recommend against enabling Disqus comments. If your thene allows Disqus commenting, there will be a parameter in config.toml like disqusShortName; set it to an empty string to disable Disqus. My Icarus blogs have disqusShortname = "".

Remove the exampleSite content

When Blogdown created the site, it copied content from the theme’s exampleSite into your blog’s content/post directory. Most of the themes I looked at have a default set of “Getting started with Hugo” posts there. You should read them, but you’ll need to delete them before you start writing. They’ll be in the exampleSite directory in the theme, so you don’t need to save them.

In the RStudio console, type blogdown::site_serve(), or select the Serve Site addin. A viewer window will open pointing to the blog. I recommend opening it in the browser as well. Whenever site_serve discovers a change in the data, it will rebuild the blog and the viewer will update. You’ll have to refresh the browser manually.

Go into the <blog-directory>/content/post directory and delete all the .md files. site_serve will detect the change and update the blog in the viewer. If there’s any other content in the content directory, remove that as well. This is your blog now!

Write a “Hello, World!” blog post

If you have a site server running, stop it. Then use the New Post addin to create a new post. You’ll get a form to fill in with the post metadata, then you’ll have a blank post in the Editor window. Once the edit window has the blank post, start up the site server again.

Edit the post in the RStduio editor window, Every time you do a Save, the server will reload the post in the viewer. When you’re done, it’s time to save everything in your Git repository.

Version control

Generally speaking, you only want to version-control source code / documents, not results that can be regenerated. So your .gitignore file should ignore

  • public - where Blogdown puts the published blog,
  • blogdown - where Blogdown puts intermediate results,
  • any HTML that’s generated in the editing process that can be re-generated, and
  • the themes directory. As you’ll see below, there’s no need to change any files in the themes.

Edit the .gitignore that RStudio built when you created the project, then do your commits and push.

Deploying

I’m not going to say much about deployment. I have all my static sites on Netlify, but you can host them for free on GitHub, GitLab or Bitbucket easily.

Customizing the theme

You probably noticed when Blogdown built your site, there were some new directories - archetypes, data, layouts, and static - in addition to the content directory where your posts and pages live. If you look in the theme directory you’ll see the same directories.

Roughly speaking, to customize a theme, you find the element in the theme directory you want to modify and copy it to the same place in your blog. Then you modify the copy and when Hugo builds the site, your modified copy will over-ride the theme.

For example, I added a Creative Commons license to the footer of every page in my sites. In the theme, that lives in themes/hugo-icarus-theme/layouts/partials/footer.html. So I copied that file to <blog-directory>/layouts/partials/footer.html and added the Creative Commons HTML to the bottom. Now when Hugo rebuilds the site it uses that file for the footer. Note that if you have a site server running, you’ll see the result as soon as you save the updates.

There’s a lot more on themes and customizing them on the Hugo site; start with https://gohugo.io/themes/customizing/. Static site theming / customization is a highly marketable skill, just like WordPress theming / customization has been, so I think learning it is time well spent.

Share