Quickstart Guide

In this article, you’ll learn how you can add Mattrbld to a simple personal blog. Along the way we’ll talk about many of Mattrbld’s core features so that by the end of it you should have a clear idea whether or not Mattrbld is the right fit for your projects.

Overview

Mattrbld is a git-based, headless content management system (CMS). It can be used mostly like the big names WordPress, Drupal, Typo3 etc., but it works very differently and is much simpler. Other sections in this documentation go over it in more detail, but for one, Mattrbld doesn’t deal with how the content you manage within it is presented—hence why it’s headless.

All Mattrbld does is manage content, what you do with that content is up to you. It doesn’t have to be a website (although that’s the example used in this article and probably one of the most common use-cases), it could be an app, a podcast, a game—anything that deals with content that needs to have a specific shape and has one or multiple editors that don’t want to learn how to code just so they can change some text here and there.

Mattrbld also works on your device as much as possible, there’s no database on a central server somewhere that Mattrbld constantly needs to talk to. In fact, after you’ve imported a project, you’ll be able to work on it completely offline until you want to synchronise those changes.

You (and any potential collaborators) still want to be able to access your content from different devices, however, so that’s where the git-based part comes in. It means that Mattrbld stores all your content in a Git-repository, which in turn is most likely being hosted on a server somewhere, so you and your collaborators can access it from anywhere. Mattrbld does not use any proprietary APIs to communicate with the repository, just plain old Git, so theoretically any Git provider will work (practically there are some limitations, but that’s a topic for another section).

Quick recap: Mattrbld isn’t a tool to build a website like Wix, Squarespace, etc., it’s a tool to manage content (which can be displayed on a website or somewhere else entirely). This guide shows you how to manage the content on a simple blog, since that’s likely one of the most common use-cases.

Prerequisites

While using Mattrbld doesn’t require technical knowledge, setting up a project is an advanced task that should probably be performed by someone who has a good understanding of how the content will be presented. As such, being a developer is a big advantage, although not strictly necessary.

If you would like to follow along with this guide you’ll need the following:

• A Git repository on a server (for example at GitLab or GitHub)

• The right to push to that repository

• Optionally, an Access Token with repository read / write access from your Git provider in case your repository is set to private

• Optionally, a static site generator (SSG) that can fill a template with data from a Markdown file (for example Astro, Gridsome, VuePress, or Gatsby, although there are many, many more to choose from)

Mattrbld doesn’t enforce any specific directory structure, but for simplicity’s sake we’ll use the following:

my-first-mattrbld-project
├── .git
├── content
│   ├── posts
│   └── uploads
├── src
│   └── (files and folders relating to your SSG)
└── (other files)

Only the content folder and its two sub-folders posts and uploads will be relevant, the others are just meant for context.

Onboarding and Initial Setup

If you’ve never opened Mattrbld before, you’ll be greeted by the Onboarding screen, which will allow you to import your first project and create your local user profile.

Importing the Project

To import the project, simply paste the URL of the Git-repository you want to use into the text field and press Enter or click outside of it.

This will then fetch a list of branches and attempt to guess the default one for you, usually master or main. If that’s not the branch you’d like to work on, feel free to select the right one from the dropdown.

Clicking on “Import” will then start cloning the repository and take you to the next step, or ask you for your Git credentials in case the repository is set to private.

Creating Your Local User

While your repository is being cloned, you can set up your local user profile. This information is only used to sign the changes you make in Mattrbld when you push them back to the repository. It’s also a great way to keep personal projects separate from your work projects by using your private email for one and work email for another local user.

Mattrbld doesn’t care what information you provide, so long as you provide it. It’s never sent to anyone but your Git-provider—but your team members and your Git history would probably appreciate if you used correct details.

If you’d like, you can also add an avatar image for your profile, or just go with the one generated for you. This image will be shown in the top right of the interface so you always know what profile you are in, as well as in the “Recent Updates” section of the dashboard if you made any changes to a project recently.

Finishing Up the Onboarding

By the time you’ve decided whether or not you want to upload a profile picture, the project should be fully imported and ready to be set up. If not, just wait until the progress bar is full and you see the option to proceed to the project setup.

Project Setup

Since this repository was never imported to Mattrbld before, you’ll be taken straight to the project settings, where you can perform the initial setup of the project. Had you imported a project that was already set up to work with Mattrbld, you would’ve been taken to the dashboard instead.

In the General Settings section you can enter a more specific name for the project, as well as upload a custom thumbnail image for it. The other options are pretty self explanatory and out of scope for this article.

Quick recap: we have imported the project from a Git-provider to Mattrbld running on your local device and completed the onboarding process by creating a local user profile.

Defining Your First Schema

With the initial setup out of the way, it’s finally time to think about what information our blog posts should include. It could be anything, really, but for our simple example the following details should be enough:

• A title

• A hero image

• A set of tags

• An author

• A publishing date

• The content of the post (duh!)

This list is basically a schema that every blog post will stick to. On our website, we can use these details to display the post itself, obviously, but also for sorting all posts by publishing date or author, for example, or have our SSG automatically generate a page for each tag that contains all posts that have said tag—Mattrbld doesn’t care, it just needs to know what data content editors need to input to create a valid blog post.

Schema Creation

The Schemas tab is the right place to turn the above list into a proper Schema. Simply click the “Add” button and give the Schema a name, “Blog Post” seems fitting, but you could call it anything you want. Mattrbld automatically makes sure that only safe characters are used in filenames, hence why the file might not be created with exactly the same name you typed.

Schema Editing

Once you’ve created the Schema, you’ll be taken to the Schema Editor, a visual drag-and-drop editor that allows you to intuitively translate the list above into a proper Schema. To do so click “Add Field” and you’ll be presented with an extensive list of built-in fields.

Each of these fields has a different function and presents content editors with a different input field once they create and edit actual content. For this guide we’ll only be looking at five of these fields:

• Unformatted Text (for the title and author of the post)

• Rich Text (for the content)

• Date (for the publishing date)

• Image (for the hero image)

• Tags (for the tags)

Try adding a Unformatted Text field by either dragging it into the dropzone on the left, or clicking the “plus”-icon next to it.

Congratulations! You’ve just added your first field. If you now click on it, you’ll see all of its options. Each field has a set of options common to every field (like label and key, validation and visibility options, etc.) and some that are unique to that type of field.

Basic Configuration

Let’s turn our Unformatted Text field into the title field for our Schema by changing its label to “Post Title” and the key to “title”. As you might’ve guessed, the label is the actual label that will be displayed above the field when creating or editing a blog post. The key, however, is what the field will be saved under in the actual blog post file.

This separation allows you to define descriptive labels for content editors, while keeping things clean and concise in the data structure (or conforming to conventions / requirements imposed by the program consuming the content, for example your SSG).

Unformatted Text fields are pretty simple fields, the only options unique to them are the wrapping and line-break options. Since the titles of our blog posts won’t need to have multiple lines, you can leave the “Allow line breaks” option off. The titles are probably also not going to be very long, so we could also disable the “Wrap the text if it’s wider than the input field” option, but considering Mattrbld also works on mobile phones, the input field could end up being quite narrow, so it would be beneficial to content editors if this option was left on and the could see everything without having to scroll within the input field.

Adding Validation

What we do want, however, is to mark the title field as required, since every blog post should have a title. To do so, simply toggle on the “Make this field required” option in the “Validation” section. Here we could also specify some more granular requirements like minimum and maximum length, but they won’t be necessary in this case.

Rinse and Repeat

Adding the other fields works exactly the same way, just click “Add field” and add and configure the remaining fields:

• Image (label: Hero Image, key: hero)

• Unformatted Text (label: Author Name, key: author)

• Date (label: Published at, key: date)

• Tags (label: Tags, key: tags)

• Rich Text (label: Post Content, key: content, Output format: Markdown)

While the keys of the other fields don’t matter much in this specific example, the Rich Text field must have the key content. This is because we want to save our blog posts as Markdown files with a frontmatter—a common format for many SSGs.

So Mattrbld knows which of the fields in a Schema holds the information that is supposed to be added after the frontmatter, i.e. as the body of the Markdown file, we need to give one of our fields the key “content”.

While configuring the Rich Text field, you might also have noticed that it allows for some quite extensive customisation options. This is so designers and developers can closely control what type of text formatting can be used in these very versatile rich text fields. For this example, the defaults should suffice, except for the fact that we obviously want the output to be Markdown instead of plain HTML.

Saving the Changes

Once you have everything set up, click the “Save” button in the top right to save your changes and then close the Schema Editor by either clicking the back-arrow on the top left, or using your browser’s back button.

You will return to the “Schemas” tab in the project settings and see your brand new “Blog Post” schema displayed in the list with a small orange dot next to the name. This dot shows that the file has local changes that have not yet been pushed back to the central Git-repository—something we’ll deal with once everything has been set up.

Quick recap: so far, we have come up with a set of properties we want all Blog Posts to have and then proceeded to turn that list into a Schema with the appropriate types for each property by using Mattrbld’s predefined fields.

A Collection for Our Posts

Now that the Schema for our blog posts has been created, we need to tell Mattrbld what type of a file a blog post is and where to save it. This happens in the Collections tab.

A Collection is a folder of files with a specific type (at the moment Mattrbld supports JSON and Markdown) in a specific location. Each of these files follows a certain Schema and can optionally be linked to from other files under a customisable path. Collections can also finely control what different types of users can and cannot do within a Collection. This allows you, for example, to let all content editors create and edit files, but not delete them, unless they have a specific role.

Creating a Collection

To create a Collection for our blog posts, click on the “Add” button in the top right and give the new Collection a name. “Blog Posts” seems like an obvious one, but it can be anything you like. Once you’ve done that, the Collection will appear in the list and be selected.

Collection Configuration

Whenever you select a Collection in this tab, its settings will show on the right (or in a modal window on mobile devices). Here you can configure the Collection to your liking.

Let’s set up the Collection for our blog posts. The “Content directory” dictates in what folder the blog posts will live. Click the selector and pick the “content” folder and then the “posts” folder within that, confirming with the “Pick this folder” button. You are free to create sub-folders in a Collection folder. Items in those will still belong to the Collection. That’s useful if you would like to group your blog posts by year, for example.

Next, we can set the file type of our Collection, like mentioned before in our case that will be “Markdown”, so select that. Once you’ve done so, you can also add the “Blog Post” Schema we created earlier under “Allowed Schemas”. If we had more than one Schema we could add multiple allowed Schemas to this Collection, which can come in handy if you have different types of blog posts for example, each with their own fields or default values.

Last but not least, you may enable the “Allow content in this Collection to be linked”, which will cause this Collection to show up in helpers for internal links, although this step is completely optional.

Linking Templates

If you enable that option, you will see a new input field labelled “URL template”. You can use this field to input a dynamic URL template for items in this Collection.

For example if your SSG generates the URLs for your blog posts based on their publishing date and title, you could enter the following:

/blog/:date[year]/:date[month]/:date[day]/:title/

This would cause a post titled “Hello World” published on May 16th 2021 to be linked to as:

/blog/2021/05/16/hello-world/

As you’ve probably figured out, the sections in the template prefixed with a colon (:) will be looked up in the content item itself. Remember how we gave the field holding the publishing date the key “date” and the title field the key “title”? That’s how Mattrbld knows what values to replace the dynamic segments in the template with. Had we given the date field a key of “createdAt”, the template would’ve had to be:

/blog/:createdAt[year]/:createdAt[month]/:createdAt[day]/:title/

Since Dates are a bit more complex than simple strings, Mattrbld allows you to select specific parts of the date with the syntax seen above.

On top of looking up the dynamic sections, Mattrbld also makes the values safe for use in a URL, a process sometimes referred to as “slugification”. That’s why “Hello World” turned into “hello-world”, since spaces are not allowed in URLs and they are typically lower-case (although that can be configured).

All non-dynamic parts of the URL, such as the slashes and the “blog” are taken as-is (so be careful they don’t contain any invalid characters!). This allows you to perfectly model URLs to the shape required while also giving content editors an easy way to create internal links between content items.

Saving the Changes

Collections are automatically saved whenever you change them, so there’s no need to save them manually. Simply close the Collection by clicking the little cross icon in the top right or by clicking it in the left column and you’re done.

Quick recap: after creating our Schema, we created a Collection for our blog posts and picked a folder where to save them, as well as assigned the “Markdown” file type and “Blog Post” Schema to this Collection.

Configuring the Sidebar

Now that we have a Schema and a Collection, we’re theoretically ready to write our first blog post! But how do we get to our newly created Collection so we can add a file?

Well, for that we need to set up the sidebar of the project, which can be done in the Sidebar tab, or by simply clicking on the “Configure sidebar” button in the sidebar itself.

Creating a Sidebar Entry

To create a new entry for the sidebar, simply type a name (e.g. “Blog”) in the input field and hit Enter or click the little “plus” button next to it. This will create a new entry of the type “Heading” and if you now look at the sidebar on the left hand side of the application, you will see that the “Configure sidebar” button was replaced by a heading with the name you just gave it.

Editing a Sidebar Entry

But we didn’t want a heading, we wanted a link to a Collection! Lucky for us, changing the configuration of a sidebar entry works just like editing a Collection in the previous step: simply click on the entry and its options will show up in the panel to the right.

Depending on the type of the entry, you’ll see different options here. As we can see, at the moment it’s a “Heading”, but we want it to represent a Collection, so select that from the “Type” dropdown in the “Functionality” section.

Two new fields have appeared: “Icon” under “Appearance” and “Target” under “Functionality”. By default, Collections are represented by a folder-icon, so that’s what’s shown if the “Icon”-field is empty, but you’re free to select any icon you wish to represent the Collection in the sidebar. For our blog maybe the “text-alt”-icon would be the right fit?

Much more important than the icon, however, is the “Target” option—this is where we tell Mattrbld what to do when the entry is clicked. In our case we want it to open the “Blog Posts” Collection we previously created. So click that field and select the Collection from the list.

Only once you did that will the entry in the sidebar change from the heading to a button with the selected icon and the entry be saved.

Other Entry Types

As you probably saw, the entries in the sidebar can also be “Documents” or “Content Items” in addition to “Headings” and “Collections”.

A Document is a Markdown file such as your README.md which can be used to display rendered Markdown within Mattrbld, for example if you would like to write some documentation specific to the project.

A Content Item is a direct link to an existing content item. This is useful if you would like a quick link to say your Home-page without first having to look for it in a “Pages” Collection. If you frequently change a specific content item, it probably makes sense to add it to the sidebar like that.

Feel free to add as many entries as you like to really make the sidebar your own. Using headings is a great way to split it into multiple sections such as “Content” “Documentation” and “Metadata” for example!

Quick recap: once we had a Schema and a Collection, we added an entry for the it in the sidebar so we can easily reach it and create and edit content.

Enabling the Media Library

Before we write our very first post, let’s take care of one last thing. As you recall, we added an “Image” field to the Schema to be able to add a hero image to our posts. But where is Mattrbld supposed to look for that image?

In Mattrbld, all media files, such as images, videos, but also PDFs, and Archives such as ZIP or RAR files live in a single folder (and its sub-folders) referred to as the Media Library.

The Media Library is a special kind of Collection that groups all the media files in one central place and allows you to manage and pick them from there through Image fields. All you need to do to configure it for this example is click the file input labelled “Upload directory” in the Media Library tab and click the “content” followed by “uploads”, again confirming your selection with the “Pick this folder” in the end. Now all files uploaded through the Media Library will be saved there and clicking on an Image field will allow us to select an image from that folder.

The other options such as the output directory, permissions, and the advanced media library are out of scope for this guide, so let’s ignore them for the time being.

Quick recap: we created our Schema and Collection and made it accessible by adding an entry for it in the sidebar. To be able to upload and pick images through Image fields such as the hero image for our posts, we then configured an upload directory in the Media Library settings.

Writing Your First Post

Phew, it’s been a lot of hard work, but Mattrbld is finally set up for some content editing! Click on the “Blog” sidebar entry we created earlier and you’ll be taken to the overview page for the “Blog Posts” Collection.

Here you can add sub-folders to organise your content, as well as create new blog posts via the familiar “Add” button. Click it to create your first blog post! Give the file a name—it doesn’t really matter what, but it probably makes sense to call it something relevant to the post, how about “Hello World”?

Similarly to when you created your first Schema, you’ll be taken to a new screen after creating your first post. This is the Content Editor, where you’ll be able to work on your content.

Here the fields of your Schema are used to generate a form for you to put in the relevant data for this particular post. There’ll be a text input field to add the title of the post, an image field for the hero, another text field for the author’s name, a date picker for the publishing date, a tag input for the post’s tags and last but not least a fully featured rich-text editor for writing the contents of your post.

Feel free to try around and experiment with the fields, maybe even write some content, but don’t focus the “Post Title” field just yet! Once you’re done, click the “Save” button in the top right.

Uh-oh! There was a warning and now the “Post Title” field is highlighted red and the “Save” button is disabled. That’s because Mattrbld validates your content before you save it to ensure it conforms to the rules set out in the Schema. If the content is invalid, you won’t be able to save it (unless it’s a draft, but we haven’t enabled those).

Remember how we marked the “Post Title” field as required in the Schema? Since we didn’t add anything to it yet, the content is technically invalid and only once you’ve added something will you be able to save. This way you can ensure that nobody forgets to add important fields or accidentally creates content that is invalid and could cause errors somewhere else.

Now add a post title, save and use your browser’s back button or the “arrow” button in the top left to return to the “Blog Posts” Collection. Congratulations! You’ve written your first piece of content in Mattrbld! 🎉

Quick recap: after creating a Schema and assigning it to a Collection, we configured the sidebar to show that Collection and enabled the Media Library. Then we used the sidebar to get to our Collection and added a first piece of content, which we edited and saved.

Syncing Your Changes

As you can see, the new post also has the little orange marker showing that it has local changes. And if you look near the top of the sidebar, you’ll also see an orange label with the word “Changes” written within it. This is a reminder that you have unsynchronised changes on this particular device.

So now all that’s left is to push them back to the remote repository! To do so, head to the project dashboard with the button in the sidebar.

The Dashboard is the central location that displays everything going on with the project. You’ll see how many local changes you have along with a button to synchronise them. There also is a “News and Announcements” section that shows the current version of Mattrbld by default, but can also be used to broadcast messages to all collaborators of a project. Below that you’ll see a list of recent changes and who made them, as well as a list of your locally changed files at the bottom.

Synchronise!

Clicking on the “Synchronise” button will open a modal showing you an overview of all the files you have added, removed or modified since the last time the project was synced.

Here you are able to select which changes you would like to synchronise, as well as see what exactly changed within a file, or even discard those changes if you changed your mind or edited something by accident.

For now, make sure all files are selected and type a descriptive message in the field above. This will be your commit message, telling your collaborators (and your future self) what you did in this particular round of changes. For example “Add Mattrbld configuration and a first blog post”.

Once you’re happy with your message, click “Sync 5 changes” and the synchronisation process will start. If your repository was set to public, or you didn’t opt for saving your credentials for the session, you’ll be prompted to confirm your identity and right to push the changes by authenticating with your username / email and password for your Git-provider.

After the sync has completed, you’ll see a quick toast-notification about it at the top of the screen and if you check the repository on your Git-provider’s website you’ll see that it now contains a .mattrbld folder (which houses all the Mattrbld related configuration such as your Schema and Collection) and your brand new blog post in the content/posts/ directory.

Whoop whoop! 🎉🥳

Conclusion

By now you should have a pretty clear idea about how Mattrbld works and what its core features are. Of course, there’s much more to discover, but this is the gist of it. You create Schemas for your content, which lives in Collections. You can tailor a project’s sidebar to precisely fit your needs and sleep peacefully at night knowing that the content created and edited through Mattrbld will always adhere to its assigned Schema.

As you saw, changes aren’t immediately pushed back to the central repository like in other git-based CMSs. Instead you control what gets pushed when, which is crucial when you would like to avoid any unnecessary runs of your CI pipelines.

Speaking of which, to really turn this guide into a functioning blog, you would probably want to set up a CI/CD service that uses your static site generator to generate a new version of the website and publish it to your host every time content was added or changed and synced with Mattrbld.

With a setup like that, Mattrbld can function just like more traditional CMSs, with a lot less costs and much better security. If you’d like to learn more about this way of building and managing websites, feel free read up on the Jamstack.

Otherwise, have a look through the other sections of this documentation or take a well-deserved coffee-break. 😉 Keep building great things!