About a week ago I moved my two blogs from using a Drupal backend to being generated with Hugo. All in all, the experience has been positive, as Hugo allows me to preview my changes on my local machine before I upload any changes to the server. The hardest part was copying my existing posts and converting them to markdown format (which wasn’t hard at all).

I’ve even forked a couple of themes for my own use! I mostly just changed some of the CSS styling to use the colors I wanted, but I’ll probably do some more advanced changes in the future, just to try it out. Cause why the heck not?

There has been one issue though that I am still trying to figure out. Before I get into that though, a brief explanation of how Hugo expects websites to be set up:

File Structure:

  • content
    • post
      • first-post.md
      • second-post.md
      • index.md
    • other-thing
      • cool-stuff.md
      • _index.md
    • another-thing
      • stuff.md
    • another-thing.md
  • themes
  • static
  • config.toml

In short: the content folder is the one that content is put into (whoa), and each file in the content folder, by default, turns into the file /file-name/index.html - this is called “pretty urls.” Three things to note are the ‘index.md’ file inside of the ‘post’ folder, the ‘another-thing.md’ file on the same level as the ‘another-thing’ folder and the ‘_index.md’ file inside the ‘other-thing’ folder. All of these are methods that should create the ‘post/index.html’, ‘another-thing/index.html’, or ‘other-thing/index.html’ file. There is a default page template used if you don’t do this, but you may want to make the page yourself…

It seems that your mileage may vary with these tricks. I tend to use the ‘another-thing’ method, though in testing I’ve also gotten the ‘index.md’ method to work too. But for my other website, there have been… issues…

I sometimes write fan fiction and have started a new story that will be hosted on my other website. The folder structure will look something like this:

  • content
    • fan-fiction
      • story-1
      • story-2
      • index.md
      • _index.md

…Yeah. There’s two index files. Why? Because that’s the only way I was able to get the custom page to be generated correctly. If I had just ‘index.md’ (or the ‘fan-fiction.md’ file next to the ‘fan-fiction’ directory), then the template page would be generated with the title “Fan-fictions.” Just the ‘_index.md’ file correctly changed the title to “Fan Fiction,” but none of the actual page content showed up. Both ‘index.md’ and ‘_index.md’ together seem to fix the issue though, by generating the page based on the ‘index.md’ file - but ‘_index.md’ must be present for it to work?


Anyways, I’ve gone ahead and posted a bug on the Hugo GitHub. View it here.