A green tea cup with the letter "beta" floating up among the steam rising from it


Beta Time

Illustrated drawing of Amadeus Maxmimilian StadlerIllustrated drawing of Amadeus Maxmimilian Stadler

Amadeus Stadler

August 26, 2022

Welcome to the first proper devlog of 2022! For the past few months since the last release at the beginning of April, I’ve been busy implementing the last feature that was still missing from Mattrbld for me to consider its first version “feature-complete”: the ability to add images inline in rich text fields.

In doing so, I also reworked some parts of the Media Library, added quality of life features and fixed a bunch (okay, a boatload) of bugs. With all of this in place and almost a year of using Mattrbld in production, I’m happy to consider version 0.3.0 the first beta-release of the software.

If you’re curious to learn more about what changed and how the new features work, read on—or if you’re eager to try them out yourself, simply get started with Mattrbld.

Documentation Update

One part of this project that I’ve been slacking in is admittedly the documentation. While I did start the section on the Media Library late last year and started filling it with content, the development of new features and bugfixes seemed like a better use of my limited time.

Now that Mattrbld is in beta, however, I want to redouble my efforts regarding the documentation, since I consider that one of the blockers for a proper first stable release.

Once I finish the article on the Advanced Media Library, I’ll be able to move on to the real-time preview section, which will be the last larger section of the documentation.

New Features

With that out of the way, we can finally move on to the good parts and take a look at what actually happened since April.

Easier Sync of Local Changes

The “Sync local changes” modal received a couple of quality-of-life improvements and now allows you to quickly start a sync after entering a message by simply hitting Ctrl+Enter while the input field is still focused.

On top of that if there are no local changes to be synced, or you don’t have any selected, you can now manually pull in the latest remote changes, which saves you a reload of the app, or closing and then reopening a project.

No More Preview-Tab Mess

Speaking of quality-of-life improvements, if you open the live-preview of a content item in a new tab or window, that tab or window will now be automatically closed once you exit out of the editing-view for that piece of content.

Uploads in File Fields can be Disabled

Up until this version, users were able to upload new files in file fields by default, which wasn’t always wanted (for example in case a user was only supposed to pick a file from an existing pool). This release introduces a new allowUploads option for file fields, which by default is set to false. This means that if you were relying on being able to upload files straight from the file picker, you have to update those fields and manually enable the option for them to be able to continue to do so.

Of course, you can always set the root option of the file field to the location of your Media Library, or a folder within it, so you and your collaborators can still upload files via the Media Library without setting the allowUploads option. This has the added benefit of being able to have finer control over who can upload files via Permissions.

Global Maximum Upload Size

You can now specify a maximum upload size in the Media Library tab of the project settings. If this value is set, files larger than that amount won’t be able to be uploaded to the Media Library or via file fields.

You can use the validation.max property on image and file fields to override this value on a per-field basis, as fields will prioritise their own validation options over the global setting.

Folder Creation During Media-Upload

If you upload a new image straight from an image field, you’ll now be able to also create directories straight from that modal. This saves you the trouble of having to manually do so in the Media Library first and can for example come in handy when grouping media files by year.

Shallower Localised Fields

Localised fields allow multi-language content to reside in the same file for easier localisation. Language fields can be used to specify what languages the content is available in.

In this new release, localised fields will no longer open in a modal if only one language is enabled for that piece of content, saving you and your collaborators a few clicks and making the UI less cluttered.

Images in Rich Text Fields

I saved the best for last, because this feature is definitely the MVP of this release—and the reason it took so long until it came out. As it turns out, adding images to rich text the right way was far more difficult than I initially estimated, but I think I’ve come up with a good solution for now.

Up until this version, the image block-format for rich text fields only existed for show—it actually had no functionality. This changes now, making Mattrbld much more viable for blogs and websites that feature images embedded directly into their text content.

Every rich text field with the image format enabled will show a new option (and allow the keyboard shortcut Ctrl/CMD+Shift+I to be used) to add an image from the Media Library inline to its content.

Depending on whether the field is set to output HTML or Markdown, the image will be added in different ways. The HTML mode will output the image as a <figure> tag containing an <img> tag and optionally a <figcaption> if the new option allowCaptions is enabled. The Markdown mode will use the standard image syntax (![]()) padded by blank lines.

The real magic, however, happens after an image was inserted into the editor, as you will then be able to specify the attributes of said image. If the field is set to output to Markdown, or if the Advanced Media Library is not enabled, you will only be able to specify an alt and a title attribute.

If, however, the Advanced Media Library is active, you’ll be able to set all the properties you have defined in the Schema, and any non-standard properties will be added as data- properties to the image. This allows you great flexibility for post-processing the content in your static site generator.

Adding a caption field to your Advanced Media Library schema will prefill the caption of images with that value, but you can always override them in the content itself.

To edit the attributes of an image in content, simply select it and either use the keyboard shortcut or the button in the editor-toolbar to do so, just like you’d do for a link. This will also allow you to replace an already placed image with a different one.


You can find a detailed list of bugfixes in the changelog, but some notable fixes include:

  • Proper validation of nested image fields in the Advanced Media Library configuration

  • Proper slugification of file and directory names when uploading them to the Media Library

  • Fixes so the paths in drafts match the final paths when published

  • Newly created, empty folders can now be synced since they are created containing a hidden, empty .gitkeep file

Next Steps

Like I mentioned above, I’m going to do my best finishing the documentation before the end of the year, although I don’t exactly know how much time I’ll be able to dedicate to Mattrbld in the coming months.

On top of that, I’m working on the integration of comments for the live-preview, which should make collaboration even more productive. As that is a complex feature, I don’t have an exact timeline for its release yet, however, so there may be more bugfix releases and some work on the mobile version especially surrounding the rich text editor and popovers in between.

In the long run, I’m also still planning on open-sourcing the code of Mattrbld once I feel like it is ready for the eyes of potential contributors.

I’ll make sure to publish another one of these devlogs (or a different kind of blog post) once there’s something significant to report—but until then you can always reach out via Twitter or Mastodon with questions and comments and read the changelog in the “News & Announcements” section of the project dashboard to keep yourself updated on the latest changes.