Things I noted

• I changed the name of the “Public” folder to “docs” so that my site can be built from the “docs” folder on GitHub. This seems the simplest way to organise this. The alternative is to have the “Public” folder on a different branch.
• Sometimes it’s a challenge to troubleshoot why things aren’t working they way you want. E.g. I couldn’t work out why the country wouldn’t show up in the document when including an address in YAML
• A header image/thumbnail can be included in the same folder as the content but it must be called “featured” or it won’t be recognised. File names are case-sensitive
• You can have as many folders as you want called whatever but the (r)markdown file of the page must be called “index”
  • In the “Courses” feature the parent page must be called "_index" or it won’t work. 🤷
• Rmd and the “Courses” feature don’t play nicely. Defining a table of contents via bookdown outputs in the YAML doesn’t work and calling toc: true directly in the YAML (following the guide) doesn’t work either.
• bookdown and blogdown don’t play nicely together in the same project either. blogdown will try to render the bookdown pages as a site rather than letting bookdown do its thing and make a nice gitbook.
  • To allow this behaviour, you need to make use of the static file builder (See below)
• Despite the template saying “Upcoming talks” Hugo doesn’t render things in the future (incl blog posts). You need publishDate in the YAML
• emojis are a nice feature 😄

Using the static folder to render a gitbook

To render rmd files into another output than blogdown::html_page you can put the rmd in the “static” folder then write a script that compiles the site in a specific order. To permit a gitbook page within the site:

1. Save the bookdown files in the “static” folder
   • It doesn’t work with files in the “content” folder, these will get the usual treatment
2. Create a folder called “R” in the root directory
3. Create an R script called “build.R” in the “R” folder
4. Add the render functions you need.
   • blogdown::build_dir("static") is a wrapper for plain rmarkdown::render() as is so it works best with simple files
   • build_dir doesn’t work for our gitbook example because we want a gitbook that knits with bookdown::render_book, otherwise you will get a bunch of HTML files from the standard render function
   • There’s something funny going on with the working directories. Running render_book("static/index.rmd") doesn’t work, neither does the full address. Instead I had to change the working directory for the function to find the right files. I’m not sure where the function is looking as the project working directory is the root directory.

The above means that all the rmd files for the gitbook also get copied into the “docs” folder. I don’t think it’s avoidable. It’s also s l o w e r to build the site because the gitbook gets rendered every time (unless you “comment it off” in the build.R script.

I also have a line to render my CV rmd into a PDF saved into the static folder. That PDF is then copied to the “docs” folder so I have an updated CV without needing to manually create one every time I update the original rmd. I think this is pretty handy.

Here’s what my build.R file contains:

# Make CV PDF
rmarkdown::render('content/cv/index.Rmd', output_format = rmarkdown::pdf_document(keep_tex = FALSE), output_dir = "static/files/", output_file = "Kong_JD_CV.pdf")

# make gitbook
# blogdown::build_dir("static") doesn't work because we want a gitbook that knits with render_book
# whereas build_dir uses rmakrdown::render() thus giving html files
old <- getwd()
setwd("static/teaching/GLM/")
bookdown::clean_book(clean = TRUE)
bookdown::render_book(input = "index.Rmd")
setwd(old)

Having a drafts folder

Hugo will not render draft blog posts by default but blogdown will still render the files for your local site and these files get pushed to GitHub. If you don’t want your repo to contain spoilers, then you need to separate your draft posts from the published posts.

One solution to stop blogdown from rendering .rmd files is to keep them in the “static” folder but Hugo will copy these files to the “public” (or “docs” folder in my case). I could not find an option to tell Hugo to ignore some files in the “static” folder. This does not solve our spoiler problem.

We can have a “draft” folder under “content” and tell Hugo to ignore it in the config.toml file (ignorefile) but that doesn’t stop blogdown from rendering the file.

I haven’t found a solution to stop blogdown from rendering and Hugo from copying the file but Hugo doesn’t add every folder from the root directory to “Public”, only folders that match the template. So I have a folder called “drafts” which contains my drafts. blogdown will still render the files every time they are saved while using serve_site but they won’t interfere with the site itself. When I’m ready to publish them I can copy them to the “content/post” folder. I also added the “drafts” folder to my .gitignore.

blogdown has a handy function to generate a new blog post. By default it will add the new files to “content/post” but I changed this to write directly to the “drafts” folder via the variable subdir and with a custom date that is used to name the folder:

blogdown::new_post(ext = ".Rmd", title = "test", subdir = "../drafts/", date = "2021-01-01")

files = files[!grepl("^_", basename(files)) | grepl("^_index[.]", basename(files))]

Other customisations via “layouts/partials” templates

Because Hugo copies any folder in the root directory into “docs” which matches the theme template, it will override any files in the “themes” folder that matches the name of the folder in the root directory. This means that you can create custom templates without modifying the original template. Thus, having a folder called “layouts/partials” will override any “partials” templates within the “theme” folder.

I have added some minor customisations to reflect personal preference:

• Added markdown to the author list in page_metadata_authors.html so that I can customise my name and bold it in the list of authors under publications
• Changed the site footer to include blogdown
• Changed page_metadata.html to show both the last modified and published date. Last modified date is default.

I’m not saying goodbye to the grasshoppers so my flavicon is a grasshopper emoji 🦗