Alchemy 5.0

tvdeyen profile image Thomas von Deyen ・5 min read

This is a huge release laying the foundation for Alchemy being a API first CMS for static site generators. While we truly believe in server site rendered HTML and will always support this, we also think that statically generated sites talking via APIs to the backend (aka the "JAM Stack") can be a huge improvement for modern frontends. That's why we made major changes to the internals of Alchemy that help you to better serialize your content and remove weirdness from the code base.

Before we begin thanks for all the contributions that made this release possible:

You really help to make Alchemy better every day.

Thanks for that ❤️

Major changes

Removed the single root page from the page tree

Alchemy always had a single root page under which all other pages were nested. Even the layout pages were nested under hidden layout root pages. This was very confusing and prevents us from making changes to the internal structure of Alchemy for features coming in the near future.

             Root Page
            /        \
  Language Root     Layout Root
  ├ Page 1            ├ Header
  | \                 └ Footer
  |  ├ Page 2
  |  └ Page 3
  ├ Page 4
  └ Page 5

This has now been changed to a easier to understand page structure

       |            |        |
  Language Root   Header   Footer
  ├ Page 1
  | \
  |  ├ Page 2
  |  └ Page 3
  ├ Page 4
  └ Page 5

Remove Page visible attribute

The page visible attribute was one of the most confusing attribute in Alchemy. It did way more things than you might have expected. Did you know that it also changed how URLs got created? Probably not. And that's why removed it.

Want to make a page appear in the navigation? Create a Menu instead and put pages into it.

In order to help with the upgrade make sure to update to Alchemy 4.6 first and use Menus and Tags instead to re-organize your pages if your page tree does not reflect the URL hierarchy.

A rake task to help with the migration is available.

  bin/rake alchemy:upgrade:4.6:restructure_page_tree

Always create nested urls

With the introduction of Menus and the removal of the Page visible flag we now completely separated the page tree from generating the navigation. That's why we now always generate a nested URL. Don't want to nest a pages URL? Just move it up in the tree.

Configurable edit page preview per site

This is a true benefit for all static sites running Alchemy as it's API. On a per site basis you can configure the host (and basic auth) to your static site and Alchemy will preview it in the build in page edit preview.

Add a @alchemy_cms/admin npm package

Modern ES6 is everywhere. We started to work on the transition to a more modern JS stack. This is the first step.

Add an On-Boarding Flow

We removed the implicit creation of the sites and default languages. We now do this via the UI instead letting admins decide what to create instead.

Removed element editor partials

After being deprecated we removed the support for element editor partials. Alchemy now renders them for you. If you rely on passing custom options into element editors and the content editors please consider to use the settings hash on the contents definition of your elements or using a custom essence.

Other minor changes

Other breaking changes

This release also removes all deprecated methods and classes from 4.6. In order to be able to smoothly upgrade please make sure to update to Alchemy 4.6 and remove all deprecations from your code base, then upgrade to Alchemy 5 and run the

bin/rake alchemy:upgrade


List of all changes

Have a look into the Changelog for a list of all PRs merged into this release.

Posted on by:

tvdeyen profile

Thomas von Deyen


Anti-fascist Ruby and Javascript developer from Hamburg, Germany. Most famous for @alchemycms


Rails based content management framework


markdown guide