middleman / middlemanapp.com

Documentation for Middleman

Middleman - Makes developing websites simple

Middleman is a static site generator using all the shortcuts and tools in modern web development. Check out middlemanapp.com for detailed tutorials, including a getting started guide.

Why Middleman?

These days, many websites are built with an API in mind. Rather than package the frontend and the backend together, both can be built and deployed independently using the public API to pull data from the backend and display it on the frontend. Static websites are incredibly fast and require very little RAM. A front-end built to stand-alone can be deployed directly to the cloud or a CDN. Many designers and developers simply deliver static HTML/JS/CSS to their clients.

• Uses Sass for DRY stylesheets.
• Bring your own asset pipeline (WebPack, Babel, Sprockets or any other).
• Easy templating with ERb or Haml.

Middleman gives the stand-alone developer access to all these tools and many, many more.

Installation

Middleman is built on Ruby and uses the RubyGems package manager for installation. These are usually pre-installed on Mac OS X and Linux. Windows users can install both using RubyInstaller. For windows RubyInstaller-Devkit is also required.

gem install middleman

Getting Started

Once Middleman is installed, you will have access to the middleman command. First, let's create a new project. From the terminal:

middleman init MY_PROJECT

This will create a new Middleman project located in the "MY_PROJECT" directory. This project contains a config.rb file for configuring Middleman and a source directory for storing your pages, stylesheets, javascripts and images.

Change directories into your new project and start the preview server:

cd MY_PROJECT
middleman server

The preview server allows you to build your site, by modifying the contents of the source directory, and see your changes reflected in the browser at: http://localhost:4567/

To get started, simply develop as you normally would by building HTML, CSS, and Javascript in the source directory. When you're ready to use more complex templates, simply add the templating engine's extension to the file and start writing in that format.

For example, say I am working on a stylesheet at source/stylesheets/site.css and I'd like to start using Compass and Sass. I would rename the file to source/stylesheets/site.css.scss and Middleman will automatically begin processing that file as Sass. The same would apply to CoffeeScript (.js.coffee), Haml (.html.haml) and any other templating engine you might want to use.

Finally, you will want to build your project into a stand-alone site. From the project directory:

middleman build

This will compile your templates and output a stand-alone site which can be easily hosted or delivered to your client. The build step can also compress images, employ Javascript & CSS dependency management, minify Javascript & CSS and run additional code of your choice. Take a look at the config.rb file to see some of the most common extensions which can be activated.

Learn More

A full set of in-depth instructional guides are available on the official website at: http://middlemanapp.com.

Additionally, up-to-date generated code documentation is available on RubyDoc.

Community

The official community forum is available at: http://forum.middlemanapp.com

Bug Reports

Github Issues are used for managing bug reports and feature requests. If you run into issues, please search the issues and submit new problems: https://github.com/middleman/middleman/issues

The best way to get quick responses to your issues and swift fixes to your bugs is to submit detailed bug reports, include test cases and respond to developer questions in a timely manner. Even better, if you know Ruby, you can submit Pull Requests containing Cucumber Features which describe how your feature should work or exploit the bug you are submitting.

How to Run Cucumber Tests

1. Checkout Repository: git clone https://github.com/middleman/middleman.git
2. Install Bundler: gem install bundler
3. Run bundle install inside the project root to install the gem dependencies.
4. Run test cases: bundle exec rake test

Donate

Click here to lend your support to Middleman

Versioning

This library aims to adhere to Semantic Versioning 2.0.0. Violations of this scheme should be reported as bugs. Specifically, if a minor or patch version is released that breaks backward compatibility, that version should be immediately yanked and/or a new version should be immediately released that restores compatibility. Breaking changes to the public API will only be introduced with new major versions. As a result of this policy, you can (and should) specify a dependency on this gem using the Pessimistic Version Constraint with two digits of precision. For example:

gem 'middleman', '~> 4.0'

License

Copyright (c) 2010-2023 Thomas Reynolds. MIT Licensed, see LICENSE for details.

middlemanapp.com's Issues

There is no license

The first thing I do when forking a repository is to check out whether I am allowed to do use this code for my purposes, or if bazillions of lawyers will descend on me if I do not publish every bit under the GPL. :)

README.md says:

Copyright (c) 2010 Thomas Reynolds. See LICENSE for details.

Unfortunately there is no file named LICENSE. Oops.

Document minify-html extension

Link from doc to edit the current page do not work

On this page http://middlemanapp.com/guides/dynamic-pages, the link "Fork and edit this guide on Github" do not work.

Server goes down intermittently

So, for some reason, my server works fine for a bit, but after I refresh the page too many times, it crashes. I can't even CTRL-C in Terminal to shut it down.

I'm using a pretty basic setup, with the html5 boilerplate template out of box.

Gemfile:

source :rubygems

gem "middleman", "~>3.0.4"
gem "therubyracer"
gem "less"

What's strange is that if I spin up a new instance on another port, it works great for a bit, then stops working and I can't even exit out of the console.

Any ideas?

Sticky Header Scrolling Janks on Docs

The above is reproduced by slowly scrolling down on the docs page. Looks like the sticky header is making the page's height to change, causing the scroll position to go back up. Rinse and repeat!

Some inconsistencies in the "sitemap" section

I saw some inconsistencies while using middleman 3.0.0.rc.1 and viewing beta.middlemanapp.com.

http://beta.middlemanapp.com/metadata/sitemap

Accessing the Sitemap

The sitemap is a repository of every page in your site, including HTML, CSS, JavaScript, images - everything. It also includes any dynamic pages you've created using :proxy. Within templates, sitemap gets you the sitemap object. From there, you can look at every page via the pages method or grab individual pages via page. You

• There is no pages method. Did you mean #resources?
• There is no page method as well.

Sitemap Pages

Each page in the sitemap is a Page object.

• It looks like each page is a Resource object. The link is dead, too.

ready do
sitemap.pages.group_by ...

• Maybe sitemap.resources?

Improve Anchor Link targeting

The current application of AnchorJS seems a bit broad, resulting in Anchor icons appearing in some places that don't make very much sense, like:

The home page subtitle:

Sidebar navigation:

It would be better to target the links only at the headings inside the articles, instead of sitewide.

Link to generated docs from guides

It'd be nice if the YARD docs were linked to from the guides, especially for people who want another reference for the helpers, extensions, and configuration options.

Promote Blogging to a top-level category

In the future, I hope this extension will merge/replace many users' need for Octopress. So let's flesh out the docs.

remove content_tag from helpers examples

Syntax <%= blah do %> doesn't work. See middleman/middleman#1250.

This example should be removed from the docs. http://middlemanapp.com/basics/helpers/

<%= content_tag :p, :class => "stuff" do %>
  Hello
<% end %>

Locales or Langs?

When rendering the page \ I get rendered index.html.erb with translation interpolated, however, when trying \es\index.html as shown in the docs it shows File not found.

What can cause the problem?

Building Guides Results in Unstyled Documentation

When I run the the middleman server, everything looks great. However, when I build it out so I can use it on the side as a static site while running server on my own project, the guides are unstyled.

partial not render

To render a partial, the guide instructs to use the "render" method, shouldn't this be the "partial" method?

Xcode Command Line Tools do not require developer account anymore

The information in https://github.com/middleman/middleman-guides/blame/master/source/basics/install.html.markdown#L15-L17 is outdated. (At least) since OS X 10.9 one can install the Command Line Tools without a Apple Developer account directly from the command line with:

xcode-select --install

This will display the following dialog:

Should we propose this mechanism as the default installation method for both Xcode and Command Line Tools? If yes, should we provide additional information for older systems?

Getting started makes multiple references to blog mode

Yet there is nowhere in the documentation where it says exactly what blog mode is, how it differs from non-blog mode and how one enables it.

Slim displays tags

Hi,
Slim template is not properly converting tags

when input this index.html.slim file

h1 Welcome
ul

• 5.times do |num|
  li Count #{num}

Using layouts/layouts/slim.slim
doctype 5
body
= yield

I get this when viewed on the web browser

<h1>Welcome</h1><ul><li>Count 0</li><li>Count 1</li><li>Count 2</li><li>Count 3</li><li>Count 4</li></ul>

I have slim required on the gem file.
And setting it as default template engine on config.rb make no difference.
Thanks
Tim

Redirect of old URL

google indexed link at old URL.
please old URL redirect at new URL.

If you do not know my words, it is wrong is my grammar.
Keyword is the [old URL] and [redirect].

Redirect of old URL

google indexed link at old URL.
please old URL redirect at new URL.

If you do not know my words, it is wrong is my grammar.
Keyword is the [old URL] and [redirect].

image folder not being included in the sprockets pipeline

sprockets (middleman-sprockets) seem to not to load any of my image assets (e.g. the image folder) when i'm running the server. it keeps on giving me a 404 in the console.

GET http://0.0.0.0:4567/images/plains.jpg 404 (Not Found)  

HOWEVER the build folder (after middleman build) the images are there, functioning as expected. The development folder (source) the issue remains.

when i try to view the image by itself i get this in the browser:

 File Not Found

 /images/plains.jpg

 If this is an an asset from a gem, add sprockets.import_asset 'plains.jpg' to your config.rb.

I've tried implementing sprockets.import_asset ... but no avail. This has never happened in the past. Would have done a fresh init but I'm too near to the end to start over.

CONFIG.RB

###
# Compass
###


# Susy grids in Compass
# First: gem install susy
# require 'susy'

# Change Compass configuration
# compass_config do |config|
#   config.output_style = :compact
# end

###
# Page options, layouts, aliases and proxies
###

# Per-page layout changes:
#
# With no layout
# page "/path/to/file.html", :layout => false
#
# With alternative layout
# page "/path/to/file.html", :layout => :otherlayout
#
# A path which all have the same layout
# with_layout :admin do
#   page "/admin/*"
# end

# Proxy (fake) files
# page "/this-page-has-no-template.html", :proxy => "/template-file.html" do
#   @which_fake_page = "Rendering a fake page with a variable"
# end

###
# Helpers
###

# Automatic image dimensions on image_tag helper
# activate :automatic_image_sizes

# Methods defined in the helpers block are available in templates
# helpers do
#   def some_helper
#     "Helping"
#   end
# end

set :css_dir, 'css'

set :js_dir, 'js'

set :images_dir, "images"

activate :livereload

# Build-specific configuration
configure :build do
  # For example, change the Compass output style for deployment
  #activate :minify_css

  # Minify Javascript on build
  #activate :minify_javascript

  # Enable cache buster
  #activate :cache_buster

  # Use relative URLs
 activate :relative_assets

  activate :directory_indexes

  # Compress PNGs after build
  # First: gem install middleman-smusher
  # require "middleman-smusher"
  # activate :smusher

  # Or use a different image path
  # set :http_path, "/Content/images/"
end

  activate :directory_indexes


sass_options = {:debug_info => true}

sass_options = {:sourcemap => true}

Document Sass/Compass configuration

Configuring Sass and Compass seems to be a sore point for a lot of users, and there's nothing on the guides to help. We should have a whole page covering this.

Can't Stop Middleman Guides without Killing Ruby

When I bundle install and exec the server, everything seems fine in that I can view the docs at localhost:4567. However, it outputs this in terminal:

== The Middleman is loading
/Users/kevinhale/Sites/middleman/middleman-core/lib/middleman-core/vendor/darwin/lib/rb-fsevent/fsevent.rb:89:in popen': No such file or directory - /Users/kevinhale/Sites/middleman/middleman-core/bin/fsevent_watch_guard (Errno::ENOENT) from /Users/kevinhale/Sites/middleman/middleman-core/lib/middleman-core/vendor/darwin/lib/rb-fsevent/fsevent.rb:89:inpipe'
from /Users/kevinhale/Sites/middleman/middleman-core/lib/middleman-core/vendor/darwin/lib/rb-fsevent/fsevent.rb:46:in stop' from /Users/kevinhale/Sites/middleman/middleman-core/lib/middleman-core/vendor/darwin/lib/rb-fsevent/fsevent.rb:42:inensure in run'
from /Users/kevinhale/Sites/middleman/middleman-core/lib/middleman-core/vendor/darwin/lib/rb-fsevent/fsevent.rb:42:in run' from /Users/kevinhale/.rvm/gems/ruby-1.9.3-p0/gems/fssm-0.2.8.1/lib/fssm/backends/rbfsevent.rb:20:inrun'
from /Users/kevinhale/.rvm/gems/ruby-1.9.3-p0/gems/fssm-0.2.8.1/lib/fssm/monitor.rb:26:in run' from /Users/kevinhale/.rvm/gems/ruby-1.9.3-p0/gems/fssm-0.2.8.1/lib/fssm.rb:70:inmonitor'
from /Users/kevinhale/Sites/middleman/middleman-core/lib/middleman-core/watcher.rb:49:in watch!' from /Users/kevinhale/Sites/middleman/middleman-core/lib/middleman-core/watcher.rb:13:instart'
from /Users/kevinhale/Sites/middleman/middleman-core/lib/middleman-core/cli/server.rb:51:in server' from /Users/kevinhale/.rvm/gems/ruby-1.9.3-p0/gems/thor-0.14.6/lib/thor/task.rb:22:inrun'
from /Users/kevinhale/.rvm/gems/ruby-1.9.3-p0/gems/thor-0.14.6/lib/thor/invocation.rb:118:in invoke_task' from /Users/kevinhale/.rvm/gems/ruby-1.9.3-p0/gems/thor-0.14.6/lib/thor.rb:263:indispatch'
from /Users/kevinhale/.rvm/gems/ruby-1.9.3-p0/gems/thor-0.14.6/lib/thor/base.rb:389:in start' from /Users/kevinhale/Sites/middleman/middleman-core/lib/middleman-core/cli.rb:49:inmethod_missing'
from /Users/kevinhale/.rvm/gems/ruby-1.9.3-p0/gems/thor-0.14.6/lib/thor/task.rb:22:in run' from /Users/kevinhale/.rvm/gems/ruby-1.9.3-p0/gems/thor-0.14.6/lib/thor/task.rb:108:inrun'
from /Users/kevinhale/.rvm/gems/ruby-1.9.3-p0/gems/thor-0.14.6/lib/thor/invocation.rb:118:in invoke_task' from /Users/kevinhale/.rvm/gems/ruby-1.9.3-p0/gems/thor-0.14.6/lib/thor.rb:263:indispatch'
from /Users/kevinhale/.rvm/gems/ruby-1.9.3-p0/gems/thor-0.14.6/lib/thor/base.rb:389:in start' from /Users/kevinhale/.rvm/gems/ruby-1.9.3-p0/gems/middleman-core-3.0.0.beta.1/bin/middleman:54:inblock in <top (required)>'
from /Users/kevinhale/.rvm/gems/ruby-1.9.3-p0/gems/middleman-core-3.0.0.beta.1/bin/middleman:51:in chdir' from /Users/kevinhale/.rvm/gems/ruby-1.9.3-p0/gems/middleman-core-3.0.0.beta.1/bin/middleman:51:in<top (required)>'
from /Users/kevinhale/.rvm/gems/ruby-1.9.3-p0/bin/middleman:19:in load' from /Users/kevinhale/.rvm/gems/ruby-1.9.3-p0/bin/middleman:19:in

'
== The Middleman is standing watch on port 4567

And then gives me the prompt, which makes it seem to run as a background process and there's no way for me to stop it without killing Ruby process. I am running Middleman 3.0 beta, so I don't know if that affects things.

Publish documentation on creating project templates

There's a registry for project templates but no information on how to create your own project template.

Document :asset_host

Document sitemap redirects feature

@tdreyno I know you added a feature to generate redirect pages, but I don't think it's documented anywhere.

Additional example of users

The new website is gorgeous!

If you want to add another company using Middleman, Hashicorp could be a good example.

I'm not affiliated with them in anyway, but I thought they'd make a good example since they are pretty well known (they've made Vagrant, Packer, Consul & Terraform – all developer tools).

Their logo can be downloaded here:
https://hashicorp.com/press.html

Totally up to you if you want to add them! Mailchimp, Basho and Thoughtbot are well-known, maybe it's enough with 3 + the link to all others.

The last few site navigation links are not accessible on the 11inch Macbook Air

FYI

It's not possible to navigate to the lower navigation links while browsing the Documentation site on the 11inch Macbook Air

See...

Nested Layouts link goes no where…

It's possible the guide hasn't been written yet, I haven't seen a file for it anywhere. Is it based on something else? I'd be happy to look at some source and see if I can write a guide, anything to contribute to this really awesome project.

Important comments getting compressed out

Comments formatted with an exclamation mark are compressed out. This is not the default behavior of Sass compressed output so I was surprised to see it in middleman.

/*! important comment */

This comment does not result as a comment in the compressed source:
https://github.com/scottkellum/scottkellum.com/blob/master/source/stylesheets/style.scss#L1

Guide for sitemap

We need to write a guide for the sitemap feature, what methods are available, and how to use it from templates and config.rb.

Example syntax error

Here https://github.com/middleman/middleman-guides/blob/master/source/advanced/custom.html.markdown

class MyFeature < Middleman::Extension
    def initialize(app, options_hash={}, &block)
      super
    end
    alias :included :registered
  end
end

Should be

class MyFeature < Middleman::Extension
  def initialize(app, options_hash={}, &block)
    super
  end
  alias :included :registered
end

Document Deployment

Rack and Static builds should be covered. Brief mention of Heroku, reference Apache-related docs.

Fix “fork and edit” URLs in footer

The URLs for the links from the online version of the guide to the Github files seem broken. Here's an example:

URL should be:

https://github.com/middleman/middleman-guides/blob/master/source/extensions/livereload.html.markdown

URL really is:

https://github.com/middleman/middleman-guides/blob/master/source/guides/livereload.html.markdown

It seems the helper edit_guide_url (https://github.com/middleman/middleman-guides/blob/master/lib/guide_helpers.rb#L18) spits out an incorrect path.

Reduce count of scrollbars

There are two scrollbars. Would it be possible to reduce the count to one? I'm using Firefox 36.

Asset Pipeline with bootstrap-sass gem not compatible with glyphicons

Hi.

This issue is about this document.
https://github.com/middleman/middleman-guides/blob/master/source/basics/asset-pipeline.markdown

I found a problem when using "bootstrap-sass" gem with middleman (3.3.2); glyphicons are not working.

In this document, we should add only this line to Gemfile

gem "bootstrap-sass", :require => false

but, I think this line are also needed to use bootstrap-sass with middleman... isn't it?

# in config.rb
require "bootstrap-sass/sass_functions.rb"

I think it's a trap in the document.

content_for with different engines for page & layout

Steps to reproduce:

1. Create simple middleman project (middleman init).
2. mv source/index.html.erb source/index.html.haml.
3. Edit index.html.haml (just reimplement the same in haml).
4. Add to the config.rb: set 'haml', :layout_engine => 'erb'
5. middleman server; wget http://localhost:4567
6. Look at the incorrect output here: https://gist.github.com/2595068

Workaround:

index.html.haml:

    = partial 'head_content'

_head_content.html.erb:

    <% content_for :head do %>Works!<% end %>

Components versions:

• middleman-2.0.15.3
• haml-3.1.4

Document all config.rb settings

A comprehensive guide to settings would be very helpful.

Error when using the link_to helper

I find that when I try to use the link_to helper and take a block, it always pop ups a syntax error. Following is the code I've tested:

<%= link_to 'http://mysite.com' do %>
  <%= image_tag 'mylogo.png' %>
<% end %>

test.html.erb:1: syntax error, unexpected ')' ...ink_to 'http://mysite.com' do ).to_s) ... ^

Thanks

"Built Using Middleman" page... links and descriptive text?

Hi

I'm not sure if this was a decision made a while ago, but the list of sites built with Middleman doesn't consist of links and description, just the url for the site. If this is intentional, no worries, but if you want me to update it to links and descriptions I'd be happy to.

-d

Middleman guides running on Windows 7?

Hi,

I am trying to get middleman running on windows 7 but the server does not seem to startup. This is my first attempt at running some ruby on Windows - so could well be missing something obvious...

Using ruby 1.9.3 from the installer.

Using bundler.

Grabbed middleman from github, checked out the 2.0.14 branch.

Grabbed middleman-guides, did a bundle install, then a bundle exec middleman server to run it, but get this error:

...
Using middleman (2.0.14) from source at ../middleman
Using nokogiri (1.5.0)
Using rubypython (0.5.3)
Using pygments.rb (0.2.4)
Using rack-codehighlighter (0.5.0) from git://github.com/wbzyl/rack-codehighlighter.git (at master)
Installing redcarpet (2.1.0) with native extensions
Using bundler (1.0.22)
Your bundle is updated! Use `bundle show [gemname]` to see where a bundled gem is installed.

C:\Users\kimptoc\dev\middleman-guides>bundle exec middleman server
C:/Users/kimptoc/dev/middleman/lib/middleman/guard.rb:5: Use RbConfig instead of obsolete and deprecated Config.
You must 'gem install win32console' to use color on Windows
Your system doesn't support QUIT signal, so Ctrl-\ (Run all) won't work
Your system doesn't support TSTP signal, so Ctrl-Z (Reload) won't work
Using inline Guardfile.
Guard is now watching at 'C:/Users/kimptoc/dev/middleman-guides'
C:/Users/kimptoc/dev/middleman/lib/middleman/guard.rb:5: Use RbConfig instead of obsolete and deprecated Config.
"server" was called incorrectly. Call as "middleman server [-p 4567] [-e development]".

If I run it and specify the -e/-p, I get this slightly different output:

C:\Users\kimptoc\dev\middleman-guides>bundle exec middleman server -p 4567 -e development
C:/Users/kimptoc/dev/middleman/lib/middleman/guard.rb:5: Use RbConfig instead of obsolete and deprecated Config.
You must 'gem install win32console' to use color on Windows
Your system doesn't support QUIT signal, so Ctrl-\ (Run all) won't work
Your system doesn't support TSTP signal, so Ctrl-Z (Reload) won't work
Using inline Guardfile.
Guard is now watching at 'C:/Users/kimptoc/dev/middleman-guides'
C:/Users/kimptoc/dev/middleman/lib/middleman/guard.rb:5: Use RbConfig instead of obsolete and deprecated Config.
You must 'gem install win32console' to use color on Windows
Your system doesn't support QUIT signal, so Ctrl-\ (Run all) won't work
Your system doesn't support TSTP signal, so Ctrl-Z (Reload) won't work
Using inline Guardfile.
Guard is now watching at 'C:/Users/kimptoc/dev/middleman-guides'

Bye bye...

Bye bye...

Thanks in advance for any tips. ~chris

PS I noticed that its using an old-ish version of guard (0.6.3) and see thats now at 1.0.0. Googling around the error seemed to indicate a related error with guard (although that might be when I was trying middleman 3...)

PPS I saw there was a similar issue to this with running on Windows 7, but closed without a solution mentioned.

PPPS middleman build seems to be working fine - generates my static site ok.

docs sidebar scroll and height

Chrome Version 40.0.2214.111 (64-bit)

sidebar navigation is hidden off screen:

Show off popular Middleman built sites

Have you though about showing off some of the top shelf Middleman built sites? I keep stumbling on some I'd be impressed If I saw them as a 'we choose Middleman'.

Perhaps compiling a list of known ones might be a good start?

• Bundler - https://github.com/bundler/bundler-site
• Emberjs - https://github.com/emberjs/website
• Basho - https://github.com/basho/basho_docs

I know we have the built-using-middleman page but I'm not completely sure about its future as a page.

Thoughts?

Search for documentation

For 3.1 perhaps we could check out using a free Switftype account to provide documentation search. I'm quite impressed by its results ( Demo )

Remove `middleman server --livereload` from docs

The --livereload flag is no longer necessary and causes the following error: "Unknown switches '--livereload'"

Setting variables

extensions/custom: Missing examples about how to use these variables.

Navigation alignment

The baseline for the Middleman link on the left doesn't match the other side -- just looks off to me.
I think it could do with being a bit bigger too as it's the homepage link, maybe just increase its font size till it looks right?

Sitemap Manipulators code does not show that resources needs to be returned

In Custom Extensions section on Sitemap Manipulators the example code looks like this

def manipulate_resource_list(resources)
    resources.each do |resource|
      resource.destination_path.gsub!("original", "new")
    end
  end

While correct, it's in now way obvious that manipulate_resource_list must return resources. Maybe this could be made more explicit.

Delete </div> tag in example code of article data section

On the blogging page under the article data section is in the first example code, for showing the 5 most-recent articles and their summary, a lonely div closing tag placed:

<a href="<%= article.url %>">Read more</a></div>

I think the tag is not intended to be there because until I removed it the article layout was broken. To prevent other users from running into the same problem, it should be deleted?

Be explicit about the data/ folder location

Let's make sure people understand that data, lib, source and build are siblings.

Add anchor.js to make deep links easier

Would you accept a PR for adding https://github.com/bryanbraun/anchorjs to middleman-guides? Should that be done via bower or do you prefer me to use another tool for that?

Middleman Extension help is inaccurate/out of date

Following the instructions here (src) when trying to add helpers to a custom extension gives me the following error:

uninitialized constant Middleman::Extension (NameError)

The middleman extension command generates a very different structure from the one in the docs:

# Require core library
require "middleman-core"

# Extension namespace
module MyExtension
  class << self

    # Called when user `activate`s your extension
    def registered(app, options={})
      # Setup extension-specific config
      app.set :config_variable, false

      # Include class methods
      # app.extend ClassMethods

      # Include instance methods
      # app.send :include, InstanceMethods

      app.after_configuration do
        # Do something

        # config_variable is now either the default or the user's
        # setting from config.rb
      end
    end
    alias :included :registered
  end

  # module ClassMethods
  #   def a_class_method
  #   end
  # end

  # module InstanceMethods
  #   def an_instance_method
  #   end
  # end

end


# Register extensions which can be activated
# Make sure we have the version of Middleman we expect
# ::Middleman::Extensions.register(:extension_name) do
#
#   # Return the extension module
#   ::MyExtension
#
# end

This latter one works but doing any advanced stuff mentioned in the docs is not obvious. Am I failing to require something that the docs don't mention or is the documentation here simply out of date?

Also I'm still not sure how to properly include helpers within an extension. I've tried adding a helpers do block within the scope of module, class, and InstanceMethods, and none of those work so far.