---
title:  Backwards Compatibility
blurb:  Notes about Backwards Compatibility with earlier versions of Middlemac.
layout: template-logo-medium
---
<%= md_links %>
<%= md_images %>

<%= current_page.data.title %>
==============================

_Middlemac_ version 2.0.0 is a **major** update. It’s an API-breaking update and
projects using _Middlemac_ version 1.0 will _not_ build without some changes to
your project.

Additionally because _Middlemac_ now requires _Middleman_ 4.1.7 or higher, there
are some _Middleman_-related changes, too.

This version of _Middlemac_ is a complete rewrite, and it was designed in such a
way that in the future it _can_ be upgraded without breaking your projects. We
hope that the improvements, though, make it completely worth the trouble to
update.


Upgrading a project
-------------------

No automated method of upgrading a project is provided, but the steps for
achieving an upgrade are fairly simple.

### Files

`middlemac.rb`
  : This file is no longer required and should be removed from your project.
    _Middlemac_ is now a proper Ruby gem and is managed by Ruby directly.

`Gemfile`
  : You must replace your `Gemfile` with ours, or at least ensure that your
    `Gemfile` is edited to reflect the new gem requirements.

`config.rb`
  : You should use our new `config.rb` as a starting point for replacing your
    current `config.rb` file. Most of the changes are obvious, and pay special
    attention to some of the items that have letter case changes.
    
`Contents/Resources/Base.lproj/assets/`
`   layouts/layout-html4.haml`
`   fonts/*`
`   stylesheets/*`
  : These files from a new project (or this sample documentation project) must
    replace the corresponding files in your current project. In particular the
    `layouts/layout-html4.haml` file enables the new `breadcrumbs` configuration
    option. The new `fonts/` directory ensures that the required `font-awesome`
    fonts are always available, and there have been visual tweaks in all of the
    `stylesheets/` files (in particular we now have to include the `github`
    styles in a new way).


### Configuration Changes

Amongst the changes mentioned above to `config.rb` is the removal of support for
_Middleman_’s `partials_dir` configuration setting. However in order to maintain
backwards compatibility we have preserved this functionality in _Middlemac_.
Simply move the `partials_dir` setting into the `activate Middlemac` block.

If you are following _Middlemac_ conventions, you can delete the `partials_dir`
setting completely, as the default is appropriate.
{: .note }


### Other Partials Changes

By default the automatic navigation partials are no longer included in the
sample project, and if you were using them you will have to keep your own
partials.
  
New partials are available as part of the required `middleman-pagegroups` gem,
but we also suggest that you consider using the new helpers instead of partials.

Also keep in mind that `md_links` and `md_images` helpers replace previous
partial functionality. Use these helpers to generate Markdown shortcuts instead.


### Other Changes

_Read_ this documentation and have a close look at the sample project. This is
a big **2.0** release, and lots of things have changed for the better. Before
long, you’ll have your old projects working again.