Middleman Blog with GitHub Pages
Middleman is a static site generation framework with an available blog extension package. I’ve tried to set up a blog with Middleman in the past, but I’ve always had trouble with deploying to GitHub pages. To me it’s not as straight forward as it could be, but I think with a few tips it can easily be done. Here are the steps that worked for me.
Start off by creating a new Middleman Blog, change into the new directory and initialize a new git repo.
1 2 3 $ middleman init snsavage.github.io --template=blog $ cd snsavage.github.io/ $ git init
GitHub Pages uses two different conventions depending on whether the pages are for a user, organization or a project. User pages are created in a GitHub repo with a
username.github.io naming scheme and are served using files on the
master branch of that repo. Project pages on the other hand use the
http(s)://<username>.github.io/<projectname> naming scheme and are served from the
gh-pages branch. Here are the instructions for setting up your GitHub Pages repo and more detail on page types and naming conventions.
After you have setup your GitHub repo, don’t forget to add the remote to your local repo.
1 $ git remote add origin https://github.com/snsavage/snsavage.github.io.git
Because GitHub Pages use the
master branch for deploying your site, you’ll need to create a new branch for developing your site. Understanding how this branch structure works with GitHub Pages is extremely important. This is what caused most of my headaches.
Create a new branch called
development, add the files to the repo and then commit the changes.
1 2 3 $ git checkout -b development $ git add . $ git commit -a -m "Initial Middleman Blog Setup"
At this point your site should only have a
development branch. Nothing was committed to the original
master branch before creating the
development branch. During my setup I created the
master branch and tested adding a file to that branch. More information on manually creating pages can be found here.
First, create the new
master branch as an orphan branch. Then remove all files from that branch. I also had to remove a directory that remained behind.
1 2 3 $ git checkout --orphan master $ git rm -rf . $ rm -rf source
Second, create an index.html file, add the file to the repo, commit the file and push to
origin. As noted earlier, more on these steps can be found here.
1 2 3 4 $ echo "My Page" > index.html $ git add index.html $ git commit -a -m "First pages commit" $ git push origin master
At this point your website should be live with the sample
index.html page. Your web address will be
<username>.github.io. But now that you know that isn’t working, it’s time to finish setting up Middleman. Start by removing the
1 $ git rm index.html
Now it’s time to head back to the
development branch to finish the Middleman setup.
1 $ git checkout development
I used the Middleman Deploy extension to handle deploying to GitHub Pages. The following instructions can be found here. As of this writing there is a typo in the Middleman Deploy
README.md. I’ve noted it below.
Add to your Gemfile.
1 gem 'middleman-deploy', '~> 1.0'
Add the following lines to your
1 2 3 4 5 activate :deploy do |deploy| deploy.method = :git # This is shown as deploy.deploy_method in the README. deploy.remote = "origin" deploy.branch = "master" end
Build and deploy your blog.
1 2 $ middleman build $ middleman deploy
This is the process that worked for me. Please let me know if you have any feedback.