How to setup hugo-apéro on GitHub Pages ...

TL;DR

In this blog, I summarize the steps necessary to adapt the deployment of a Hugo-Apéro website to GitHub Pages. I also discuss how to use git submodules to include a theme dynamically.

Introduction

Hugo-Apéro is a Hugo theme for publishing websites using the blogdown package within R. In fact, it’s what I’m using to publish my personal site here!

Even if you’ve never used Hugo or blogdown previously, the setup is fairly straightforward. The steps outlined in the “ Get Started” blog series by creator Alison Hill are an excellent place to start. The series describes how to build a blogdown website in six steps:

1. Set up;
2. Create your site;
3. Site configuration;
4. Deploy your site;
5. Section configuration; and,
6. Page configuration.

For the most part, I followed the instructions laid out in the blog series above. However, I did make a couple of small modifications in steps 2 and 4. The remainder of this blog will dive into those modifications, namely:

• To deploy the site on GitHub pages instead of Netlify; and,
• To use git submodules to include the theme dynamically.

Create GitHub repository

The Hugo-Apéro setup instructions recommend publishing your site using Netlify. This is a great option; however, my personal preference is to keep everything within the GitHub universe. To do so, there are a number of small modifications necessary to the recommended setup.

The first change is to create a repository on GitHub, but make sure to use the following naming convention: [username].github.io, where “[username]” is replaced with your GitHub handle.

Create site

Once this is complete, create a new version-controlled RStudio project by cloning the GitHub repository you just created.

In the new RStudio project, use the blogdown::new_site function to create a new site skeleton via Hugo. Note that we avoid entering a theme parameter (i.e., theme = NA), such that we can install it manually.

> library(blogdown)
> new_site(theme = NA,
           format = "toml",
           sample = FALSE,
           empty_dirs = TRUE)

― Creating your new site
| Converting all metadata to the YAML format
| Adding netlify.toml in case you want to deploy the site to Netlify
| Adding .Rprofile to set options() for blogdown
― The new site is ready
○ To start a local preview: use blogdown::serve_site(), or the RStudio add-in "Serve Site"
○ To stop a local preview: use blogdown::stop_server(), or restart your R session
► Want to serve and preview the site now? (y/n)

We are asked:

► Want to serve and preview the site now? (y/n)

Select n as we have yet to add any content.

We can also delete the /netlify.toml file, as it is not necessary for publishing our site to GitHub.

> file.remove("netlify.toml")

[1] TRUE

Add hugo-apero submodule

Creating a git submodule is essentially adding a repository within a repository. Here we need to add hugo-apero to the /themes/ folder.

The steps described below are based on the blog “ How to Utilize Submodules within Git Repos” by Paige Niedringhaus. The documentation on git submodules is also a useful resource.

To add a new submodule to an existing project, open Git Bash, navigate to the project and, in the terminal, enter the following command ignoring brackets:

$ git submodule add [project URL] [folder name]

The “[project URL]” is the URL of project we wish to add (i.e. submodule), while the “[folder name]” is the name of the submodule directory we wish to see in the existing project (i.e. main repository). By default, submodules add the subproject into an eponymous directory in the project’s root directory. It is possible to use a different path by including it at the end of the command.

In our case, the Hugo-Apéro theme should be added under the /themes/ subfolder.

$ git submodule add https://github.com/hugo-apero/hugo-apero.git themes/hugo-apero

Once, we’ve added the Hugo-Apéro submodule, we need to copy the following files and folders to the appropriate locations within the website repository:

• /themes/hugo-apero/assets/ \(\longrightarrow\) /assets/;
• /themes/hugo-apero/exampleSite/config.toml \(\longrightarrow\) root directory;
• /themes/hugo-apero/exampleSite/content/ \(\longrightarrow\) root directory; and,
• /themes/hugo-apero/exampleSite/layouts/ \(\longrightarrow\) root directory.

This is necessary, since we did not include a theme when we created the site.

At this point, we should now have a few new elements in our “website” repository. Let’s take a closer look at each of them.

Publish to GitHub Pages

Now that we have our website setup locally, we can proceed to publishing it through GitHub Pages. The steps outlined in this section are based on the “ GitHub Pages” chapter within the Creating Websites with R Markdown book by Yihui Xie.

Edit .RProfile

Instead of GitHub publishing our website from the root directory, we would like it to do so from a subdirectory. Since, the only two options are to publish from the root or a /docs/ subdirectory, we must rename /public/ to /docs/.

Next, to ensure that the site is built in the /docs/ folder, we must add the following line of code to the .RProfile file in the root of the website repository.

> options(blogdown.publishDir='docs')

Finally, save .RProfile and restart the R session for the changes to take affect.

Add .nojekyll

To ensure GitHub does not rebuild our website using Jekyll, we need to create a (hidden) file named .nojekyll in the /docs/ folder.¹ This can be done by running the following line of code in the R console:

> file.create("docs/.nojekyll")

Build the website

Build the website locally using Hugo by running the following line of code in the R console:

> blogdown::build_site()

This should populate the /docs/ folder with the static website.

Push changes to GitHub

We can directly push our website to GitHub by running the following commands in Git Bash:

$ git add .
$ git commit -m "Publish website" 
$ git push origin HEAD

This will add all changes and submodules to the remote “website” repository.

Edit GitHub Pages settings

Finally, we need to adjust a few of the repository settings to ensure the website is properly published to GitHub pages.

The website should now be published online at the following link: “https://[username].github.io/”, where “[username]” will be replaced with your GitHub handle.

Workflow summary

From this point, my workflow in RStudio is outlined in the following steps:

1. Open the RStudio project for the site.

2. Start the Hugo server using blogdown::serve_site().

3. View the site in the RStudio viewer pane, and open it in a web browser using the “Show in a new window” button.

4. Edit and/or create content using RStudio.

5. After making changes, save the respective files to preview them. Subsequently, the console will detect the change, the viewer pane will update, and the web browser will also refresh.

6. When satisfied with the changes, build the website locally by running blogdown::build_site().

7. Add, commit and push changes to the “website” remote repository, including the built site in the /docs/ folder. From Git Bash and within the “website” repository, use the following code:²

   $ git add .
   $ git commit -m "Content updates"
   $ git pull
   $ git push
   

So, there we go. We now have our Hugo-Apéro website published to GitHub pages!

This setup entails that all GitHub content is public. Alternatively, we can use git submodules to keep parts of the remote repository private. To read about how to do so, see the following blog post:

• How to restrict access to a hugo-apéro website on GitHub Pages..