Collections

While Schemas describe the shape of individual pieces of content, Collections determine the properties of groups of content. Collections control in what folder items are stored, which Schemas they may have, what format the files have, if and how they should be linked internally and who can perform what action within that Collection.

In this article, you’ll learn more about all of these options and most importantly where and how to create Collections for your own project.

Creating a Collection

You don’t have to be a designer to create your very own Collection. 😉 Simply head over to the Collections tab of the project settings. Here you’ll be able to create a new Collection by clicking the “Add Collection” button in the top right.

Unlike almost all other types of content and configuration files, Collections cannot be stored in sub-folders. All of your Collections live as top-level JSON-files in the .mattrbld/collections folder and can still be created and edited manually in a text editor.

After giving your new Collection a name and creating it, it will show up in the list of available Collections and should immediately be selected, which causes its details to appear in the panel to the right (or an overlay on devices with small screens).

This details panel is split into three sections, “Content”, “Linking” and “Permissions”.

Content

In the “Content” section you are able to pick where the content items of this Collection live on the file system. For example, you might have a folder called “content” in your repository that contains two sub-folders “pages” and “posts”.

Picking the “content” folder as the content directory for your Collection would allow Content Editors to create files in both the “pages” and “posts” folders. If you instead set it to the “pages” folder, Content Editors would only be able to access content in that folder and any of its sub-folders.

Since you can assign multiple Schemas to one Collection, both options are viable, but it is a common practice to have an individual Collection for each individual type of content, i.e. in this case one Collection for “content/pages” and one for “content/posts”. This becomes a necessity if your pages are stored as JSON files and your blog posts as Markdown files, since a Collection may only have a single content type.

The Content type determines the type of file content items in your Collections will have and how Mattrbld will serialise the data. You can learn more about what file formats Mattrbld supports in the dedicated article on the subject.

Allowed Schemas allows you to select one or more Schemas that are valid for content items in this Collection. Just choose the ones you want from the dropdown and they will be added to the list where you will be able to rearrange and remove them again. Every Collection needs to have at least one allowed Schema for content to be editable.

If a Collection has just one allowed Schema, it will be automatically assigned to all files in that Collection upon creation, or the first time any pre-existing file is opened. If there are multiple, Content Editors will have to choose which Schema should be applied to the content item they created or are editing.

Linking

The “Linking” section allows you to choose whether or not content items in that Collection should be able to be linked to. It makes sense to activate this option for something like pages or blog posts, but you might also keep other types of editable content in Collections, such as authors or team members that wouldn’t necessarily have their own page that could be linked.

If the toggle is activated, you will be able to define a custom URL template for that Collection, which would then be used to generate the internal URLs to content items within it in Link and Rich Text fields with links enabled. These URL templates are a powerful tool for you to make sure that internal links match the URL structure of your project and will be discussed further in their own article.

If you have multiple languages enabled for your project, you will be able to set an individual URL template for each language. If you don’t, the first non-falsey value will be used. If none are specified, the path of the file in the project without a file extension will be used as a fallback.

Permissions

Last, but not least, there is the “Permissions” section, which allows you granular control over what role is able to perform what action in the context of that particular Collection. By default, everyone will be able to do everything, but you might want to lock that down depending on your needs. You can learn more about the subject in the Permissions article.

Quick Recap

Collections determine how and where content items are stored and what Schemas the data of each item has to conform to. They are created and edited in the Collections tab of the project settings. Once created and configured, you’ll be able to add them as entries to your project’s Sidebar and start managing the content they manage.

In the next article, you can get an overview over what types of content files Mattrbld supports at the moment, or you can skip ahead to the article on URL templates or get started with multi-language content if you choose to.