Core Principles and Features

Illustrated drawing of Amadeus Maxmimilian StadlerIllustrated drawing of Amadeus Maxmimilian Stadler

Amadeus Stadler

Last updated August 29, 2021

Like Mattrbld itself, this article is a work in progress. Please excuse any missing links or unfinished content.

This article highlights the principles at the core of Mattrbld, which lead to a set of features that distinguish it from other solutions available. While Mattrbld fundamentally strives to deliver a familiar experience to developers who have worked with headless content management systems before, as well as for non-technical content editors who have used other CMSs before on the surface, it works a bit differently under the hood.

Read on to learn what sets Mattrbld apart from other git-based headless content management systems.

Independence and Decentralisation

Instead of creating and maintaining an infrastructure of servers and locking you into a proprietary system, Mattrbld only provides you with a graphical user interface to import your own content and manage it. By relying on an open standard such as Git, you are free to choose where to store your content, or even store it on your own infrastructure.

When you import a project, it only gets stored on your device, never on our end. In fact, if you use your own proxy server, or host Mattrbld yourself, your data and requests will never even leave your ecosystem. You don’t even need to grant Mattrbld blanket access to your entire Git account. Importing a project works just like cloning the repository to your local machine.

Your data is yours, Mattrbld is just providing you the UI to manage it. Even if you should ever decide to switch away from Mattrbld, there’s no need to export any data—it’s right where it always was: in your repository. Simply delete the configuration folder, do a quick search and replace to remove any Mattrbld-specific fields in your content and it will have vanished without a trace. There’s no account to delete, no data you would need to request be removed from our servers.

Even while using Mattrbld, you’re independent from it, everything you do in Mattrbld can also be done from a text editor—it’s just files after all.


Like mentioned in the Introduction, Mattrbld is meant to be flexible. It was designed and built to be able to map any content structure to a set of input fields, thus providing a clean and easy user interface for even non-technical users to create and manipulate content.

On the other hand, it’s also important that the data managed with Mattrbld can maintain its internal integrity, which is why there’s a number of ways for validating each field in a piece of content. Of course, you’re also able to set default values for each field and control what field shows up under which conditions.

While simple fields like simple text inputs only allow for few options, more complex fields like rich text editors make it possible to finely tune what formats, levels of headings and even types of links are allowed within them. You are also able to freely combine and configure the default set of fields and save them as your own, custom fields which makes it even easier to create reusable building blocks that are managed from a central location.

This allows you to truly mould Mattrbld into an interface befitting your content and not the other way round.

User Centred

It should be a given, but sometimes it feels like it isn’t: the user should be at the centre of a product. In Mattrbld, there are two archetypes of users: developers and content editors. Each of them has their own needs and requirements and Mattrbld does it’s best to cater to both types.

Developers get as much control over the UI, content structure and editing experience as possible, at the expense of some additional complexity. Setting up a project for Mattrbld isn’t as easy as clicking a couple of buttons, advanced features like the realtime preview require some development knowledge, but in the end the degree of control and flexibility should be well worth the small extra effort.

Content editors on the other hand get an easy to use, consistent and intuitive UI to do their work. They can rest easy that the risk of accidental mistakes is minimised, so they can fully focus on managing their content without having to worry about breaking something. They don’t even need to understand Git and the concepts that come along with a git-based CMS, since those are abstracted away and presented with non-technical language.

Features like the ability to undo almost all destructive actions, an easy overview of local changes, previews, internationalisation and drafts benefit both groups. In the end, using Mattrbld should be a simple and delightful experience, no matter if you are a seasoned developer, or somebody who just wants to quickly change the headline on a homepage.


Mattrbld is not trying to re-invent the wheel, it’s trying to improve on already existing concepts while keeping the core experience familiar. Schema-based content modelling with built-in validation is not new, neither is the way these Schemas are transformed into a set of editable fields, but many existing solutions quickly devolve into a complex set of convoluted options where it’s hard to tell where one set of fields ends and another begins.

Mattrbld tries to alleviate that by introducing display-only headings and descriptions, as well as separators that can be used to visually group sets of fields without affecting the underlying data structure. Unrelated fields can even be moved to different tabs for an even better separation. On the other hand, tabs can also be used to group fields under a common key in the content structure—the choice is yours.

Custom visibility rules allow you to hide fields from users with certain roles, or under specific circumstances, for example if one field has a particular value or another is below a particular threshold.

This ensures that content editors aren’t overwhelmed by a sea of fields that might not even matter to their current tasks and goals, but the underlying content structure still contains all the required information.

Even Mattrbld’s overall UI doesn’t stray far from patterns established by operating system conventions and other content management systems—it’s intentionally familiar so content editors can focus on editing content without having to learn a new UI from scratch. Anyone who has worked with a CMS before should have no trouble managing content with Mattrbld—and even without prior experience the learning curve should be minimal.


Many other git-based content management systems push local changes back to the central repository as soon as they happen. This has benefits, since it minimises the risk of conflicts, but it can also be wasteful.

More often than not, the underlying central repository is watched by a continuous integration and delivery service (CI/CD) that runs tests or rebuilds a website whenever a push happens—even if the changes wouldn’t have an effect on the product, such as drafts or configuration changes. Every individual run, or even every single minute a CI pipeline runs, costs money and computing power, which consumes energy.

That’s why Mattrbld leaves it up to the user when they want to push their changes back to the central repository. That way, related changes can be grouped and split intelligently so that the CI pipeline can be configured to only run when parts of the content change that affect the final product. This approach, while requiring two additional clicks by the user, overall helps you to save time and money, as well as power.

And since all local changes happen on the user’s device and not a server, they can safely be performed without even needing an internet connection until they should be pushed back to the central repository! Ideal for writing a blog post while winding down on a beach somewhere or editing typos on a marketing page on the underground with a spotty connection.


As the world becomes more and more globalised and businesses expand beyond the borders of their home country, there’s an even greater need for multi-language websites. That’s why Mattrbld has internationalisation integrated at its core.

You are able to centrally define what languages your project supports and then mark relevant fields in Schemas as internationalised which allows content editors to specify that field’s value in all languages configured for that content item. This also has more subtle effects like automatically using the appropriate quote marks in rich text editors if “smart quotes” are enabled.

Feel free to check out the article on multi language content for more information on the concepts behind this feature. Please be aware, however, that Mattrbld’s interface elements are only available in English for the time being.


Especially in the context of blogs and websites, it can be highly beneficial to be able to create a piece of content, but not have it be published during the next push to the central repository, for example to continue an article started on a phone on a laptop at a later point in time.

However, static site generators handle drafts very differently depending on which one you choose, if they support them at all. For that reason and to maintain Mattrbld’s general principle of flexibility, you are able to freely choose a directory to save your drafts in, which Mattrbld will in turn manage and integrate with your different Collections of content.

To content editors, drafts and published content will appear in the same lists (although drafts are clearly marked as such), while the file structure in the back stores them in different directories so they can be cleanly separated during build.

On top of that, Mattrbld also makes sure to push drafts and other content using two distinct push events even when they are synchronised in a single action, so CI pipelines can safely be configured to not run when changes happen in the drafts directory without risking that published content won’t be updated.

To learn more about how to set up drafts and see example configurations for CI services, check out the article on drafts.

Live Preview

Last, but not least, it’s highly important to some content editors to be able to see what the changes they are making to a piece of content will look like once published. Unfortunately, getting content previews for headless content management systems, especially git-based ones, right is very hard, since by design content is decoupled from its presentation.

Some solutions require spinning up a development server on demand, while others depend on API servers that are able to provide temporary data. Others again just expect you to regenerate a rendered version of your changes on a temporary URL using their CI service. Each of these options has its own benefits and drawbacks, but usually ends up overly complex or feeling rough around the edges and untrustworthy.

Despite that challenge, Mattrbld was conceptualised from the start with an integrated content preview that updated nearly instantly as editors made changes.

To be clear: the solution is not perfect. There are inherent technical limitations to what can be done without relying on external servers, but if set up correctly, the preview in Mattrbld should in most cases be perfectly enough for seeing the new content in the context of the given presentation.

The section on content previews goes more into the technical details and how to set it up for your project. In summary, what happens is that Mattrbld establishes a connection with the presentation, for example a special route on your website. When content is updated, Mattrbld sends the new content to the presentation, which is then free to do with it as it sees fit, for example by rendering it with client-side Javascript.

This means that on one hand it’s only a preview of the content item currently being edited (i.e. other unpublished changes to menus, etc. won’t show up), but on the other hand it also leaves the developer in control. Since Mattrbld is not just for websites, this flexible preview system could for example be used to update the content of an electrical billboard, or generate downloadable imagery such as a business card and much more.

So while not the easiest to implement, this preview solution strives to be one of the most flexible, while also adhering to the core principle of independence and decentralisation and as such not requiring complicated external services or APIs. It even works offline if the initial connection was established before the line dropped!


Mattrbld strives to be an independent and flexible content management system that leaves you in control. While flexibility and complexity are proportional to each other, Mattrbld still aims to provide you and your collaborators with an intuitive and friendly user interface to accomplish your goals, without forcing you to renounce convenience features such as drafts and previews.

Continue with the next section for a technical overview on how Mattrbld works from a technical perspective.