- "Middleman is a static site generator using all the shortcuts and tools in modern web development."---Middleman Home Page
One of those shortcuts is having a directory structure to help organize your project. Here's a short version of that directory structure (a more complete version is located in the docs).
mymiddlemansite/
-- .gitignore
-- Gemfile
-- Gemfile.lock
-- config.rb
-- source (all the files necessary for building the static site)
-- build (the generated static site files)
The idea is that you would write all your code in the source directory, type in bundle exec middleman build to generate your build directory, and then ship this build directory elsewhere to be served by a web server. Most likely, you would use a tool such as middleman-deploy or middleman-gh-pages to automate the deployment process. Both of these tools are able to natively support deploying to GitHub Pages, usually by pushing up the build directory to the gh-pages branch of a GitHub repository.
But what if you don't want to use those tools to deploy to a separate branch of your repository? What if you wanted your website files to be in the same branch as your Middleman source code, for maintainability and aesthetic reasons? GitHub Pages luckily gives you that option...though in a rather indirect and hacky fashion.
In the settings of your GitHub repository, you tell GitHub Pages to read from either the gh-pages branch, the master branch, or the /docs folder.
The last option is incredibly useful for open-source projects who wants a specific /docs folder to store all their documentation files for their projects. For example, the Classifier-Reborn open source project has a GitHub Page, and its source code is stored within the /docs folder.
So we're going to abuse this feature to deploy our own Middleman site. First, we need to select the master branch /docs folder option in the settings of our repo. Second, we need to rename /build to /docs. This can be done by editing config.rb to change the build directory's name.
configure :build do
set :build_dir, 'docs'
end
Finally, we just type out...
bundle exec middleman build
...commit the resulting build folder to our repository, and then push the result up to our GitHub repository.
There is still one tiny flaw though. Any time you need to make a change, you must rebuild the /docs directory and commit the generated files. I leave it to the reader to decide how to best automate this process (probably by writing out a Raketask).
Top comments (2)
neat! I just used this trick. It's really useful for demo sites. But keep in mind that files won't be in the root but in a directory, eg: user.github.io/repo-name/ and that might cause some problems with links and assets.
Cool!
There's another trick I recently discovered as well that might help people avoid this problem in the future. If you don't want your files to be in a directory, you can create your own GitHub organization, which will have its own github.io domain (organization-name.github.io).
To use that github.io domain though, you will have to create a repo (organization-name.github.io) first. So while you're avoiding configuring and assets on Middleman, you will have to do some additional configuration on the GitHub site.