Middleman: a Ruby static site generator for hand-written frontends

The problem Middleman solves for hand-written frontends

The README frames the target user directly: a front-end built to stand alone, deployed to a CDN or handed to a client as static HTML, JS and CSS. The pitch is that a site can be built and deployed independently of the backend, using a public API to pull data. That is a familiar argument, but Middleman's version of it is narrower than the modern JavaScript static-site field. It is a Ruby gem, and the templating it advertises is ERb or Haml, not JSX or a component framework.

The audience is therefore a developer who is already comfortable in Ruby and wants the generator to be a library in that ecosystem rather than a separate runtime. The README lists Sass for stylesheets and explicitly says you bring your own asset pipeline, naming WebPack, Babel and Sprockets as examples. So Middleman does not try to own bundling. It owns the page compilation step and leaves JavaScript tooling to whatever you already run.

That division is the whole design argument. If you want one tool that compiles templates, bundles JavaScript and manages dependencies, Middleman is not that. If you want a Ruby-native page compiler and are happy to run your own bundler beside it, the split is reasonable.

How the source directory, config.rb and extension-based templating fit together

A Middleman project has two parts named in the README: a config.rb file for configuration and a source directory holding pages, stylesheets, javascripts and images. The build reads from source and writes a stand-alone site. The preview server watches the same directory so edits appear in the browser.

The templating mechanism is file extension based. The README gives the concrete case: a stylesheet at source/stylesheets/site.css becomes source/stylesheets/site.css.scss and Middleman begins processing it as Sass. The same rule applies to CoffeeScript as .js.coffee and Haml as .html.haml. So the pipeline is driven by naming, not by an explicit registry in config.rb. You opt a file into an engine by appending that engine's extension.

That is a small design decision with real consequences. It means adding a template language is a rename, and it also means a typo in an extension silently produces a file that is copied rather than compiled. The README states that the build step can also compress images, manage JavaScript and CSS dependencies, minify JavaScript and CSS, and run additional code of your choice, and it points at config.rb to see which extensions can be activated. The README does not enumerate those extensions itself, so the authoritative list is the config file in a generated project and the material on the official website.

The repository is split into middleman-cli, middleman-core and middleman directories at the top level. The README does not describe that split, but the layout is consistent with a CLI layer over a core library, which matters if you intend to call Middleman programmatically rather than through the command line.

Installing Middleman and running a first build

Middleman is built on Ruby and installs through RubyGems. The README says Ruby and RubyGems are usually pre-installed on macOS and Linux; Windows users need RubyInstaller, and the README states that RubyInstaller-Devkit is also required on Windows. The install is a single gem command.

 gem install middleman

After that the middleman command is available. Scaffolding a project is the next step, and the README uses MY_PROJECT as the placeholder name.

 middleman init MY_PROJECT

That creates a directory containing config.rb and the source directory. Move into it and start the preview server.

 cd MY_PROJECT
 middleman server

The README states the preview is served at http://localhost:4567/. Edit files under source and the browser reflects the change. To convert a stylesheet to Sass, rename it so the extension becomes .css.scss, for example source/stylesheets/site.css to source/stylesheets/site.css.scss, and Middleman processes it as Sass without further configuration.

When the site is ready, build it. The README says this compiles templates and outputs a stand-alone site that can be hosted or delivered.

 middleman build

If you want to work on Middleman itself rather than use it, the README gives a separate path: clone the repository, install Bundler with gem install bundler, run bundle install in the project root, then run the test suite.

 bundle exec rake test

Where Middleman is the wrong tool

The clearest limitation is the runtime dependency. Everything starts with a Ruby gem install, and on Windows the README adds a second requirement in RubyInstaller-Devkit. A team that ships frontends from a Node-only environment pays a real cost here: a second language runtime on every machine and in every build image, for a step that other tools do in the runtime they already have.

The asset pipeline is deliberately not included. The README says to bring your own, naming WebPack, Babel and Sprockets. That is a fair boundary, but it means Middleman does not solve dependency management, code splitting or module resolution. You configure that elsewhere, and you own the integration between the two systems.

Extension-based templating is convenient until it is not. Because the engine is chosen by the file extension, there is no central list in the README of which engines are wired up. The README points to config.rb and to the website. A reader who wants a definitive supported-engine matrix will not find it in the repository README.

Finally, the README is silent on rollback, incremental build behaviour and how the preview server handles a failing template. Those are exactly the questions that decide whether a generator is pleasant on a large site, and the README does not answer them. Treat that silence as something to test yourself before committing a big project to it.

Middleman against Jekyll and the JavaScript site generators

Jekyll is the closest comparison in the Ruby world, and the difference is not the language but the templating and the asset story. Jekyll is built around Markdown and Liquid, which suits content-heavy blogs where most pages come from files with front matter. Middleman's README leads with ERb and Haml and with Sass, which points at hand-authored pages and stylesheets rather than a document pipeline. If your site is mostly prose in Markdown, Jekyll's defaults fit with less configuration. If your site is mostly layouts and styles you write yourself, Middleman's defaults fit better.

Against the JavaScript generators, the difference is the runtime and the pipeline. A Node-based generator keeps templates and bundling in one toolchain. Middleman keeps page compilation in Ruby and hands bundling to WebPack, Babel or Sprockets. That is a genuine architectural split, not a cosmetic one: it decides which language your build scripts are written in and what has to be installed in CI.

Middleman's other distinguishing choice is the extension rename. Jekyll uses a front matter block and Liquid tags inside files; Middleman uses the filename to select the engine. The rename approach is less visible in the file body and easier to get wrong, since nothing in the file content declares the engine.

Maintenance, versions and the MIT licence

The repository is not archived and the last push was on 2026-08-24, so the codebase is being touched. The README does not include a release history, and no recent releases were retrieved, so there is no changelog detail here to judge the pace of change. The CHANGELOG.md file exists at the top level and is the place to look for version-by-version detail.

On versioning, the README states the project aims to follow Semantic Versioning 2.0.0 and treats violations as bugs. It says breaking changes to the public API are introduced only in new major versions, and it recommends pinning with a pessimistic constraint at two digits of precision, giving this example.

 gem 'middleman', '~> 4.0'

The practical upgrade cost follows from that: within a major version you should not expect breaking API changes, and a major bump is where you plan migration work. The README does not describe a deprecation policy or a support window for older majors, so the CHANGELOG is the source for what actually changed.

The licence is MIT, stated in the README and in LICENSE.md, with copyright attributed to Thomas Reynolds for 2010-2023. MIT is permissive and imposes no copyleft obligation on the sites you generate. That is a general property of the licence, not legal advice; if your organisation has specific compliance requirements, the LICENSE.md file is the document to read.

Editorial conclusion

Adopt Middleman if you write templates by hand in ERb or Haml and want the build to stay a Ruby gem rather than a Node toolchain. Skip it if your team has no Ruby and no appetite for installing it, or if you need a plugin ecosystem with a large third-party catalogue, since the README points only to the official website, RubyDoc and the forum for extensions. Before committing, run middleman init in a scratch directory, confirm the preview server answers on http://localhost:4567/, and check whether config.rb exposes the asset pipeline hooks your project needs.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. middleman/middleman on GitHub
4. Project website
5. README