I attended the blogdown session at the RStudio conference in Florida. I am enjoying the enthusiasm and energy around R and RStudio. It reminds me of the early days of personal computers at the end of the 70’s and the beginning of the 80’s. Perhaps I am experiencing a second childhood. Anyway, all the Cool Kids are doing web pages on GitHub so I want to do it too.
I have done some simple blog posts with Blogger and WordPress. One of my goals is to create a portfolio of the my R projects. RMarkdown is the obvious way to go and WordPress doesn’t directly support that. So that’s a motivation to use blogdown. But a big part of the motivation is that these days I am “all in” with the RStudio set of tools so it’s natural to put my faith in Yihui Xie and jump in. Because blogdown is still developing, I know I am going to suffer through rough edges. As a retiree, I am doing this for fun so the rough edges just add to the adventure.
I had a little trouble to start because I didn’t understand the basics of
what was going on with GitHub and web pages. Here I am focused on what GitHub refers to as a “user site” (as opposed to an organization site or a project site). See their general description of GitHub Pages and What is GitHub Pages?. The key
fact is that if you have a repository called
username.github.io (with your
GitHub username), whatever is in that repository will be served
as a web site accessed as
we are going to do here is describe how to use markdown, RStudio,
and GitHub to place the content of a static web site into
The site relies on blogdown and GitHub. You have to have at least a beginner’s familiarity with GitHub, and believe me, I am merely a GitHub beginner. I got my start with GitHub mostly based on information from Jenny Bryan (see Happy Git and GitHub for the useR) and from RStudio. There’s also an introduction on the GitHub site.
You need to be able to create a repository on GitHub and then clone that to a project in RStudio. See especially section 16 on Happy Git.
In general I try to operate in a way that allows me to rely on RStudio to do most of the work and to avoid doing git commands in the Terminal on OSX. That’s why I create a minimal repository first on GitHub and then create a new project in RStudio that clones the repository from GitHub. Rely on Jenny’s directions on how to do that.
Creating a website
To get started with blogdown, I relied on a post by Amber Thomas,
especially the comments on the post by Yihui Xie, the creator of
blogdown. Amber’s instructions involve more work with Git than I wanted
to attempt. In particular, she uses multiple branches. Instead,
I followed the suggestion in the comments by Yihui Xie and created two repositories.
One was for the site itself (
johngoldin.github.io) and the other (which I called
pages-source) contains the blogdown and Hugo material
that actually produces the site.
- Create a repository for username.github.io on your github.
- Clone that to a RStudio project with the same name.
- Create a repository on your github, any name you desire, but here we will call it
- Clone that second project to an RStudio project.
You are going to use blogdown to create a Hugo site created by files in the RStudio project
hugo-source. And you are going to configure that site
so that whenever it builds a website, it will place that
website into the RStudio project username.github.io.
When you push username.github.io to GitHub you will in effect
publish your website.
(It doesn’t matter whether or not you maintain
a GitHub repository for
hugo-source. It depends on whether
you want to use version control for convenience or backup, just
as would be true for any other RStudio project.)
Kevin Wong does a nice job of describing the steps needed to get started with blogdown. Too bad I didn’t discover this page until after I started writing this description. But I will follow his text closely here.
Here are the steps in the RStudio project that contains the source for Hugo. If you don’t already have
devtools installed as a pckage, use the Packages tab in RStudio to add that package.
In the RStudio project hugo-source (or whatever you have called it), have blogdown install hugo.
Next we wil have Hugo create a new site:
The hugo-source site has to be totally empty. Otherwise you will get an error. Of course as created it will not be totally empty.
You will have an RProj file and probably
.gitignore. Move those
out of the project folder and keep them somewhere safe. Run
new_site again and them move them back into the project folder.
Next you need to install a Hugo theme. Go to the themes page to find one you like. It’s hard to know what to pick when you are just starting out. I’m a novice as well so I can’t offer good advice. You can avoid a choice for now and just stick with the default theme that is installed as part of the new_site() call.
If you have chosen a different theme, use the install_theme call:
The above commands will be needed only once when you first setup the project.
To try out your site,
With luck, the web site should appear in your RStudio View pane.
If you make changes in a post, they will automatically update
in the site if it is running, You press the stop button to halt the site. To restart it in the RStudio Viewer pane, you
can again use
How to you get this site running in GitHub? There’s a neat trick.
config.toml file in the
hugo-pages project folder and
add this magic line:
publishDir = "../username.github.io" # where username is your GitHub name
Whenever you run blogdown::serve_site(), the constructed site will be
created in the
username.github.io directory rather than in
To get the site working on GitHub, switch to the
username.github.io project in RStudio,
go to the Git pane in RStudio, select all the changed files,
Push the changes to GitHub. Magic! The same code
that is creating the trial web site on your local computer will
now be reproduced exactly in the
repository on GitHub and can be accessed as http://username.github.io.
You can work on your web site on your local RStudio project. When you think it is ready to publish changes
for all the world to see, go to the
username.github.io project and
push the changes to GitHub and you have published your changes on the web.
In summary, here are the steps to maintain the site:
1. edit the site in the hugo-source project
2. run blogdown::serve_site() to refresh the site
3. switch to the username.github.io project on your local machine
4. commit all changes
5. push those changes to username.github.io on GitHub.
I now have a working web site on GitHub. But I have a ways to go to learn how to take advantage of Hugo on an ongoing basis. So far I have added one and only one post. I have looked at the Hugo documentation a bit to try to figure out how to do some basis things. For example, this page tells me how to add a cross-reference to a post on my site.
It is not yet clear to me how I will take advantage of my Hugo GitHub site on an ongoing basis.
One of the features of blogdown is that I can use RMarkdown.
How will I do that in practice?
I’ll have an RMarkdown file in a project I am working on that
documents or demonstrates that project. Will I
knit the file
and then move the html to my blogdown project? Will
I move the Rmd file to the blogdown project and include a
call to point to the project that it comes from? I haven’t
tried any of this in practice yet. I need to look at the existing blogdown
examples more closely. When I know more, I’ll add to this introduction.
I have switched to the Hyde-x theme rather than just Hyde.
Configuration has involved a lot of trial and error.
I setup Disqus and briefly saw the ability to do comments on my blog. But after and I made some unrelated changes,
I no longer saw any sign of Disqus.
Eventually I realized that I was confused (and ignorant) about the
config.toml. I had had a square-brackets author line above
the line that set
disqusShortname and as a result
wasn’t getting set. I moved things around and comments reappeared.
This is typical of the blundering around I am doing with Hugo and themes. I guess it’s a learning experience.
Things I Have Learned Since I First Posted This
If you follow my steps exactly as described here or the instructions at the RStudio blogdown readme, you
are likely to end up with a two-tiered directory structure. You create an
RStudio project for your site (the top level) and then when you run
blogdown::new_site() you create a new directory within that project
directory. That didn’t seem right to me, so behind the scenes I “fixed” that
and flattened things so that my hugo site directory was the same as my RStudio project.
Since then, I’ve decided there is probably some advantage in keeping
the hugo site as a separate directory inside the project directory. It’s not
a big deal, but having two levels gives you a place to put additional related
material that is not directly related to your web site. As of now I have “flat” one-directory structure for my blogdown site. But if you
follow the description in this post and end up with a two-level structure,
How To Manage an RMarkdown Post
I finally did my first RMarkdown post. As is likely to be the case,
it is derived from a separate RStudio project. How should I deal with the
working directory? The RMarkdown file is in my Hugo blogdown project. But
the data file I need for my work is in the original project directory.
At first I thought I should change the working directory with
but I wondered about what side effects that might produce.
A post on Stack Overflow steered me away from
I now know I should use something like
knitr::opts_knit$set(root.dir = '../myproject'). I have been having some trouble with that,
presumably because of the
.. notation to go up a directory, but
I haven’t taken the time yet to case that out. Being impatient I cut
corners and sort of hardcoded the file reference in my Rmd file. I’ll go back
and fix that once I figure out the