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
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
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
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.
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
<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
baseurl to the URL where your blog will be deployed,
* 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
disqusShortName; set it to an empty string to disable Disqus. My Icarus blogs have
disqusShortname = "".
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
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.
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
themesdirectory. As you’ll see below, there’s no need to change any files in the themes.
.gitignore that RStudio built when you created the project, then do your commits and push.
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 -
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.