Middleman has the ability to generate pages which do not have a one-to-one relationship with their template files. What this means is that you can have a single template which generates multiple files based on variables. Here's an example `config.rb` setup:

- :::ruby

["tom", "dick", "harry"].each do |name|

page "/about/#{name}.html", :proxy => "/about/template.html" do

@person_name = name

@@ -22,7 +21,6 @@ When this project is built, four files will be output:

In most cases, you will not want to generate the template itself without the @person_name variable, so you can tell Middleman to ignore it:

In your `config.rb`, activate the `minify_css` and `minify_javascript` features during the build of your site.

- :::ruby

configure :build do

activate :minify_css

activate :minify_javascript

@@ -20,7 +19,6 @@ If you are already using a compressed file that includes `.min` in its filename,

You can customize how the JavaScript compressor works by setting the `:compressor` option when activating the `:minify_javascript` extension in `config.rb` to a custom instance of Uglifier. See (Uglifier's docs)[https://github.com/lautis/uglifier] for details. For example, you could enable unsafe optimizations and mangle top-level variable names like this:

- :::ruby

set :js_compressor, Uglifier.new(:toplevel => true, :unsafe => true)

If you want to exclude any files from being minified, pass the `:ignore` option when activating these extensions, and give it one or more globs, regexes, or procs that identify the files to ignore. Likewise, you can pass an `:exts` option to change which file extensions are renamed.

@@ -29,7 +27,6 @@ If you want to exclude any files from being minified, pass the `:ignore` option

It's a good idea to [serve compressed files](http://developer.yahoo.com/performance/rules.html#gzip) to user agents that can handle it. Many web servers have the ability to gzip files on the fly, but that requires CPU work every time the file is served, and as a result most servers don't perform the maximum compression. Middleman can produce gripped versions of your HTML, CSS, and JavaScript alongside your regular files, and you can instruct your web server to serve those pre-gzipped files directly. First, enable the `:gzip` extension:

- :::ruby

activate :gzip

Then configure your server to serve those files. If you use Nginx, check out [the gzip_static](http://wiki.nginx.org/NginxHttpGzipStaticModule) module. For Apache, you'll have to do something a little trickier - see [this Gist](https://gist.github.com/2200790) for an example.

@@ -40,17 +37,13 @@ If you also want to compress images on build, you can use the [Middleman Smusher

@@ -10,7 +10,6 @@ To make your website render as quickly as possible, you should serve any assets,

The most effective technique for preventing users from using outdated files is to change the asset's filename every time you change one of your assets. Since that would be a pain to do by hand, Middleman comes with an `:asset_hash` extension that does it for you. First, activate the extension in your `config.rb`:

- :::ruby

activate :asset_hash

Now, refer to your assets as normal, with their original filename. You can use helpers like `image_tag` as well. However, when your site is built, each asset will be produced with a bit of extra text at the end of the filename that is tied to the content of the file, and all of your other files (HTML, CSS, JavaScript, etc) will be changed to reference that unique-ified filename instead of the original one. Now you can serve your assets with a "never expire" policy, but be sure that when you change them, they'll show up as a different filename.

@@ -23,7 +22,6 @@ If you want to exclude any files from being renamed, pass the `:ignore` option w

The second approach is to append a value to the end of URLs that reference your assets. For example, instead of referencing `my_image.png` you'd reference `my_image.png?1234115152`. The extra info at the end of the URL is enough to tell many (but not all) browsers and proxies to cache that file separately from the same file with a different cache buster value. To use this, activate the `:cache_buster` extension in your `config.rb`:

- :::ruby

activate :cache_buster

Now, to use cache-safe URLs, you must use [asset path helpers](http://www.padrinorb.com/api/Padrino/Helpers/AssetTagHelpers.html) like `image_path` or `javascript_include_tag`. Make sure to use [Compass helpers](http://compass-style.org/reference/compass/helpers/urls/) in your SASS too (`image-url`, etc.). For JavaScript, you'll need to make ERb templates like `my script.js.erb` and call asset helpers via ERb tags to output the right values. If you forget one, your users will still get the file (since the copy on the server just has a normal name) but they might not see changes.

-The extension provides a new api for enabling localization in your `config.rb`:

-

- :::ruby

activate :i18n

By default this will search the `locales` folder in the root of your project for YAML files representing each locale you want to support. The YAML file is a set of keys and values for each string you need to localize in your site. The keys, which is how you will refer to these strings in your templates, must be the same in each locale, but the values will change. Here are two example YAML files.

`locales/en.yml`:

- :::yaml

---

en:

hello: "Hello"

`locales/es.yml`:

- :::yaml

---

es:

hello: "Hola"

Localizable templates live in the `source/localizable` folder by default (see below on how to change this option). Each template in that folder will have access to the `I18n` helper. Using this helper, you can refer to keys from your YAML files and inject the language-specific values into your template. Here's a simple `source/localizable/hello_world.html.erb` template:

- :::erb

<%= I18n.t(:hello) %> World

This would output two files:

@@ -50,7 +41,6 @@ Each individual language is accessible in its own namespaced path. By default, t

You can change this with the `:path` option, but remember: the URL will always include the name of the YAML file:

- :::ruby

activate :i18n, :path => "/langs/:locale/"

Now the paths would be:

@@ -61,7 +51,6 @@ Now the paths would be:

If you are unhappy using the YAML file names as part of your path, you can remap them to different values.

- :::ruby

activate :i18n, :path => "/langs/:locale/",

:lang_map => { :en => :english, :es => :spanish, :fr => :french }

@@ -82,7 +71,6 @@ Let's say we have a file `source/localizable/hello.html.erb`. By default, this w

If we want to rename that file to `hola.html` for Spanish only, we can use the `paths` key in `locales/es.yml`:

- :::yaml

---

es:

hello: "Hola"

@@ -98,7 +86,6 @@ Now, the files would be output as:

By default, the contents of `source/localizable` will be built in multiple languages while the rest of your templates will continue to work normally. The name of this folder can be changed with the `:templates_dir` option:

- :::ruby

# Look in `source/language_specific` instead

activate :i18n, :templates_dir => "language_specific"

@@ -106,7 +93,6 @@ By default, the contents of `source/localizable` will be built in multiple langu

If you'd prefer specify a list of supported languages rather than automatically discovering files in `locales/`, you can use the `:langs` option:

- :::ruby

activate :i18n, :langs => [:en] # Ignore all languages except :en

##Default (Root) Language

@@ -119,7 +105,6 @@ By default, the first language (either specified by `:langs` or discovered in yo

You can change the default or disable mounting a specific language at the root entirely using the `:mount_at_root` option:

If you are not using a Rack-based web-server, you can use the Directory Indexes feature to tell Middleman to create a folder for each `.html` file and place the built template file as the index of that folder. In your `config.rb`:

- :::ruby

activate :directory_indexes

Now when the above project is built, the `about-us.html.erb` file will be output as `about-us/index.html`. When placed in an Apache compatible web-server, the page would be available at:

@@ -37,19 +35,16 @@ Now when the above project is built, the `about-us.html.erb` file will be output

If you prefer a different file be output, you can use the `index_file` variable. For example, IIS uses default.html:

- :::ruby

set :index_file, "default.html"

Or, you may want a PHP file:

- :::ruby

set :index_file, "index.php"

###Opt-out

If there are pages which you don't want automatically renamed, you can opt-out:

- :::ruby

page "/i-really-want-the-extension.html", :directory_index => false

`page` works with regexes or file globs if you want to turn off indexes for many files at once.

@@ -12,7 +12,6 @@ Middleman has full access to Rack Middleware which opens up an expansive univers

This site is written in Middleman and features many code blocks which have syntax highlighting. This syntax highlighting is accomplished outside the scope of Middleman. This site renders `<code>` blocks and then Rack Middleware takes over an enhances those blocks with syntax highlight. The middleware in use is called [`Rack::Codehighlighter`](https://github.com/wbzyl/rack-codehighlighter). Here's how it can be used in your `config.rb`:

- :::ruby

require 'rack/codehighlighter'

require "pygments"

use Rack::Codehighlighter,

@@ -23,7 +22,6 @@ This site is written in Middleman and features many code blocks which have synta

Make sure you add the right dependencies to your `Gemfile` to make those work:

Middleman has an official extension to support blogging, articles and tagging. `middleman-blog` ships as an extension and must be installed to use. Simply specify the gem in your `Gemfile`:

- :::ruby

gem "middleman-blog"

Or install it by hand if you're not using Bundler:

- :::bash

gem install middleman-blog

Then activate the extension in your `config.rb`:

- :::ruby

activate :blog do |blog|

# set options on blog

end

Alternatively, you can generate a fresh project already setup for blogging:

- :::bash

middleman init MY_BLOG_PROJECT --template=blog

If you already have a Middleman project, you can re-run `middleman init` with the blog template option to generate the sample [`index.html`](https://github.com/middleman/middleman-blog/blob/master/lib/middleman-blog/template/source/index.html.erb), [`tag.html`](https://github.com/middleman/middleman-blog/blob/master/lib/middleman-blog/template/source/tag.html.erb), [`calendar.html`](https://github.com/middleman/middleman-blog/blob/master/lib/middleman-blog/template/source/calendar.html.erb), and [`feed.xml`](https://github.com/middleman/middleman-blog/blob/master/lib/middleman-blog/template/source/feed.xml.builder), or you can write those yourself. You can see [what gets generated](https://github.com/middleman/middleman-blog/tree/master/lib/middleman-blog/template/source) on GitHub.

@@ -48,14 +44,12 @@ As a shortcut, you can run `middleman article TITLE` and Middleman will create a

The base path for your blog defaults to `/` (the root of your website) but can be overridden in `config.rb`:

- :::ruby

activate :blog do |blog|

# set options on blog

end

The permalink for viewing your posts can be easily changed as well:

- :::ruby

activate :blog do |blog|

blog.permalink = "blog/:year/:title.html"

end

@@ -68,7 +62,6 @@ By default, articles can be truncated when viewed outside their permalink page.

This can be changed in `config.rb`:

- :::ruby

activate :blog do |blog|

blog.summary_separator = /SPLIT_SUMMARY_BEFORE_THIS/

end

@@ -93,7 +86,6 @@ Now you can find this article listed on `tags/blogging.html`.

This path can be changed in `config.rb`:

- :::ruby

activate :blog do |blog|

blog.taglink = "categories/:tag.html"

end

@@ -112,7 +104,6 @@ In templates, you can use the [`blog_year_path`](http://rubydoc.info/github/midd

You can set a specific [layout](/templates/templates-layouts-partials) to be used for all articles in your `config.rb`:

@@ -8,7 +8,6 @@ Middleman extensions are Ruby classes which can hook into various points of the

The most basic extension looks like:

- :::ruby

module MyFeature

class << self

def registered(app)

@@ -24,7 +23,6 @@ This module must be accessible to your `config.rb` file. Either define it direct

Finally, once your module is included, you must activate it in `config.rb`:

- :::ruby

activate :my_feature

The [`register`](http://rubydoc.info/github/middleman/middleman/master/Middleman/Extensions#register-class_method) method lets you choose the name your extension is activated with. It can also take a block if you want to require files only when your extension is activated.

@@ -33,7 +31,6 @@ In the `MyFeature` extension, the `registered` method will be called as soon as

`activate` can also take an options hash (which are passed to `register`) or a block which can be used to configure your extension.

The [`Middleman::Application`](http://rubydoc.info/github/middleman/middleman/Middleman/Application) class can be used to change global settings (variables using the `set` command) that can be used in your extension.

Sometimes you will want to wait until the `config.rb` has been executed to run code. For example, if you rely on the `:css_dir` variable, you should wait until it has been set. For this, we'll use a callback:

- :::ruby

module MyFeature

class << self

def registered(app)

@@ -132,7 +125,6 @@ Sometimes you will want to wait until the `config.rb` has been executed to run c

Similarly, if you're extension relies on variable and settings within Compass to be ready, use the `compass_config` callback.

- :::ruby

module MyFeature

class << self

def registered(app)

@@ -149,7 +141,6 @@ Similarly, if you're extension relies on variable and settings within Compass to

Helpers are methods available inside your template. To add helper methods, we do the following:

Now, inside your templates, you will have access to a `make_a_link` method. Here's an example using an ERb template:

- :::erb

<h1><%= make_a_link("http://example.com", "Click me") %></h1>

##Request Callback

@@ -176,7 +166,6 @@ The request callback allows you to do processing before Middleman renders the pa

Here's an example:

- :::ruby

module MyFeature

class << self

def registered(app)

@@ -195,7 +184,6 @@ The above sets the `:currently_requested_path` value at the beginning of each re

You can modify or add pages in the [sitemap](/metadata/sitemap) by creating a Sitemap extension. The [`:directory_indexes`](/advanced/pretty-urls) extension uses this feature to reroute normal pages to their directory-index version, and the [blog extension](/extensions/blog/) uses several plugins to generate tag and calendar pages. See [the `Sitemap::Store` class](http://rubydoc.info/github/middleman/middleman/Middleman/Sitemap/Store#register_resource_list_manipulator-instance_method) for more details.

- :::ruby

module MyFeature

class << self

def registered(app)

@@ -227,7 +215,6 @@ You can modify or add pages in the [sitemap](/metadata/sitemap) by creating a Si

This callback is used to execute code after the build process has finished. The [middleman-smusher] extension uses this feature to compress all the images in the build folder after it has been built. It's also conceivable to integrate a deployment script after build.

Middleman provides an official extension to support for the LiveReload browser extension. Simply install the gem:

- :::bash

gem install middleman-livereload

If you have installed [the LiveReload extension] in your browser, you can have Middleman automatically tell the browser to refresh upon changes to your source code. To do this, you will need to start the Middleman server in LiveReload mode:

- :::bash

middleman server --livereload

Now, browsers using the LiveReload extension can connect to Middleman and automatically refresh after you update your code.

@@ -16,7 +16,6 @@ Mac OS X comes prepackaged with both Ruby and Rubygems, however, some of the Mid

Once you have Ruby and RubyGems up and running, execute the following from the command line:

- :::bash

gem install middleman --pre

This will install Middleman, its dependencies and the command-line tools for using Middleman.

@@ -35,7 +34,6 @@ To get started we will need to create a project folder for Middleman to work out

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).

- :::bash

middleman init my_new_project

###The Skeleton

@@ -56,26 +54,22 @@ A config.ru file describes how the site should be loaded by a Rack-enabled webse

To include a boilerplate `config.ru` file in your project, add the `--rack` flag to the init command:

- :::bash

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:

- :::bash

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:

- :::bash

middleman init --help

This will list my custom mobile framework and I can create new projects based on it as before:

- :::bash

middleman init my_new_mobile_project --template=mobile

##The Development Cycle (middleman server)

@@ -86,7 +80,6 @@ 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:

- :::bash

cd my_project

bundle exec middleman server

@@ -100,7 +93,6 @@ You can stop the preview server from the command-line using CTRL-C.

Running `middleman` without any commands is the same as starting a server.

- :::bash

bundle exec middleman

This will do exactly the same thing as `middleman server`.

@@ -109,7 +101,6 @@ This will do exactly the same thing as `middleman server`.

Under some circumstances(one known case is under Windows, see [here](https://github.com/middleman/middleman/issues/101)), `middleman` might not work as expected, try using a full command instead:

- :::bash

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.

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`:

@@ -20,7 +20,6 @@ Each page can also find other pages related to it in the site hierarchy. The `pa

You can use the sitemap information to create new [dynamic pages] from `config.rb` (this is how the [blog extension](/extensions/blog) creates tag pages), but you need to be a little careful, because the sitemap isn't populated until *after*`config.rb` has already been run. To get around this, you need to register a callback for the application's `ready` event. As an example, let's say we've added a "category" element to the [frontmatter] of our pages, and we want to create category pages dynamically for each category. To do that, we'd add this to `config.rb`:

@@ -10,26 +10,22 @@ Template helpers are methods which can be used in your dynamic templates to simp

Padrino provides a `link_to` function that you can use to make link tags. At its most basic, `link_to` takes the name and URL of a link:

- :::erb

<%= link_to 'My Site', 'http://mysite.com' %>

`link_to` can also take a block, allowing you to provide more complex content for the link:

- :::erb

<%= link_to 'http://mysite.com' do %>

<%= image_tag 'mylogo.png' %>

<% end %>

Middleman enhances the `link_to` helper to be aware of the [sitemap](/metadata/sitemap). If you refer to pages in your source folder (with their file extension minus all the template extensions) then `link_to` will generate the correct link, even if you have extensions like [`:directory_indexes`](/advanced/pretty-urls) on. For example, if you had a file `source/about.html` and `:directory_indexes` on, you could link to it like this:

- :::erb

<%= link_to 'About', '/about.html' %>

Produces: <a href='/about/'>About</a>

You can also refer to source paths relative to your current page. Some people want their links to be relative to the current page. Pass `:relative => true` to `link_to` to get a relative URL.

- :::erb

From within source/foo/index.html.erb, with :directory_indexes on

<%= link_to 'About', '/about.html', :relative => true %>

@@ -37,7 +33,6 @@ You can also refer to source paths relative to your current page. Some people wa

If you want all URLs generated by `link_to` to be relative, add this to `config.rb`:

- :::ruby

set :relative_links, true

You can still override individual links to not be relative by adding `:relative => false`.

@@ -48,14 +43,12 @@ Output helpers are a collection of important methods for managing, capturing and

The `content_for` functionality supports capturing content and then rendering this into a different place such as within a layout. One such example is including assets onto the layout from a template:

- :::erb

<% content_for :assets do %>

<%= stylesheet_link_tag 'index', 'custom' %>

<% end %>

Added to a template, this will capture the includes from the block and allow them to be yielded into the layout:

- :::erb

<head>

<title>Example</title>

<%= stylesheet_link_tag 'style' %>

@@ -66,14 +59,12 @@ This will automatically insert the contents of the block (in this case a stylesh

You can also check if a `content_for` block exists for a given key using `content_for?`:

- :::erb

<% if content_for?(:assets) %>

<div><%= yield_content :assets %></div>

<% end %>

Also supports arguments yielded to the content block

- :::erb

yield_content :head, param1, param2

content_for(:head) { |param1, param2| ...content... }

@@ -83,7 +74,6 @@ Tag helpers are the basic building blocks used to construct html "tags" within a

The tag and `content_tag` are for building arbitrary html tags with a name and specified options. If the tag contains "content" within then `content_tag` is used. For example:

- :::erb

<%= tag :img, :src => "/my_image.png" %>

# => <img src='/my_image.png'>

@@ -94,7 +84,6 @@ The tag and `content_tag` are for building arbitrary html tags with a name and s

The input_tag is used to build tags that are related to accepting input from the user:

- :::ruby

input_tag :text, :class => "demo"

# => <input type='text' class='demo'>

input_tag :password, :value => "secret", :class => "demo"

@@ -104,7 +93,6 @@ The input_tag is used to build tags that are related to accepting input from the

Asset helpers are intended to help insert useful html onto a view template such as hyperlinks, mail_to links, images, stylesheets and javascript. An example of their uses would be on a simple view template:

The `escape_html` and `js_escape_html` function are for taking an html string and escaping certain characters.

`escape_html` will escape ampersands, brackets and quotes to their HTML/XML entities. This is useful to sanitize user content before displaying this on a template. `js_escape_html` is used for passing javascript information from a js template to a javascript function.

There is also an alias for `escape_html` called `h` for even easier usage within templates.

Format helpers also includes a number of useful text manipulation functions such as `simple_format`, `pluralize`, `word_wrap`, and `truncate`.

- :::ruby

simple_format("hello\nworld")

# => "<p>hello<br/>world</p>"

pluralize(2, 'person')

@@ -212,7 +197,6 @@ In addition to the helpers provided by Middleman out of the box, you can also ad

To define a helper method, use the `helpers` block in `config.rb`:

- :::ruby

helpers do

def some_method

# ...do something here...

@@ -221,7 +205,6 @@ To define a helper method, use the `helpers` block in `config.rb`:

Alternatively, you can created external Ruby modules which contain helpers and include them. You can put files in the `lib` directory. For example, if you were to extract the above helpers into a file named `lib/custom_helpers.rb`, you could create a module:

- :::ruby

module CustomHelpers

def some_method

# ...do something here...

@@ -230,7 +213,6 @@ Alternatively, you can created external Ruby modules which contain helpers and i

@@ -14,12 +14,10 @@ All template files in Middleman include the extension of that templating languag

To begin, this file would just contain normal HTML:

- :::erb

<h1>Welcome</h1>

If we wanted to get fancy, we could add a loop:

- :::erb

<h1>Welcome</h1>

<ul>

<% 5.times do |num| %>

@@ -63,7 +61,6 @@ Stylus | .styl | ruby-stylus

[Markdown](http://daringfireball.net/projects/markdown/) is a popular template language that is readable even as plain text. Middleman's default Markdown renderer is [Maruku](http://maruku.rubyforge.org/), though [RedCarpet is suggested](/advanced/speeding-up) for speed and extra features. You can customize you Markdown options in `config.rb`:

- :::ruby

set :markdown_engine, :redcarpet

set :markdown, :fenced_code_blocks => true,

:autolink => true,

@@ -79,7 +76,6 @@ The most basic layout has some shared content and a `yield` call where templates

Here is an example layout using ERb:

- :::erb

<html>

<head>

<title>My Site</title>

@@ -91,12 +87,10 @@ Here is an example layout using ERb:

Given a page template in ERb:

- :::erb

<h1>Hello World</h1>

The combined final output in HTML will be:

- :::erb

<html>

<head>

<title>My Site</title>

@@ -122,7 +116,6 @@ The default layout file lives in the `source` folder and is called "layout" and

To create a new layout for admin, add another file to your `source` folder called "admin.erb". Let's assume the contents are:

- :::erb

<html>

<head>

<title>Admin Area</title>

@@ -134,14 +127,12 @@ To create a new layout for admin, add another file to your `source` folder calle

Now, you need to specify which pages use this alternative layout. You can do this in two ways. If you want to apply this layout to a large group of pages, you can use the "page" command in your `config.rb`. Let's assume you have a folder called "admin" in your `source` folder and all the templates in admin should use the admin layout. The `config.rb` would look like:

- :::ruby

page "/admin/*", :layout => "admin"

This uses a wildcard in the page path to specify that any page under the admin folder should use the admin layout.

You can also reference pages directly. For example, let's say we have a `login.html.erb` template which lives in the source folder, but should also have the admin layout. Let's use this example page template:

- :::erb

<h1>Login</h1>

<form>

<input type="text" placeholder="Email">

@@ -151,12 +142,10 @@ You can also reference pages directly. For example, let's say we have a `login.h

Now you can specify that this specific page has a custom template like this:

- :::ruby

page "/login.html", :layout => "admin"

Which would make the login page use the admin layout. As an alternative to specifying everything in the `config.rb`, you can set the layout on individual pages in their template file using [Individual Page Configuration]. Here is an example `login.html.erb` page which specifies its own layout.

- :::erb

---

layout: admin

---

@@ -173,7 +162,6 @@ Which would make the login page use the admin layout. As an alternative to speci

In some cases, you may not want to use a layout at all. This can be accomplished by setting the default layout to false in your `config.rb`:

- :::ruby

disable :layout

## Partials

@@ -182,14 +170,12 @@ Partials are a way of sharing content across pages to avoid duplication. Partial

Partial files are prefixed with an underscore and include the templating language extension you are using. Here is an example footer partial named `_footer.erb` that lives in the `source` folder:

- :::erb

<footer>

Copyright 2011

</footer>

Now, we can include this partial in the default layout using the "partial" method:

- :::erb

<html>

<head>

<title>My Site</title>

@@ -202,7 +188,6 @@ Now, we can include this partial in the default layout using the "partial" metho