- Author: [[Adam Ormsby]] - Full Title: How to Set Up a Hugo Site on Github Pages - With Git Submodules! - Tags:: [[Submodules in Git]] [[Publishing new content to Hugo site]] [[Hugo]] - URL: https://www.adamormsby.com/posts/how-to-set-up-a-hugo-site-on-github-pages-with-submodules/ - ### Highlights first synced by [[Readwise]] [[2020-12-10]] - Why Git Submodules? Every git project is stored as a versioned code repository (a repo). Git submodules allow us to reference other repos within a project, which effectively puts a project inside a project (or a repo inside a repo). The submodule’s code can then be used by the main project, but the submodule maintains its own commit and branch history, which separates the projects and can be a pretty powerful thing. In a Hugo project, most of what we see is source data - the raw files we manipulate before building our site. After Hugo builds our site, our ‘ready-to-publish’ data gets output to the public directory of our project. By turning the public folder into a submodule of the main project, we can treat it as a separate entity with a separate history. Let’s see what that process looks like. ([View Highlight](https://instapaper.com/read/1368373249/14828351)) - Benefits of Making a Submodule in ‘Public’ To recap, here’s our project setup so far. Let’s take a look at some of the benefits of this system. No accidental deploys - With our source code separated from our site data, it’s a lot harder to accidentally push unfinished work to our live site. Even if we make builds locally and push our source changes, we won’t push to our hugo-gh-pages-public repo without explicitly running commands to make that happen. *sigh of relief* Separate rollbacks - If something goes wrong, the main project and public project can be separately rolled back to earlier commits. (Just remember to commit the modified reference updates to the main module!) Branch work is easier - Changing branches in our source project will not change branches in our subproject (and vice versa). This is another nice safety buffer, and it gives us more options for branching in either module. Ready for site staging - We can easily create development branches in the public submodule that could be served as development subdomains of our site and used for testing new features. Some Drawbacks Of course, it’s always wise to assess the risks of any setup, and there are many opinions on the ‘perfect system’ in the dev world - tell me about yours in the comments! To shine some light on the potential downsides of our submodule use, here are some of the concerns I’ve thought about. Juggling multiple repos - With more submodules comes more administration. It doesn’t seem so rough for me, but right now I’m working on my own. Running interlinked, asynchronous repositories comes with its own challenges in a team setting, particularly if someone forgets to push updated submodule references to the source. No site staging with Github Pages - While the public submodule can branch and easily store data used in a site staging system, Github Pages does not seem to support subdomains from different project branches. That’s more of a Github Pages drawback, but it means we can’t take full advantage of our setup just yet. Another hosting platform might offer a solution - I’ll be looking into some options in a future post. ([View Highlight](https://instapaper.com/read/1368373249/14828355)) - Look at it this way - directly cloning a theme into our project has two major problems. We can’t push our commits to the theme’s source repo, because we don’t have permission. This means we can’t make changes to the theme and then keep them versioned. A cloned project in a subdirectory isn’t linked with the main project. When a submodule is added to a project, the main project adds a reference to it in a file named .gitmodules. Without that reference, the main project and the theme project aren’t connected, which could cause confusion or problems down the line. Also, Git doesn’t allow repos inside repos that aren’t submodules. See this ‘simple dev’ post for details. ([View Highlight](https://instapaper.com/read/1368373249/14828362))