/www Using a gh-pages BranchNote: These instructions are not quite complete. It’s probably easiest to do this for a new repo where you have no ./www folder to start. I’m leaving it here so that I can work on it in the future, but it is not 100% worked out.
The easiest solution to this problem is to use the /docs folder or a separate branch instead, since Github supports both options out of the box. If you don’t need Jekyll builds I have another article that covers using Github Actions to serve static content from the www folder.
This guide walks through setting up a GitHub Pages site from the /www directory in your repository. We will:
gh-pages branch/www into it for deploymentgit deploy) to automate updatesgh-pages BranchGitHub Pages serves content from a branch called gh-pages. We need to create and configure it.
gh-pages branchRun the following in your repository root:
git checkout --orphan gh-pages
Since this branch starts with all your main files, remove them (we only want /www here). I don’t want to give you destructive commands, so I’m going to leave the deleting as an action for the reader.
GitHub Pages requires files at the root of the gh-pages branch. Move everything from /www:
mv www/* .
Now, delete the www folder. Again, I’m going to leave this as an action for the reader.
git add .
git commit -m "Initial GitHub Pages setup"
git push -u origin gh-pages
Now that gh-pages is set up, enable it in your repository.
We will create a Git alias of git deploy that:
/www folder to gh-pagesRun this command inside your repository:
git config alias.deploy '!git push origin main && git subtree push --prefix www origin gh-pages'
Check that the alias was set correctly:
git config --get alias.deploy
It should return:
!git push origin main && git subtree push --prefix www origin gh-pages
Switch back to your main branch.
git checkout main
Now, whenever you update your site, just run:
git deploy
This will:
Your site will now update automatically whenever you run git deploy.
Enjoy your streamlined GitHub Pages workflow!
This Markdown version is ready to be published on your website! Let me know if you’d like any tweaks.
I used AI to help write this article. It’s a tool I use in a lot of my work.
Originally I was working with an AI chat bot to help me deploy a site from the www folder on Github. I was using some of my old instructions that were’nt working because of some differences for my new deployment. From that synthetic conversation I learned about the strategy of using a sub module for the www folder and I learned about git aliases.
I usually write for my future self, and this article is no different. I gave AI a few instructions for what I wanted the article to contain and I let it ghost write most of it for me. I then saved it as this post and followed them myself. But, the AI didn’t get everything right. Worse still, it had included some very destructive instructions.
I followed the instructions carefully and manually adjusted them where I saw problems. As I edited my own writing and that of the AI became more and more blurred.
Written by Joel Dare with the help of an AI on March 17, 2025.
Get a monthly digest of what I'm up to.