Live Static Sites with Middleman, Github Pages, and Proteus
For as many reasons as there are to need a static site there are just as many options to build and host that site with. Staticgen.com alone has a list of 130 Top Open-Source Static Site Generators.So how do you choose?This post will quickly go over why Middleman, Github Pages, and Proteus are a great combination for creating and hosting static sites.
September 21, 2016
Using Static Sites
No matter how long you have been developing it’s only a matter of time before someone asks you to build a simple static website.
Maybe it’s a portfolio page you want to build out, a new company website, or a even a quick way to prototype.
For as many reasons as there are to need a static site there are just as many options to build and host that site with. Staticgen.com alone has a list of 130 Top Open-Source Static Site Generators.
Middleman is a Ruby Framework that quickly builds static websites using shortcuts and tools in modern web development. In other words it’s built on top of tools that you are most likely using elsewhere, making understanding a breeze.
Ruby based Framework. Being comfortable with Ruby on Rails this will feel natural.
Plays nice with github-pages which allows you to host directly from your Github repository.
Has great documentation.
Quick & Simple
Uses same tools and languages you use everyday.
What is Github Pages
Github Pages is a way to host a website directly from your Github repository without any additional hosting packages or costs. Just edit, push, and your changes are live.
Why Github Pages
Popularity of Github means the familiarity
Has great documentation
No new tools to learn
What is Proteus
Proteus is collection of starter kits. This is definitely an optional component but it can help create a middleman project quickly with preset configurations out of the box. (Not for all)
Above all else, it’s ready to go out of the box
Now that you have a high level overview of what Middleman, Github Pages and Proteus are, I’ll show you the way to get a site up and running fast.
Getting Middleman installed.
Using RubyGems package manager gem install proteus-kits
This is going to give you a pre configured middleman app when creating a new project that for me is out of the box ready to go. gem install middleman is all that is needed but then you have to configure from a bare project. Here’s a quick overview of what both options look like out of the box.
Using middleman gem
middleman new PROJECTNAME
Using proteus-kits gem
proteus new middleman PROJECTNAME
As you can tell out of the box you get a lot more with Proteus. Like anything, this might not be best fit for your skills and knowledge (Haml, SASS, etc.), but it can all be configured as well.
Moving forward I’m only showing the Middleman project built with Proteus.
Fastest path to live
Change to the newly created project cd PROJECTNAME run proteus setup. This will install all dependencies and gems in gemfile. This project is by default using git so no need to git init
Now bringing Github Pages into the picture, I’m going to map this site to a custom domain so in the end it will be reachable at www.SITENAME.com. This means you have a registered domain name somewhere. Not necessary but always nice to use a custom domain. If this is skipped, your site would still be live on the web just under http://GITHUBUSERNAME.github.io
For this example, we are creating a User Pages Site.
There are a few different options for Github Pages:
Create a new repository: GITHUB_USERNAME.github.io
Set up repo remotely by heading back to terminal in project base run
Can always run git repo -v to make sure it is set up correctly
Using a custom domain is simple. Go to a Domain Registrar if you don’t already have one and purchase what you want. $9/year is pretty standard. Find the DNS Records for that domain and add a CNAME.
It should look something like this:
Make sure you fill in the host name with www.SITENAME.com. The Answer would be the name of your repo, and also remember to add a second CNAME without www. so that your site will be accessible either way with or without the prefix.
Now that you are set up with your repo and have set up your CNAME to use your custom domain, you can actually start building and deploying your site.
Add a file CNAME in source/ directory.
Add one line of code: www.SITENAME.com
This is only required because we have set up a CNAME to use a custom domain
Edit config.rb file
Add deploy.branch = 'master' after line 25.
Should look like: ruby # config.rb activate :deploy do |deploy| deploy.build_before = true deploy.deploy_method = :git deploy.branch = 'master' end That is all you need to configure your site and get your site running.
Now you just need to get a git workflow setup. Since Github pages is going to use master for our User Page Site, we need to make another branch to work off of. bash git checkout -b NEW git add . git commit -m 'Initial Commit' git push -u origin NEW
This is going to allow you to keep your source/ directory and make changes as you build out your site. Always push here when making changes before builds.
After, push the change back to master bash git checkout master git merge NEW git push
Now run the Middleman build command: bash bundle exec middleman build
If it ran correctly, you will see a message on the screen that says “Project built successfully”
Now you can change into the build directory: bash cd build it
Add all those files: bash git add .
Commit: bash git commit -m build
And finally Push: bash git push -u origin master
Note: you are pushing from within the build directory.
Your site should be live and be found at your custom domain. www.sitename.com
By adding one file (only if you are adding a CNAME to have your site live at a custom domain) and two lines of code, you are configured to build and push live. How simple is that?
Middleman gives you the ability to serve your site locally by running: middleman serve
This will put your site live at localhost:4567 and with the configured app that we build, auto-reload will be enabled so every time a file is changed your changes will automatically be updated. This gives you a quick working environment to see how your site will look after a build.
A quick note if you have never worked with a file structure that has a source and build directory.
You will ALWAYS work within the source directory. The build directory changes every time build is run based on what is within the source directory so if you find yourself working in the build directory you are going to be fighting a battle you can’t win.
Reference Middleman Docs to find out how everything plays together if you get caught-up, but this should get you up and running very quickly for free. This will help you spend more time building and not worrying about how to get a site live.
Enjoy! And the remember you only grow when you are pushed outside your comfort zone, so try something new!
Actionable UX audit kit
Guide with Checklist
UX Audit Template for Figma
UX Audit Report Template for Figma
By filling out this form you agree to receive our super helpful design newsletter and announcements from the Headway design crew.
Building Self-Service Web Pages in Contentful with GatsbyJS