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.
- Install the blogdown package
install.packages("blogdown")
- Install Hugo
blogdown::install_hugo(version = "0.123.8")
- 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")
- 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 lineoptions(blogdown.hugo.version = "0.123.8")
- 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
- In a browser go to the address printed in the R console,
- Edit the content as required
- To stop the served site run
blogdown::stop_server()
- 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 GitHubgit 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 itsroot/
directory - The GitHub Action workflow builds the site and puts those files into the
public
folder. These are then moved to thegh-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)
- Commit
- 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/
ordocs
as the directory for its source on themain
branch, i.e., the Hugo Academic theme default of thepublic
directory is not allowed. In the repo settings change the GitHub Pages source to themain
branch and itsdocs
directory. - Then build the site locally with
blogdown::build_site() # or: rmarkdown::render_site(encoding = 'UTF-8')
- This creates the
docs
directory (instead ofpublic
) 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 thedocs
folder into the repo. Delete thepublic
folder if you have previously created that. - Push up to GitHub
- With earlier versions of the Academic theme add the following line to
- (If the pages build and deployment workflow completes successfully) your site will be served at
https://GITHUB_USERNAME.github.io/
- 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 inblogdown.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