Hugo Restructure Posts

In this post, the 6th for my github pages site, I’ll be exploring changing the structure of my Hugo site so that I have a content management strategy in place for future.

I’ve always been someone that likes my file systems to be organised by folders in the style of a taxonomy. When I started using the internet, that was how the most popular search engines at the time worked. Yahoo! had just introduced a search engine element to it’s site but the primary means of navigation was still to drill down to information I was looking for through a series of directories.

I’m not sure why I like to store my data this way, but I do like being able to navigate to what I’m trying to find quickly. I still use search heavily, but I think keeping files well organised gives me the best of both worlds - I can still search for the information I want, or navigate to the information I want.

The problem I had with my Hugo repo was that my content organisation strategy wasn’t working. I had used the Quick Start guide and then continually repeated the process defined in there for making new posts. This is fine for a single post trial but doesn’t scale well when more posts start to get added. After my first few posts my Hugo file structure looked like this:

.
├── archetypes
├── content
|   └── posts
|       ├── batocera-picade.md
|       ├── hugo-customisation.md
|       ├── hugo-setup.md
|       ├── hugo-theme-change.md
|       └── hugo-themes.md
├── resources
└── static
    ├── 01.png
    ├── 01_DefaultHugoPage.png
    ├── 01_FacebookLink.png
    ├── 02.png
    ├── 02_TwitterLink.png
    ├── 03.png
    ├── 03_LinkedInLink.png
    └── 04_DefaultHugoPage.png

This did not match what I would consider to be a well structure file system. I did start to organise the /static folder into subfolders but I didn’t like having the written content and visual content separated, it was becoming hard to manage. My ideal situation would be to have all post related content in one place, in Hugo this is possible through the use of page bundles.

Moving post files

First step of the re-organise is to move post files to their own directories under /content/posts and rename the post files. Once this is done it means there is a page bundle per post and the creation of the bundles is as simple as:

1. Create a folder with the same name as the blog post
2. Move blog post to the directory
3. Rename the main blog file to index.md. If this is not done, the URL for a post would be posts/hugo-restructure-posts/hugo-restructure-posts. The change in filename removes the duplication in the URL so it appears as posts/hugo-restructure-posts

Once the content move is complete Hugo can be run and the site viewed, there should be no noticeable difference from what existed before.

Moving media files

Second step is to move the media files out of /static and into the folder for each post. Unfortunately, this didn’t work out of the box:

After a bit of digging, everything I found suggested that it should just work until I found a section on the GitHub page for the theme that I use about organising page resource. A quick update to my config.toml to add usePageBundles = true and my images stored next to my posts started appearing locally.

With no file names changed, the images started appearing with no other work needed, this is because the reference to the image from the post, e.g. ![Default Hugo page](/01_DefaultHugoPage.png) will look in several locations to see if an image exists and use the first one it finds.

Now that the reorganisation is complete, my Hugo source repo now looks a lot more pleasing, for me anyway:

.
├── archetypes
├── content
|   └── posts
|       └── batocera-picade
|       |    ├── index.md
|       |    └── 01_GitView.png
|       ├── hugo-customisation
|       |    ├── index.md
|       |    ├── 01_FacebookLink.png
|       |    ├── 02_TwitterLink.png
|       |    ├── 03_LinkedInLink.png
|       |    └── 04_DefaultHugoPage.png
|       ├── hugo-setup
|       |    ├── index.md
|       |    └── 01_DefaultHugoPage.png
|       ├── hugo-theme-change
|       |    ├── index.md
|       |    └── 01_GitView.png
|       └── hugo-themes
|            ├── index.md
|            ├── 01_HugoCoderThemeGitLink.png
|            ├── 02_HugoShellThemeGitLink.png
|            └── 03_HugoTerminalThemeGitLink.png
├── resources
└── static

Although I am happy with the structure at the moment, I suspect there will come a time when I want to reorganise again, especially if I start adding a lot of content.