This is based on this answer on stackoverflow but changed to allow both a 'in progress' public website and a 'development website', both publicly available.
Note: this guide describes how to deploy a project website, (e. g. username.github.io/projectname). If you're deploying a user website (e. g. username.github.io), you'll need to adjust some options.
Github Pages will serve your project website from a subfolder. This means that you can't reference your pages and assets with absolute URLs. Tell Middleman to use relative URLs.
Also you are going to change the build dir to be gh-pages/dev (this is so you can have gh-pages be the 'in progress' public website and gh-pages/dev be the development website where people can go to check your latest progress):
activate :relative_assets
set :relative_links, true
set :build_dir, 'gh-pages/dev'
Don't forget to use the link_to helper for internal links, don't write <a href... manually.
Make sure that your .gitignore file lists the build folder. If it doesn't, add it:
# build folder for middleman
/gh-pages/
You have to do this routine once.
- Publish your project on Github.
- Change into the
gh-pages/directory:cd gh-pages/ - If you don't have it in your project, either create it manually or build your project with
middleman build. - Init an empty git repo:
git init - Add your Github repo as a remote:
git remote add origin git@github...git - Start a new branch
gh-pages:git checkout --orphan gh-pages
You'll have to repeat the following steps every time you deploy an update. Consider adding them to a batch file so that you don't have to repeat them manually.
- Build your project. Starting at the project root:
middleman build - Change into the build directory:
cd gh-pages/ - Add all files:
git add -A - Commit them. You don't really need a meaningful commit message here because your commit history is stored in your project's main branch. There's no big need to duplicate it here:
git commit -m build - Push them to Github:
git push origin gh-pages
Bonus: During the first push, add -u: git push -u origin gh-pages
Just put your static html in the gh-pages folder. The directory structure will be something like this:
(project-root)
|-- * (middleman config files)
|-- source
| |-- * (middleman source files)
|-- gh-pages
| |-- * (your static html for the 'public' website)
| |-- dev
| |-- * (the html generated by middleman, the bleeding edge version)
Removing the files in gh-pages (using zsh)
rm -r ./gh-pages/*
middleman build
cp -r ./gh-pages/dev/* ./gh-pages/
Note that Github Pages take time for your website to show up.
Subsequent pushes should be immediate. If a push is not reflected on you website, try bumping it with another commit + push.
For those wondering why would I want to do this, I wanted to develop a static html website on github, having both a landing page where visitors would see a countdown to launch and a development page (on /dev) that people who knew about that page could use to give me feedback on the actual site that was being developed.