Thomas Goossens
How to quickly create and maintain a blog with R ?
Maintaining a blog allows you to keep track of what you have done and thought. When you don’t remember how did you succeed to find a solution to a tricky problem, browsing your old posts might help you. As a scientist, it’s also the perfect tool to communicate your results to a wider audience. Moreover it allows you to showcase your work and possibly get hired for a future project. Nowadays many tools exist for you to publish on the web. But as a R user you might be interested in a solution that seamlessly integrates with your habitual R workflow : blogdown !
How to build your site using blogdown ?
Downloading the necessary stuff
For a detailed explanation, I recommand you to read the full documentation on the blogdown official site. What would be need ? We juste need to install blogdown and Hugo (a static site generator like the famous jekyll). All of this can be achieved with 3 R commands :
install.packages("blogdown")
library(blogdown)
blogdown::install_hugo()Initiating a new site
Now that we have what we need, we simply initiate a new hugo site using the followin R command :
blogdown::new_site()Doing so will generate all the required files for your site to work. Once the command is executed, we can see our live site in action using :
blogdown::serve_site()Woah ! Pretty neat and quick, no ? If your site looks “strange” (no styling), you might need to edit some settings in its config.toml file located at the root of your site folder. At the top of the file, replace the value of the baseurl key by "/" and below this line add this key-value pair :relativeurls = true. Normallyh everything should now looks much more nice !
Changing the parameters of the site
Now in the config.toml you can change the default settings like the title, authorname, etc according to your needs. You can even add new menu items. Once you are happy with your custom config, you must delete your public folder to avoid possibly conflicting git settings (you will recompile it later, once your git submodules config is done - see below) and turn your blogdown server off :
blogdown::stop_server()Initialise git version control
As you will use github pages to make your website publicly available, you will need to make its root folder a git repository ((if you don’t know how to use git and github, I would recommand you to take some time to learn this inescapable tool for anyone who is building code). So head at github and create a new repository. This repository will hold the source files of your hugo blog and not the rendered blog (you will see why later). Once your hugo blog source files repository is created on github, you will add it as your remote repository for your local website root directory as follows :
$ cd <LOCATION_OF_WEBSITE_ROOT_DIR>
$ git init
$ git remote add origin https://github.com/<YOUR_USERNAME>/<reponame>.git
$ git pull
$ git push origin masterPublishing your site
Now that your sources are under version control, it’s time to make the rendered static site availble publicly. The first step is to create a special github repository that you must call <YOUR_USERNAME>.github.io. Once it is created, github will treat it as a special repo and everything you will put into it will be publicly availble at <YOUR_USERNAME>.github.io.
The second step is to add this repository as a submodule of your local website root folder actually stored in a fodler called public (the one yo uhave previously deleted) :
$ cd <LOCATION_OF_WEBSITE_ROOT_DIR>
$ git submodule add -b master git@github.com:<YOUR_USERNAME>/<YOUR_USERNAME>.github.io.git publicAt this point, you can tell R blogdown to reconstruct your site under this git versioned public folder :
blogdown::serve_site()This command rebuild your site in the public folder and allows you to inspect it your site in the RStudio viewer.
As the 2 latest commands have produced some new files, we need to commit and push these on github :
$ cd <LOCATION_OF_WEBSITE_ROOT_DIR>
$ git add .
$ git commit -m "adding submodule ref"
$ git push
$ cd <LOCATION_OF_WEBSITE_ROOT_DIR/public>
$ git add .
$ git commit -m "adding rendered files"
$ git pushNice ! Now you have keeped track of changes made both on your source files repo and on your rendered site repo. Wait a few seconds, and head at
How to change the design of your blog ?
If you want to change the theme of your blog, there are many ways to achieve this. I’ve found the following procedure to be the most efficient one. It also uses the git submodules feature. The main idea of the procedure is to separate the versioning of your theme from the versioning of your content.
Finding a theme
Head at https://themes.gohugo.io/ and find the theme that best suits your tastes. Click on its “homepage button”, and fork the repository.
Adding it to your website
$ cd <LOCATION_OF_WEBSITE_ROOT_DIR>
$ git submodule add -b master git@github.com:<YOUR_USERNAME>/<THEME_NAME>.github.io.git themes/<THEME_NAME> This command has cloned your theme in the theme folder of your website. To use it, first make a backup of your config.toml. Then, in your choosen theme folder, open the exampleSite folder and copy paste its config.toml file to your website root folder. We need to proceed this way because config.toml files are theme dependent. Edit it by inspiring yourself from what was in your backed up config file.
Once its done, you can ask blogdown to serve your site with its new design, commit and push both the sources and the rendered files.
Tweaking the theme
if you want to make changes to your theme CSS, edit its css file found in your theme’s static folder. As the theme was added as a submodule you can also version it using it.