Live Static Sites with Middleman, Github Pages, and Proteus

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.

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.

‍

What is Middleman

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.

Why Middleman

1. Ruby based Framework. Being comfortable with Ruby on Rails this will feel natural.
2. Plays nice with github-pages which allows you to host directly from your Github repository.
3. Has great documentation.
4. Quick & Simple
5. 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

1. Popularity of Github means the familiarity
2. Host free
3. Has great documentation
4. 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)

Why Proteus

Above all else, it’s ready to go out of the box

‍

Start building

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.

1. Getting Middleman installed.
2. Using RubyGems package manager
   gem install proteus-kits
3. 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

‍

On Github

For this example, we are creating a User Pages Site.

There are a few different options for Github Pages:

For Reference

1. Create a new repository: GITHUB_USERNAME.github.io
2. Set up repo remotely by heading back to terminal in project base run
3. git remote add origin git@github.com:USERNAME/REPONAME
4. Can always run git repo -v to make sure it is set up correctly

Custom Domain

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.

Project setup

1. Add a file CNAME in source/ directory.
2. Add one line of code: www.SITENAME.com
3. This is only required because we have set up a CNAME to use a custom domain
4. Edit config.rb file
5. Add deploy.branch = 'master' after line 25.
6. 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.

‍

That’s it!

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!