Hugo Theme Customisations

Keeping Theme Customisations While Using Git Submodules or Cloning#

If you use a Git submodule or clone a theme, any changes made directly in the theme directory will be lost when you set up a new machine. To avoid this, all modifications should go in your project root.

Best Workflow for Customising a Theme Without Losing Changes#

1. Keep the theme as a Git submodule (or clone it).
2. Place all modifications in your project root (without modifying the theme directly).
3. Ensure your repository includes only your customizations (not the theme itself).
4. Set up your project on a new machine properly to restore both your files and the theme.

Step 1: Clone a Theme as a Submodule (Recommended)#

Instead of cloning the theme manually, add it as a Git submodule:

git submodule add https://github.com/theme-author/theme-name.git themes/theme-name

• This keeps the theme separate from your custom files.
• Your repository will track only the reference to the theme, not its files.

Step 2: Make Customizations in the Project Root#

Instead of modifying themes/theme-name/, put overrides in your project’s layouts/ and assets/ folders.

Example: Customizing header.html Without Editing the Theme#

1. Check if the theme has header.html in themes/theme-name/layouts/partials/

2. Copy it to your project:

   mkdir -p layouts/partials
   cp themes/theme-name/layouts/partials/header.html layouts/partials/header.html
   

3. Make changes in layouts/partials/header.html

   • Hugo will use this file first, ignoring the theme’s version.

Step 3: Pushing Your Project to Git Without the Theme#

You want to track your custom files but not the theme itself.
In your .gitignore, add:

themes/theme-name/

Then commit only your project files:

git add .
git commit -m "Custom modifications"
git push origin main

Step 4: Setting Up a New Machine#

When you clone your project on a new machine, the theme folder will be empty because it was a submodule.

1. Clone your project:

   git clone https://github.com/yourname/your-hugo-site.git
   cd your-hugo-site
   

2. Initialize and pull the theme:

   git submodule update --init --recursive
   

3. Now everything works as expected!

Alternative: Forking the Theme If You Need to Modify It#

If you need deep changes to the theme itself (beyond Hugo’s override system), you can:

1. Fork the theme’s repo on GitHub.

2. Use your forked theme as a submodule:

   git submodule add https://github.com/yourname/theme-name.git themes/theme-name
   

3. Now you can modify the theme directly without losing changes when switching machines.

Summary: Best Practices#