Custom Extensions with Middleman

Middleman is great tool for building static websites and blogs that don’t require a database or server side functionality. It helps you get started quickly and has support for things like Sass and CoffeScript, so you can build with the modern tools you’re used to using. Trust me, it’s cool.

On top of all of that it gives you the ability to create your own custom extensions, for functionality that might not exist in the core framework. I recently created an extension for our Tech Blog at Belly, and it’s actually pretty easy once you get the hang of the core concepts. In this post, I’ll get you started with creating your own extensions by way of walking thru the one I created. Ready? Here we go!

Background

At Belly, we all write posts for our Tech Blog, so we have a number of authors. We also sometimes write posts together, so a single post can have multiple authors. So, what we want to build is a way to tag a post with an author or authors and have that information organized into profile pages that we can show each author and a list of all of their blog posts. Make sense? Seems pretty straight forward, so how do we get started?

Middleman has a handy generator for building a scaffold for a new extension. This generator actually builds out a gem for you with some default files and folders structure, so it makes it super easy to get started. Outside of your project directory, run this command:

1
middleman extension YOUR_EXTENSION_NAME # i.e. middleman-blog-authors

Which will give you some files that look like this:

Take a look at your extension file in lib (middleman-blog-authors.rb) and you’ll see the generated code. There are a lot of comments in here, so it makes it pretty easy to see the important parts.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
# Require core library require "middleman-core" # Extension namespace class MyExtension < ::Middleman::Extension option :my_option, "default", "An example option" def initialize(app, options_hash={}, &block) # Call super to build options from the options_hash super # Require libraries only when activated # require 'necessary/library' # set up your extension # puts options.my_option end def after_configuration # Do something end # A Sitemap Manipulator # def manipulate_resource_list(resources) # end # module do # def a_helper # end # end end # Register extensions which can be activated # Make sure we have the version of Middleman we expect # Name param may be omited, it will default to underscored # version of class name # MyExtension.register(:my_extension)

There are 3 things to care about in here:

  • The initialize method
  • The after_configuration method
  • The extension registration hook

initialize

This method is used to run any code needed when the extension is loaded, such as loading dependencies and setting config options, etc.

1
2
3
4
5
6
7
8
9
10
def initialize(app, options_hash={}, &block) super require 'blog_article' require 'blog_data' require 'author_pages' require 'author' app.set :blog_authors_options, options app.set :blog_authors_data, {} end

after_configuration

after_configuration is used to run code after the config.rb file has been fully processed. This means that you will have all extensions loaded and all the site objects built. For this extension, we are using after_configuration to register a resource_list_manipulator, which is just a class that iterates through all the pages on the site so you can do something with them.

1
2
3
4
5
6
7
def after_configuration @app.sitemap.register_resource_list_manipulator( :author_pages, ::Middleman::BlogAuthors::AuthorPages.new(@app, self), false ) end

register

Once you have your hooks setup, you just need to register the extension with Middleman, so it can enabled via the config.rb file.

1
::Middleman::Extensions.register(:authors, BlogAuthors)

Then, in your Middleman app, add your new extension to your Gemfile:

1
gem "middleman-blog-authors", :path => "~/path/to/extension"

And update your config.rb to activate you new extension:

1
activate :authors

And, that’s it! At a very basic level, those three hooks are all you need to get a functional extension created. It may not do a whole lot yet, but it works. Take a look at the documentation for additional details, and to see the finished middleman-blog-authors extension check out the GitHub repo.

Ask a question or share this article, we’d love to hear from you!

Tweet