... How To Keep Your Hugo Site's Content In A Different Repository

December 28, 2024

I use vim as my primary editor for everything related to code. But when it comes to writing blog posts, I don’t always use vim. In fact I don’t always use my laptop. I resort to a Markdown-Editor that is available on all my devices and has basic git-capability, so I can push it to a remote repository.

But how do I get the files from this repository into my blog?

I use Hugo as a static site generator. Hugo is Markdown-based, so there’s no need to convert my content-files into a different format.

That leaves me with two problems:

How do I get the files from my separate content-repository into my site’s folder structure (and keep them updated)?
How do I tell Hugo where to find the content?

Each problem has its own answer:

Use Git submodules to integrate two different repositories

I have two code bases: One for the mechanics of the site (config, layout, etc), and one for the content. The latter one is part of the first one. So the solution I opted for is using a Git submodule.

Adding a git submodule is easy. From the root of your parent repo do this:

# the --name option is optional, but could be important later!
git submodule add \
  --name <give-it-a-name> \
  -b main \
  <your repo url> \
  <your target directory>

This will create the target directory as well as a .gitmodules file that you can check into your main repo so it recognizes the submodule as a dependency. If you clone the repo in a different location, you only have to initialize the submodule:

git submodule init
git submodule update

That’s fine but there’s an edge case that might fall onto your feet here: Sometimes you need a different repo url for the submodule in a different environment. This could be the case if the environment only has limited access to the repository (e.g. a read-only access token that is part of the url).

In this case you can change the submodule repo url locally using git config:

# remember the --name option?
git config --local submodule.<your submodule name>.url <repo url>

After making this local change you can run the init and update commands and it will pull from the custom url.

Telling Hugo where to find the content

So how do we make Hugo use the content files from <repo-root>/<submodule-folder>/content instead of the default <repo-root>/content folder?

Luckily, this is an easy setting in the Hugo configuration:

# Add this to your hugo.yaml:
module:
  mounts:
   - source: <your submodule folder>
     target: content

That’s it, you’re all set!

Tags:

Hugo
Git