Introduction

Welcome once again to Mattrbld and this documentation. Here you’ll find everything you need to know to work with the application and then some!

Each section is centred loosely around a specific topic broken down into multiple articles, which themselves may have further reading materials categorised under them. While everything is structured in such a way that you should be able to read it from start to finish, feel free to jump straight to the sections that are most relevant to you, especially if you’d just like some more information on a specific topic.

While this documentation is certainly geared more towards people setting up Mattrbld for themselves or clients and as such can be a bit technical at times, it also features some sections relevant to active users of Mattrbld, i.e. content editors. It’s also a great place for all who simply wish to learn more about and understand how Mattrbld works behind the scenes.

What is Mattrbld?

Mattrbld is a headless, git-based content management system (CMS) that leaves you in control. Most people are likely going to use it for creating and editing the content, i.e. text, images and structure of websites and blogs, but it’s not limited to that. It can also be used for managing content for podcasts, games, etc.—any collection of data that even non-technical users should be able to edit easily. Your imagination is the limit.

It’s Headless

In fact, headless means that Mattrbld is not responsible for how the content you manage with it is presented. It only needs to know where to store data and how that data is supposed to look. This will then allow you and your collaborators to freely edit that data with a customisable and intuitive UI, but Mattrbld will not process the data further.

This means that Mattrbld is not aware what the data will be used for, to it it’s just data, not a website, podcast or whatever else—that’s what makes it so flexible! You should be aware, however, that on its own, Mattrbld is not very useful. There should always be something consuming the data managed through Mattrbld to have a complete product.

On the other hand, this separation has the added benefit of the content not being tightly tied to the presentation, which makes it much easier to change and iterate on both aspects independently.

It’s Git-Based

Git is a version control system that is widely used when developing software. It stores the source-code of a program and allows many people to collaborate on it. To ensure that that works as smoothly as possible, it keeps track of who changed what so changes can easily be undone and any possible conflicts can be minimised and resolved transparently, should they happen.

Git-based refers to the fact that Mattrbld reads the content it manages from a Git repository and saves any changes back to it, instead of say a database. This allows you and your collaborators to reap all the benefits of a version control system without having to intimately be familiar with Git and its many commands.

It also means that your content can live right alongside the source-code of your project, for example a website. This keeps everything neatly grouped together and makes it easy to move it between places—and as an added bonus content is stored in plain files, which are much easier to work with than if they were stored in a database.

Since Git is open-source and built with decentralisation in mind, you are also not tying yourself and your project to a particular company, which can be a great benefit—more on that in a bit.

It’s Flexible

Mattrbld was also designed and built with a great degree of flexibility in mind. It’s meant to be custom tailored to the needs of your particular projects, which is why it offers a wide range of customisation options and settings.

This approach makes the initial set-up of a project a bit more complex, but it also allows fine control over how exactly Mattrbld should behave in the context of a particular project and how the content it manages is structured and what it needs to look like to be valid.

Aside from very few core assumptions, you are free to not only use the directory structure that best suits your project, but also customise the controls of Mattrbld’s user interface as you see fit.

It’s a Progressive Web App

While at first glance Mattrbld might appear like any other website you visit, it’s in fact a so-called progressive web app, or PWA for short. These are a new type of application that are built using web technologies and run in a browser, but can also be installed to your device, be it a personal computer, a tablet or a smartphone.

Like other PWAs, Mattrbld is also able to run completely offline—although you won’t be able to import new projects or synchronise changes while you’re offline since that would require a connection to the remote Git repository. This means that you and your collaborators are able to work on your content even in areas with spotty coverage or while on a plane. Just keep in mind that if multiple people work on the same project the risk of inadvertently causing conflicting changes is greater when working offline.

It’s Decentralised

Last, but very certainly not least, Mattrbld is meant to be decentralised. You will not need to create an account to use Mattrbld. You are free to use any Git provider you would like, or even host your own Git server. In fact, it will even be possible to host your very own instance of Mattrbld in the future—which is easy since Mattrbld only requires basic web hosting without any special server components (although there’s one small gotcha) itself.

I believe that your content should be your business, not mine. So Mattrbld is just a tool to manage content, nothing more and nothing less. I don’t want to lock you into my tool or force you to only use specific Git providers with their own proprietary APIs. I don’t want access to your repositories or be able to see exactly what you do with them.

This approach has its drawbacks, but I believe it is the right one that gives you the control over your data that you deserve.

What It’s Not

While Mattrbld certainly can be a lot more than the points outlined above depending on how you choose to use it, there are some things that it is not.

It’s Not an All-In-One Website Builder

Some people equate the term CMS with services like Wix, Squarespace, or even something like Webflow. These tools allow users to build websites without having any development knowledge by simply dragging and dropping predefined building blocks and then editing their contents. Mattrbld is not one of those, Mattrbld just manages content.

While you could certainly create a similar experience (minus the inline-editing of content) with Mattrbld and an external service that transforms the data into a website (such as a static site generator) that still requires some development knowledge of the person who builds that external service.

In short: you can obviously use Mattrbld to manage the content on a Website, but Mattrbld doesn’t generate Website code, just the data that can then be turned into a website by a different tool.

It’s Not a Drop-In Replacement for a Traditional CMS

Mattrbld also isn’t a drop-in replacement for something like WordPress, Drupal, etc. In those systems, content and presentation are often quite heavily dependent on each other, so you couldn’t take say a WordPress Website and suddenly manage its content in Mattrbld.

To do so, you’d have to re-create a lot of it from scratch with the concept of a headless CMS in mind, for example by using a static site generator that can consume the data Mattrbld outputs for the website itself.

If however you are already using a (git-based) headless CMS for your content and want to try out something new, Mattrbld should be easy to integrate with your existing system. Just give it a try. 😉

It’s Not Trying to be the One and Only

Mattrbld is not unique in the sense that there are plenty of other headless CMSs out there, even git-based ones. Sure, Mattrbld has some unique features and principles that I personally think are very important for what it is, but surely some people would disagree.

Choosing the right content management system for a project is a little science in itself. There are plenty of options and Mattrbld is one of them. In the end, you have to decide what the right fit is and Mattrbld is certainly not trying to be the only tool for any job. There will always be things where it’s better or worse than other tools. That’s just the way it is.

Moving On

Now that you have a rudimentary understanding of what Mattrbld is and is not, you should already have a sense of whether or not it is the right fit for your project. To help you make a decision, the next three articles in this section will give you an overview of what makes it different, how it works and what its limitations are.

Thank you for giving Mattrbld a chance and I hope you’ll enjoy your stay! 😊