How to deploy a Middleman site to GitHub user page

Question

I'm trying to deploy a Middleman project to my GitHub user page ([username].github.io). I'm using the middleman-gh-pages gem, and the instructions seem simple enough.

However, after running bundle exec rake publish, my GitHub user page still shows a 404. I see the build on GH, and it's on the 'gh-pages' branch.

Here is my directory structure on master after publishing.

Here is my directory structure on the gh-pages branch after publishing.

When I navigate to [username].github.io/source/index.html.haml, my browser downloads the haml file. It seems like my gh-pages branch is not what's actually being served up. Has anyone else encountered this problem? How can I make it so the gh-pages branch is what is served when I go to my GitHub user page?

Answer 1

i see this question is already resolved, but i'm still gonna put my two cents.

How to deploy a Middleman project to Github Pages manually

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. It's not hard to figure out!

Project configuration

config.rb

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:

activate :relative_assets
set :relative_links, true

Don't forget to use the link_to helper for internal links, don't write <a href... manually.

.gitignore

Make sure that your .gitignore file lists the build folder. If it doesn't, add it:

/build/

.nojekyll

Github Pages use the Jekyll preprocessor that might interfere with your static website. To disable Jekyll magic, create a blank .nojekyll file under source/.

From your project root:

touch source/.nojekyll

Repo preparation

You have to do this routine once.

1. Publish your project on Github.

2. Change into the build/ directory. If you don't have it in your project, either create it manually or build your project with bundle exec middleman build.

   cd build/
   

3. Init an empty git repo:

   git init .
   

4. Add your Github repo as a remote:

   git remote add origin [email protected]
   

5. Start a new branch gh-pages:

   git checkout --orphan gh-pages
   

Deployment routine

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.

1. Build your project.

   Starting at the project root:

   bundle exec middleman build
   

2. Change into the build directory:

   cd build/
   

3. Add all files:

   git add -A
   

4. 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
   

5. Push them to Github:

   git push origin gh-pages
   

   During the first push, add -u:

   git push -u origin gh-pages
   

---

Note that Github Pages take time for your website to show up. They say ten minutes but it might take hours. Be patient, though there's always a chance that you messed something up. :)

Subsequent pushes should be immediate. If a push is not reflected on you website, try bumping it with a subsequent push.

Answer 2

A username.github.io aka a user/organisation site is supposed to be pushed in master branch.

middleman-gh-pages gem seems to only push in gh-pages (see publish task here) which is the branch for project pages (username.github.io/projectName).