Drafts

Sometimes it may be desirable to work on and sync content that is not immediately used in the project. For example a blog post you start on your phone, but would like to edit and flesh out on your computer at home, or a new team member that still needs to have their picture taken and thus cannot be displayed on the “Team” page of your website yet.

You could, of course, simply add a toggle field to your Schema and filter content based on the value of that field while building your project, but that wouldn’t be very practical, considering it would still cause your CI/CD pipeline to run whenever you sync your content, even if your project doesn’t need to be rebuilt.

That’s why Mattrbld comes with a built-in way to handle content drafts and in this article you’ll learn how it works and how it can make your life easier.

Enabling Drafts

As described in the article on project configuration, drafts can be enabled in the General Settings of your project. For them to work properly, you will also have to provide a folder to store your drafts in. By default this will be /.mattrbld/drafts, but you can choose any location within your project. So if for example your static site generator has a specific folder for drafts by convention, you can choose that.

Once this folder is set, all content items within the project can be marked as a draft either via the toggle in the content editor, or from the context menu in a Collection.

You will also be able to specify whether new content items should always be created as drafts on a per-Collection basis. To do so, simply toggle the option for the respective Collection in the Collection settings.

There are also special permissions to control who may publish drafts within a Collection, for example when you want new content to go through an approval process before it can appear in the published product.

How It Works

Whenever a content item is created or marked as a draft, the file gets moved into a sub-folder of the drafts directory. This sub-folder will be named after the content directory of the Collection the content item belongs to. I.e. if the content directory for a “Posts” Collection is /content/posts/ and the drafts directory is /.mattrbld/drafts/, the respective folder for draft posts would be /.mattrbld/drafts/posts/.

Conversely, if a draft is published, its file is moved from the drafts directory back into the content directory of the Collection it belongs to.

Effects on Synchronisation

If drafts are enabled for a project and files in that folder are included in a synchronisation operation, Mattrbld will create two separate push events instead of one. It will first commit and push all the changes in the drafts folder, appending “(drafts)” to the commit message, and then commit and push all other changes separately.

This is done so you can configure your CI/CD pipeline to not run when there are changes in the drafts directory, for example with rules on GitLab CI, to avoid wasting resources unnecessarily.

Benefits of Drafts

Since everything you do in Mattrbld is local to the device you’re on by default, using drafts is an excellent way to sync unfinished content between devices without affecting the public version of your project at all. Drafts are also perfect to have some sort of approval process for new content by making content for specific Collections drafts by default and restricting which roles are allowed to publish drafts.

Moving On

This article concludes the section on working with content. You have had a general overview of the most important parts of the Mattrbld UI, learned how to create and edit content and sync those changes back to the central repository.

The next section will teach you all you need to know about the Media Library and how to use its advanced functions to make your own and the lives of your team members easier.