Getting Started
Middleman is a command-line tool for creating static websites using all the shortcuts and tools of the modern web development environment.
Middleman assumes familiarity with the command-line. The Ruby language and the Sinatra web framework form the base of the tool. Familiarity with both will go a long way in helping users understand why Middleman works the way it does.
Installation
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. Xcode can be installed via the Mac App Store. Alternately, if you have a free Apple Developer account, you can just install Command Line Tools for Xcode from their downloads page.
Once you have Ruby and RubyGems up and running, execute the following from the command line:
gem install middleman
This will install Middleman, its dependencies and the command-line tools for using Middleman.
The installation process will add one new command to your environment, with 3 useful features:
- middleman init
- middleman server
- middleman build
The uses of each of these commands will be covered below.
Starting a New Site: middleman init
To get started we will need to create a project folder for Middleman to work out of. You can do this using an existing folder or have Middleman create one for you using the middleman init
command.
Simply point the command at the folder for your new site and Middleman will build a skeleton project in that folder (or create the folder for you).
middleman init my_new_project
The Skeleton
Every new project creates a basic web development skeleton for you. This automates the construction of a hierarchy of folders and files that you can use in all of your projects.
A brand-new project will contain a source
folder and a config.rb
file. The source folder is where you will build your website. The skeleton project contains folders for javascript, css and images, but you can change these to match your own personal preferences.
The config.rb
file contains settings for Middleman and commented documentation on how to enable complex features such as compile-time compression and "blog mode."
Gemfile
Middleman will respect a Bundler Gemfile for locking down your gem dependencies. When creating a new project, Middleman will generate a Gemfile for you which specifies the same version of Middleman you are using. This will lock Middleman to this specific release series (the 2.x series, for example).
config.ru
A config.ru file describes how the site should be loaded by a Rack-enabled webserver. This file is provided as a convenience for users wishing to host their Middleman site in development mode on a Rack-based host such as Heroku.
To include a boilerplate config.ru
file in your project, add the --rack
flag to the init command:
middleman init my_new_project --rack
Project Templates
In addition to the default basic skeleton, Middleman comes with an optional project template based on the HTML5 Boilerplate project. Alternative templates can be accessed using the -t
or --template
command-line flags. For example, to start a new project based on HTML5 Boilerplate, run this command:
middleman init my_new_boilerplate_project --template=html5
Finally, you can create your own custom template skeletons by creating folders in the ~/.middleman/
folder. For example, I can create a folder at ~/.middleman/mobile/
and fill it with files I intend to use on mobile projects.
If you run middleman init with the help flag, you will see a list of all the possible templates it has detected:
middleman init --help
This will list my custom mobile framework and I can create new projects based on it as before:
middleman init my_new_mobile_project --template=mobile
There are also a number of community-developed project templates.
The Development Cycle (middleman server)
The Middleman separates your development and production code from the start. This allows you to utilize a bevy of tools (such as HAML, SASS, etc) during development that are unnecessary or undesirable in production. We refer to these environments as The Development Cycle and the Static Site.
The vast majority of time spent using Middleman will be in the Development Cycle.
From the command-line, start the preview web-server from inside your project folder:
cd my_project
bundle exec middleman server
This will start a local web server running at: localhost:4567/
You can create and edit files in the source
folder and see the changes reflected on the preview web-server.
You can stop the preview server from the command-line using CTRL-C.
Unadorned middleman command
Running middleman
without any commands is the same as starting a server.
bundle exec middleman
This will do exactly the same thing as middleman server
.
When something goes wrong
Under some circumstances(one known case is under Windows, see here), middleman
might not work as expected, try using a full command instead:
middleman server -p 4567 -e development
Under some circumstances(say if your config file has gone wild), middleman server might not be able to boot itself, and no error output can be seen on the console, don't panic, just try middleman build
to see the full trace of the problem and fix it.
Exporting the Static Site (middleman build)
Finally, when you are ready to deliver static code or, in the case of "blog mode", host a static blog, you will need to build the site. Using the command-line, from the project folder, run middleman build
:
cd my_project
bundle exec middleman build
This will create a static file for each file located in your source
folder. Template files will be compiled, static files will be copied and any enabled build-time features (such as compression) will be executed. You can pass a --clean
flag to middleman build
to have it clean out any files from the build directory that are left over from earlier builds but would no longer be produced.