In simple terms, Middleman or any static site generator produces static website, made of HTML, CSS and Java Script files, which can be uploaded to any static host or served from any normal web server. Static, informational, one-way broadcast content sites are often called "brochureware" and are ideal for blogs, curriculum vitae, portfolios, etc.
Middleman is a library for creating static websites written in Ruby, which utilizes some of the power of Rails (the popular Ruby web framework). An easy to use framework, Middleman allows you to build static websites with modern workflows in mind and with a high degree of developer productivity.
Middleman is distributed using the RubyGems package manager. This means you will need both the Ruby language runtime installed and RubyGems to begin using Middleman.
Mac OS X comes prepackaged with both Ruby and RubyGems, however, some of the Middleman's dependencies need to be compiled during installation and on OS X that requires Xcode Command Line Tools. Xcode can be installed from the terminal:
$ xcode-select --installOnce you have Ruby and RubyGems up and running, execute the following from the command line:
$ gem install middlemanIf all has gone well, you should be able to run
$ middleman versionAnd see something like Middleman 4.0.0 (the latest version).
To get started we will need to create a project folder for Middleman to work out of. Run (inside the current directory you're in)
$ middleman init my\_first\_projectEvery new project creates a basic web development skeleton for you. This automates the construction
of a standard hierarchy of folders and files that you can use in all of your projects. If you change
into this directory**($ cd my-first)**and take a look at the files Middleman has generated,
you'll see
- config.rb,
- config.ru,
- Gemfile,
- Gemfile.lock
- a 'source' folder
The config.rb file which configures how middleman generates the site and contains commented documentation on how to enable complex features such as compile-time compression and "blog mode". In addition, any extensions you might activate are configured in config.rb.
A config.ru file describes how the site should be loaded by a Rack-enabled webserver.
The Gemfile controls which bits and pieces get loaded into a middleman project. Any gems that you need for a project to build should be added.
Gemfile.lock is a snapshot of all of the gems and versions installed by the bundler with *reference to Gemfile.
The 'source' folder is where you will build your website. This completely self-contained source folder has 'index.html.erb' – which is the index page of the site. At this point, it important to know that Middleman uses ERB for templates (hence the .erb extensions). For an introduction to ERB templating, see this article. The source folder also has folders for javascript, CSS, layout and images, but you can change these to match your own personal preferences.
This is the typical structure and content of a new Middleman project:
|-config.rb
|-config.ru
|-Gemfile
|-source
| |-images
| | |-background.png
| | |-middleman.png
| |-index.html.erb
| |-javascripts
| | |-all.js
| |-layouts
| | |-layout.erb
| |-stylesheets
| | |-all.css
| | |-normalize.css
Middleman will have generated a Bundler Gemfile as part of the generation of the skeleton project.
Run Bundler to install the Gems that are part of your new Middleman project:
bundle
Middleman has two "modes": development and static.
The ultimate goal is to generate static content and deploy it to a bare-bones web server or basic hosting service.
When you're developing your content, you typically want to look at the changes you're making as you make them. Generating static content each time you make a change would slow down your development work.
Middleman provides a development server that you can use to view the content you're working on without having to go through the static generation cycle.
Start the development server:
bundle exec middleman
The server will be listening on your local host on port 4567.
Open a web browser and navigate to: http://localhost:4567
You will see the Middleman place holder page.
To stop the development server, return to the terminal window where it's running and press CTRL+C.
Ok so what's actually happening here? Well, Middleman is compiling the site with the layout in the
layout.erb file and then loading in the index.html.erb file into this layout dynamically.