I just switched my homepage from Jekyll to Middleman. The frameworks are very similar and the migration has been relatively painless. The following notes recap the motivations for the switch and what I had to to move to the new framework.
Remark. The following notes were written when I was using older versions of both frameworks, namely, Middleman 3 and Jekyll 2. Some of the remarks are still valid, others issues are now less relevant. I updated the post to reflect some of these changes, but some caution still has to be applied.
The main strengths of Middleman are, in my opinion:
erbtemplates. Middleman allows one to use Ruby rather than Liquid for “dynamic” content. On top of a more familiar syntax, which makes the construction of dynamic content simpler and more flexible (for me, at least), this feature allowed me to reuse a template I developed for a Rails application.
proxydirective. Although I have not yet used this feature, doing the same trick in (older versions of) Jekyll requires the use of plugins. One of such plugins is Jekyll datapage generator
ftp. To achieve the same trick with Jekyll I had to define a Rakefile, which is available here: Jekyll Rakefile.
The only issue I have found with Middleman is an incompatibility between the Sass release of Foundation 5.4.7 and the compass library required by Middleman. This is, in fact, more a problem with Foundation than with Middleman. The effect on websites based on Foundation is that changes to the default configuration are ignored. I have not yet found a good workaround and I’ll just wait for Foundation to release a version which supports more recent releases of Compass (most likely: Foundation version 5.5).
Phase 1. Website up and running with no layouts:
index.textileshould be renamed
index.html.textile. If you want also want to use ERB in the file, add the
erbsuffix; e.g., rename the file to
link_toand the other helpers (e.g.,
image_tag, to simplify the way in which assets are referenced)
The steps above should be enough for a basic website. If you are using custom layouts, move to the next phase!
Phase 2. Migrate layouts and take advantage of Middleman features:
sources/layoutsand change the extension of the layouts to
erb. Thus, for instance,
<%= yield %>in place of `<div class="container grid-lg">
<div class="columns"> <div class="column"> <h1>Source Code in Org Mode</h1> <p>To enable execution of ruby code in OrgMode files, put in your <code class="highlighter-rouge">.emacs</code> file</p>
You can then insert ruby code in your org file using the following tags:
#+BEGIN_SRC ruby a = 2 + 3 b = 10 * 2 [a + b, a] #+END_SRC
C-c C-C … and voila, the result is shown in the buffer
#+RESULTS: | 25 | 5 |
Consult the org-mode manual for more information.
</div> </div> <div class="columns"> <div class="column"> <p><strong>Get in touch</strong></p>
</div> </div> <div class="columns"> <div class="column"> <p><strong>Comments</strong></p>
wrap_layoutsyntax (Have a look at: https://middlemanapp.com/basics/templates/)
Phase 3. Activate some specific features:
Gemfileto include the extensions you prefer (e.g.,
config.rbto minify and compress assets, to bust cache, etc.
This section has been superseded:
One critical point (both with Jekyll and Middleman) used
to be, the management of URLs, especially if the website is deployed
on a suburi (e.g.,
http://www.example.com/a/b/c/). The problem is
the way in which URLs are interpreted. More in details:
href="x/y/z") in templates or in pages is no good, because pages might be deployed at different levels of depth on the website, making relative references wrong
href="/x/y/z") won’t work, unless you specify the full path (e.g.,
/a/b/c/). This however, breaks the possibility of previewing on the local webserver and makes re-deployment on a different URL more difficult.
href="http://...") breaks the possibility of previewing on the local webserver and of moving your website to a different location, if needed.
To solve this problem, when I started using Jekyll, I defined a
Rakefile to simplify
the management of common Jekyll operations, including deployment. The
Rakefile sets a variable
_config.yml. The variable can
thus be prepended to all URLs used on a website, to make them absolute.
Middleman supports a simpler solution. More in details, the
:http_prefix variable can be used to prepend a portion of a path to
URLs defined with the standard helpers:
Thus, for instance, if the website lives on
“http://www.example.com/a/b/c/”, it is sufficient to set
configure :build do set :http_prefix, "/a/b/c/" end
and Middleman will take care of replacing, e.g.,
"p.html" %> with
<a href="/a/b/c/p.html">. (Notice that settting
:http_prefix to a full URL, like, e.g.,
http://..., will cause an
The problem remains, however, with links defined using the native markup tags. For instance, Middleman will not replace the URL of links written in Textile (or Markdown).
The problem can be solved by defining a helper to generate absolute
URLs. Add to your
config.rb the following code:
helpers do def aurl url File.join(http_prefix, url) end end configure :development do set :http_prefix, "/" end configure :build do set :http_prefix, "/a/b/c/" end
and use the
aurl helper every time you want to insert a link or a path
using the markup of the templating language. For instance:
"Some link on my website":<%= aurl("some_page.html") %>
More in details, the following rules apply:
image_tagyou are fine
link_toyou are fine
Get in touch