remlapmot / remlapmot.github.io

Personal website built using the blogdown package in R and hosted on GitHub Pages

GitHub Pages website source code

This repo contains the source files and built site for my personal website made with the blogdown package in R, Hugo, and the Academic theme.

Building the site

• Install the blogdown package

  install.packages("blogdown")

• Install Hugo

  blogdown::install_hugo(version = "0.127.0")

• Create a new directory called GITHUB_USERNAME.github.io and initialise this as a Git repo (e.g., using GitHub Desktop)

• Within this empty repo create a new Academic site

  blogdown::new_site(theme = "gcushen/hugo-academic")

  • This now downloads the contents from their new wowchemy repos here and here

• Open the repo as an RStudio project by double clicking the .Rproj file or run from within RStudio (with the working directory as the repo directory)

  # rstudioapi::initializeProject() # .Rproj file now created by blogdown::new_site()
  rstudioapi::openProject(path = '.')

• Add the version of Hugo in a project .Rprofile file containing the line

  options(blogdown.hugo.version = "0.127.0")

• Serve the site as you build it (nb. simply opening index.html in a browser doesn't render correctly because a web server is required to be running)

  blogdown::serve_site()

  • In a browser go to the address printed in the R console, http://localhost:####
  • The locally served site will updated when you resave relevant content files

• Edit the content as required

  • The content goes in the content/ directory
  • PDF files etc. go in the static/ directory
  • Edit configuration settings in newer versions in the YAML files in config/_default/

• To stop the served site run

  blogdown::stop_server()

Building the site for deployment on GitHub Pages

1. Build the site with a GitHub Action workflow, see blogdown.yaml which is edited from the r-lib/actions version here

   • Commit blogdown.yaml into the repo in the .github/workflows directory

   • Create a new branch called gh-pages and push that upto GitHub

     git checkout --orphan gh-pages
     git reset --hard
     git commit --allow-empty -m "Initializing gh-pages branch"
     git push origin gh-pages
     git checkout main

   • In the repo settings enable GitHub Pages (Pages tab) and select the Source as the gh-pages branch from its root/ directory

   • The GitHub Action workflow builds the site and puts those files into the public folder. These are then moved to the gh-pages branch, which GitHub Pages serves as the website.

   • Push your commits on the main branch upto GitHub, which will trigger the GHA to build the site

   • You can view the workflow on the Actions page of your repo (e.g. here)

2. Build the site locally

   • With earlier versions of the Academic theme add the following line to config.toml

     publishDir = "docs"

   • With more recent versions of theme add the following line to config/_defaults/config.yaml

     publishdir: docs

   • You might need to delete the docs/ entry from your .gitignore file if that was generated by e.g., GitHub Desktop

   • This is required because GitHub Pages only allows root/ or docs as the directory for its source on the main branch, i.e., the Hugo Academic theme default of the public directory is not allowed. In the repo settings change the GitHub Pages source to the main branch and its docs directory.

   • Then build the site locally with

     blogdown::build_site()
     # or: rmarkdown::render_site(encoding = 'UTF-8')

   • This creates the docs directory (instead of public) with the contents of the site. Note, this will not render correctly when opened locally in browser because it needs a web server running. Commit the docs folder into the repo. Delete the public folder if you have previously created that.

   • Push up to GitHub

• (If the pages build and deployment workflow completes successfully) your site will be served at https://GITHUB_USERNAME.github.io/

Updating the Hugo version over time

• Create a new branch

• Install the latest version of Hugo by running

  blogdown::install_hugo()

• Change the version number to the latest in the .Rprofile file (and in blogdown.yaml if using GHA)

• Verify whether the site builds by running

  blogdown::serve_site()

• If it builds, push a commit updating the Hugo version number upto GitHub