Easy deployment of Middleman sites to Github Pages
Easy deployment of Middleman sites to Github Pages
Middleman makes creating static sites a joy, Github Pages hosts static sites for free, Middleman Github Pages brings the two together. Middleman Github Pages is just a few rake tasks that automate the process of deploying a Middleman site to Github Pages.
Add this line to your Gemfile:
gem 'middleman-gh-pages'You'll also need to require the gem in your Rakefile:
require 'middleman-gh-pages'Middleman Github Pages provides the following rake tasks:
rake build # Compile all files into the build directory
rake publish # Build and publish to Github PagesThe only assumption is that you are deploying to a gh-pages branch in the same
remote as the source. rake publish will create this branch for you if it
doesn't exist.
ALLOW_DIRTYYou cannot deploy your site if you have uncommitted changes, but you can
override this (default: nil):
bundle exec rake publish ALLOW_DIRTY=trueCOMMIT_MESSAGE_SUFFIXYou can append a custom suffix to commit messages on the build branch
(default: nil):
bundle exec rake publish COMMIT_MESSAGE_SUFFIX="[skip-ci]"REMOTE_NAMEYou can change the remote that you deploy to (default: origin):
bundle exec rake publish REMOTE_NAME=upstreamBRANCH_NAMEIf you're publishing a personal or organization page, you may want to use the
branch master instead of gh-pages (default: gh-pages):
bundle exec rake publish BRANCH_NAME=masterPROJECT_ROOTIf your middleman project isn't at the root of your repository, you will likely need to change this (default: root of git repository):
bundle exec rake publish PROJECT_ROOT=/Users/me/projects/repo/wwwBUILD_DIRIf you override the default middlemant :build_dir setting, you will likely
also need to set this variable (default: /build):
bundle exec rake publish BUILD_DIR=/some/custom/path/to/publicOf course, for more permanent settings, you can always set these environment
variables directly in your Rakefile instead of from the command line.
require "middleman-gh-pages"
# Ensure builds are skipped when publishing to the gh-pages branch
ENV["COMMIT_MESSAGE_SUFFIX"] = "[skip ci]"
# Ignore errors about dirty builds (not recommended)
ENV["ALLOW_DIRTY"] = "true"To set up a custom domain, you can follow the GitHub help page.
NOTE You will need to put your CNAME file in the source directory of your middleman project, NOT in its root directory. This will result in the CNAME file being in the root of the generated static site in your gh-pages branch.
Since project pages deploy to a subdirectory, assets and page paths are relative to the organization or user that owns the repo. If you're treating the project pages as a standalone site, you can tell Middleman to generate relative paths for assets and links with these settings in the build configuration in config.rb
activate :relative_assets
set :relative_links, trueNOTE This only affects sites being accessed at the username.github.io/projectname URL, not when accessed at a custom CNAME.
git checkout -b my-new-feature)git commit -am 'Add some feature')git push origin my-new-feature)No open issues yet, or sync has not completed.