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?
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.
- 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
- Host free
- 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 middlemanis 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
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:
- Set up repo remotely by heading back to terminal in project base run
git remote add origin firstname.lastname@example.org:USERNAME/REPONAME
- Can always run
git repo -vto 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
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
- Add one line of code:
- This is only required because we have set up a CNAME to use a custom domain
- Add one line of code:
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.
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
git checkout master
git merge NEW
Now run the Middleman build command:
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
cd build it
Add all those files:
git add .
git commit -m build
And finally Push:
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.
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:
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
A quick note if you have never worked with a file structure that has a
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!