Contributing to the LIBD rstats club
In this blog post Leonardo Collado-Torres explains how to contribute posts to the LIBD rstats club. While some parameters are specific to this blog, you could also use this for creating your own community blog.
Install necessary tools
We first need to get the appropriate tools installed in our computer.
Lets start by installing the latest version of R. At the time of writing this post, that would be R 3.4.3 but in reality this should work with any R 3.4.x version. It might even work with earlier versions, but it’d be a bummer to find out that we have an R version problem later on.
Once we have an up to date R version, lets install RStudio. By using the latest version we will have access to RStudio addin menus, which will make our life much easier. Since we will be using RStudio quite a bit, it’s best to work from your laptop/computer than any server or cluster where you might not have the flexibility to install/update RStudio and R.
We next need to install the main package that we will be using for creating our blog posts, that is blogdown (Xie, Hill, and Thomas, 2017). At the time of writing this post, the version that we need to use is only available in the development branch. So we need to install blogdown via devtools (Wickham, Hester, and Chang, 2018).
## If needed install devtools first: install.packages('devtools') ## Install development version devtools::install_github('rstudio/blogdown') ## If you are reading this in the fiture, you might only need install.packages('blogdown')
At some point we might need two other extra packages that blogdown uses. It will show you a message when that happens, so you can install them when you need them or you could go ahead and get them anyway.
We are almost there! blogdown uses hugo which they claim is the world’s fastest framework for building websites.
hugo is a bit complicated, but it makes maintaining a complicated website such as a blog super easy. Basically, we will be working in the
rstatsclubsource directory and
hugo will create the final version we can share around in the directory
Ok, lets go head and install it with
To get the files and interact with other LIBD rstats club members you will need to use
git, which you can install following these instructions from the happygitwithr website. A note for Windows users: get git for windows because it includes
git bash and will enable you to run some commands that we will need later on. Even more advanced for Windows users, when installing
git bash choose the use git and optional Unix tools from the Windows Command Prompt as described in detail here.
Also get a GitHub account if you don’t have one already. Optionally set up ssh keys for password-less login, though it’s not needed.
Access blog source files
The file structure of our blog involves a total of 3 GitHub repositories that are related to each other as shown below. However, you will only need to interact with one of them.
rstatsclubsource ## From https://github.com/LieberInstitute/rstatsclubsource content/ post/ ... static/ post/ img/ ... themes/ hugo-academic/ ## From https://github.com/gcushen/hugo-academic ## linked as a git submodule public/ ## https://github.com/LieberInstitute/rstatsclub ## Hosts the files that make up the website ## http://LieberInstitute.github.io/rstatsclub/
The main directory for the blog is
rstatsclubsource and you can access it at github.com/LieberInstitute/rstatsclubsource if you are a member of the LIBD rstats club and have logged in to your GitHub account. This directory contains many files that blogdown understands and that you don’t really need to change. The main sub-directory that you will be interacting with is
rstatsclubsource/content/post where your new post files will get saved by blogdown. If you insert images, blogdown will automatically create the directory
rstatsclubsource/static/post/2018-03-09_postTitle_files (example), but don’t worry about it.
Ok, lets get the files. Open your terminal or
git bash (Windows) and navigate to the directory where you will store your copy of the source files.
## Works in Mac and Windows (with git bash) cd ~/Desktop ## Windows example command if you have more than 1 disk cd /f/Desktop
Next clone github.com/LieberInstitute/rstatsclubsource. Here we use https since that doesn’t require extra setup, but cloning by ssh also works.
git clone https://github.com/LieberInstitute/rstatsclubsource.git
After a successful clone, we should have created the directory
~/Desktop/rstatsclubsource. Lets change to this new directory.
Our cloning process also created a placeholder for our hugo theme (hugo-academic) but it’s contents are empty.
$ ls -lh themes/hugo-academic/ total 0
Lets fill them up by running the following git command.
git submodule update --init --recursive
If we now check the contents of the
themes/hugo-academic directory we should see several files now (here’s a screenshot from Windows using
ls -lh themes/hugo-academic
Our setup is now complete! We can now start writing blog posts using blogdown. Open the
~/Desktop/rstatsclubsource/rstatsclubsource.Rproj file, which should open a new RStudio window automatically. Find the Addins menu on the top of your window, and select the
Serve Site option in the drop-down menu.
This addin will create a local version of the website you can preview in the RStudio Viewer pane.
If you click in the show in new window symbol as shown below
you then can preview the website in your main browser:
This will be super useful when you are writing a new blog post because any changes you make will automatically refresh the local preview version after a second of two (only after you save the file you are editing). Sometimes you might have to manually refresh your browser (like when you make too many updates in a row). The preview website works as long as you have the Serve Site addin running on the background.
All our files
By running Serve Site blogdown actually populated automatically our
rstatsclubsource/public directory. So our full list of files look somewhat like this:
## Found about tree from ## https://stackoverflow.com/questions/3455625/linux-command-to-print-directory-structure-in-the-form-of-a-tree ## Intall in a Mac with homebrew: ## brew install tree $ tree -d rstatsclubsource . ├── archetypes ├── content │ ├── home │ └── post ├── data │ ├── fonts │ └── themes ├── layouts │ └── partials ├── public │ ├── 2018 │ │ └── 03 │ │ ├── 06 │ │ │ └── test-post-for-checking-website │ │ └── 09 │ │ └── welcome-to-the-libd-rstats-club │ ├── categories │ │ ├── page │ │ │ └── 1 │ │ ├── rstats │ │ │ └── page │ │ │ └── 1 │ │ └── setup │ │ └── page │ │ └── 1 │ ├── home │ ├── img │ ├── js │ ├── post │ │ ├── 2018-03-06-test-post-for-checking-website_files │ │ │ └── figure-html │ │ └── page │ │ └── 1 │ ├── publication_types │ │ └── page │ │ └── 1 │ └── tags │ ├── blog │ │ └── page │ │ └── 1 │ └── page │ └── 1 ├── static │ ├── img │ └── post │ └── 2018-03-06-test-post-for-checking-website_files │ └── figure-html └── themes └── hugo-academic ├── archetypes ├── data ├── exampleSite ├── i18n ├── images ├── layouts └── static
Some of the structure looks redundant right? Well, that’s because
hugo and blogdown tried to keep everything super organized and re-use some of the file structure for the final version of the website (the one inside
Write a blog post
We now have a working full preview version of the website in our computer. It’s finally time to write a blog post. The good thing is that we don’t need to do all the setup steps again!
Update if necessary
If you paused midway for a few days, it’s likely that your files are not the latest ones. So please
git pull the latest files from github.com/LieberInstitute/rstatsclubsource.
cd ~/Desktop/rstatsclubsource git pull
Start a blog post
To start a new blog post, use the New Post blogdown addin.
This will open up a window where you can specify the blog post title. The title will automatically fill out the slug which is used in the final URL of the post. It also lets you choose a date, when is when the blog post will be made publicly visible.
Use a blog template
Next lets choose the blog archetype (template) that for posts, that is
The reasons why a blog template is useful are described in full detail in this blog post by L. Collado-Torres. The quick version is that it will pre-populate your new blog post with helpful information and reminders on how to do \(X\) or \(Y\). For example, how to insert external images, how to control the figure height and width for images generated by R, how to cite packages, and including the R reproducibility information by default.
Use appropriate post categories
Most of our blog posts will likely be about R. For those blog posts, select the
rstats category as shown below.
If your blog post covers a topic that might be useful to new LIBD members use the
setup category. If it involves using the JHPCE cluster, use
jhpce as a category, etc. The New Post blogdown addin lets you see which categories and tags have been used before to classify posts. In general, we should aim to have a handful of categories while having as many tags as necessary. These will be useful for filtering our blog posts.
Hit done! (well check before)
We are now basically set to start our new blog post. Just double check:
- the categories,
- that the format is
- that the archetype is
- post title,
- post date,
- post author.
Aaaaand hit done!
Edit your blog post
You can now write your blog post using the R Markdown syntax. Note that you won’t be using the
knit button from RStudio since the Serve Site blogdown addin should be doing all the work for you and updating your local website preview.
When writing your blog post keep in mind our Code of Conduct and that your our blog posts have to comply with the confidentiality agreement we signed at LIBD.
We are keeping both github.com/LieberInstitute/rstatsclubsource and github.com/LieberInstitute/rstatsclub as private repositories to enable contributors to write posts anonymously.
The default license for our blog posts is (CC) BY-NC-SA 4.0 which you can read more about here. If you write a blog post under a different license, please make it clear. Also please attribute the sources of the material you use.
If you want to learn even more, check the blogdown book and the hugo-academic theme. Maybe you can help with this currently unresolved issue.
If you want to check a public version equivalent to the one described here, check:
- github.com/lcolladotor/hugoblog which is the equivalent of github.com/LieberInstitute/rstatsclubsource
- github.com/lcolladotor/lcolladotor.github.com which is the equivalent of github.com/LieberInstitute/rstatsclub
hugoblog ## From https://github.com/lcolladotor/hugoblog content/ post/ ... static/ post/ img/ ... themes/ hugo-academic/ ## From https://github.com/gcushen/hugo-academic ## linked as a git submodule public/ ## https://github.com/lcolladotor/lcolladotor.github.com ## Hosts the files that make up the website ## http://lcolladotor.github.io/
This blog post was made possible thanks to:
 C. Boettiger. knitcitations: Citations for ‘Knitr’ Markdown Files. R package version 1.0.8. 2017. URL: https://CRAN.R-project.org/package=knitcitations.
 A. Oleś, M. Morgan and W. Huber. BiocStyle: Standard styles for vignettes and other Bioconductor documents. R package version 2.6.1. 2017. URL: https://github.com/Bioconductor/BiocStyle.
 H. Wickham, J. Hester and W. Chang. devtools: Tools to Make Developing R Packages Easier. R package version 1.13.5. 2018. URL: https://CRAN.R-project.org/package=devtools.
 Y. Xie, A. P. Hill and A. Thomas. blogdown: Creating Websites with R Markdown. ISBN 978-0815363729. Boca Raton, Florida: Chapman and Hall/CRC, 2017. URL: https://github.com/rstudio/blogdown.
## Session info ----------------------------------------------------------------------------------------------------------
## setting value ## version R version 3.4.3 (2017-11-30) ## system x86_64, darwin15.6.0 ## ui X11 ## language (EN) ## collate en_US.UTF-8 ## tz America/New_York ## date 2018-03-10
## Packages --------------------------------------------------------------------------------------------------------------
## package * version date source ## backports 1.1.2 2017-12-13 CRAN (R 3.4.3) ## base * 3.4.3 2017-12-07 local ## bibtex 0.4.2 2017-06-30 CRAN (R 3.4.1) ## BiocStyle * 2.6.1 2017-11-30 Bioconductor ## blogdown 0.5.9 2018-03-08 Github (rstudio/blogdown@dc1f41c) ## bookdown 0.7 2018-02-18 cran (@0.7) ## colorout * 1.2-0 2018-02-19 Github (jalvesaq/colorout@2f01173) ## compiler 3.4.3 2017-12-07 local ## datasets * 3.4.3 2017-12-07 local ## devtools * 1.13.5 2018-02-18 CRAN (R 3.4.3) ## digest 0.6.15 2018-01-28 CRAN (R 3.4.3) ## evaluate 0.10.1 2017-06-24 CRAN (R 3.4.1) ## graphics * 3.4.3 2017-12-07 local ## grDevices * 3.4.3 2017-12-07 local ## htmltools 0.3.6 2017-04-28 CRAN (R 3.4.0) ## httr 1.3.1 2017-08-20 CRAN (R 3.4.1) ## jsonlite 1.5 2017-06-01 CRAN (R 3.4.0) ## knitcitations * 1.0.8 2017-07-04 CRAN (R 3.4.1) ## knitr 1.20 2018-02-20 cran (@1.20) ## lubridate 1.7.3 2018-02-27 CRAN (R 3.4.3) ## magrittr 1.5 2014-11-22 CRAN (R 3.4.0) ## memoise 1.1.0 2017-04-21 CRAN (R 3.4.0) ## methods * 3.4.3 2017-12-07 local ## plyr 1.8.4 2016-06-08 CRAN (R 3.4.0) ## R6 2.2.2 2017-06-17 CRAN (R 3.4.0) ## Rcpp 0.12.15 2018-01-20 CRAN (R 3.4.3) ## RefManageR 0.14.20 2017-08-17 CRAN (R 3.4.1) ## rmarkdown 1.9 2018-03-01 cran (@1.9) ## rprojroot 1.3-2 2018-01-03 CRAN (R 3.4.3) ## stats * 3.4.3 2017-12-07 local ## stringi 1.1.6 2017-11-17 CRAN (R 3.4.2) ## stringr 1.3.0 2018-02-19 cran (@1.3.0) ## tools 3.4.3 2017-12-07 local ## utils * 3.4.3 2017-12-07 local ## withr 2.1.1 2017-12-19 CRAN (R 3.4.3) ## xfun 0.1 2018-01-22 CRAN (R 3.4.3) ## xml2 1.2.0 2018-01-24 CRAN (R 3.4.3) ## yaml 2.1.17 2018-02-27 cran (@2.1.17)