Who Would Have Thought The Slug Was The Bug

This post is of the the folder structure of a blogdown website, to get a basic understanding of how it works and to also remind myself next time I face a similar publishing issue!

Publishing issue

I have been updating my blogdown website with posts, and then I hit an issue. The about link would not update. I tried multiple amendments and multiple commits to no avail. I then re-created the whole website and reinstalled the theme. This still didn’t work. I finally figured out that the slug in the about.md file was about-me, and the build site saved the index.html in an about-me folder. However the corresponding HTML file was looking for a github.io base URL ending with about-me, which did not exist. I changed the slug to about and it now updates.

Review of blogdown website structure

I went back through the documentation to review the structure of a blogdown website:

• a config.toml file uses TOML to configure the website and to define global variable names and links.

• TOML syntax is as follows:

The primary building block of a TOML document is the key/value pair

For example :

  key = "value" 
        or 
  weight = 1

Tables are collections of key/value pairs. They appear in square brackets on a line by themselves.

For example :

  [social]
        twitter = "kim_fitter"
        github = "kimnewzealand"

An array of tables… can be expressed by using a table name in double brackets. Each table with the same double bracketed name will be an element in the array.

For example :

  [menu]
        [[menu.main]]
              name = "Home"
              url = "/"

        [[menu.main]]
              name = "About"
              url = "/about/"

• each URL has a corresponding index.html file. When we build the Hugo site, a markdown source file in the blog source directory creates this index.html in another publishDir variable directory, in a folder with the same name as the source file’s slug by default. This publishDir directory folder structure determines the permanent links (permalink) of your web pages. The permalink rules can also be customised in the config.toml file.

• Each markdown source file has YAML metadata at the start. This YAML includes the slug which is a character string as the tail of the URL.

In Summary

1) The source file \blogdown_source\content\about.md

2) Creates \kimnewzealand.github.io\about\index.html

3) As viewed in the https://kimnewzealand.github.io/about/ URL.