Spiria logo.

Statamic, a flat file CMS

March 22, 2018.
The fetchingly-named Statamic is a neat flat file CMS built on Laravel. Compared to its closest competitor, October, Statamic seems more evolved. But let’s have a look.

First, a refresher on flat file CMSes. In theory, they do away with databases, all data being stored instead in simple, easy-to-understand text files. All you need is a server running the latest version of PHP, and since you’re not querying a database server, response times should be fast. Another advantage is that both code and content can be archived in a version control system like Git. What you see on your screen is static pages (unlike dynamic pages, built on the fly after any number of database queries).

There are many such CMSes: check out this and this list. Developed in 2012 by American company Wildeborn, Statamic is not free, costing US$199 per site. However, you can use it for free to develop a local site, just as long as you don’t put it up on-line.

Easy installation, spare and efficient interface

First off, installation is simple, as is the documentation. The company has provided a complete tutorial on YouTube. Dealing with this young team is fun; humor is the order of the day, even as they promptly respond to questions on Slack.

The default installation features a theme and a few pages, for quick familiarization with the tool.

Default Theme.

Redwood, the default installation theme as provided by Statamic. The CSS is built on SASS.

But you can just as easily start with a blank slate. A bunch of commands in terminal mode allow you to build from the ground up, from the theme to the fields associated with each page. To call up a list of commands, just type please. For example, “php please site:clear” clears out the site, including the theme. To rebuild a bare-bones site, just type “php please make:theme”. To create users: “php please make:user,” etc.

Terminal Commands

Some of Statamic’s terminal commands.

The interface is simple, pleasant to work with and easy to navigate. It has just three main sections: Content, Tools and Configuration (a complete French version of the interface came in as these lines were being written).

Administration interface.

The administration interface allows for mystery-free management. Everything is right there.

The interface

There are two main types of contents: Pages and Collections (i.e. texts organized as if for a blog). When creating content, users are offered multi-purpose templates (see below). This section may be a little confusing, because it does allow you to see Collections. So let’s look at the Pages section as the site tree.

Pages

The Pages section. You see two different Collections, which, unlike other types of pages, have a side menu for adding children.

Pages

Editing a page. Here, you just see the title and content (in markdown syntax). Fields are a function of the model chosen when creating the page. If you’ve made a mistake and want to change the model later on, you’ll have to modify the resulting flat file. Collections group pages under a specific template. You can create content with complex fields as if for a blog, or all manner of lists. But I’m not going to go into this feature, suffice it to say that the possibilities are endless.

Collection

The Collections section. In this example, there are two Collections.

Collection

The “blog” Collection

Collection

Editing a Collection page. Notice that in the example above, the content field is no longer in markdown, but rather benefits from Bard, a complex WYSIWYG editor.

A nice little feature is the live preview of changes made. This provides for a user-friendly interface for ordinary users, making Statamic a nice alternative to Wordpress.

Preview

Statamic’s preview feature

Besides page types, Statamic also provides media management, a taxonomy system, a nice little utility to create forms, and more. I especially liked the Media section and the ability to choose a focal point for each image, so that any image manipulation is automatically predicated on your chosen focal point. Cropping is coded in the pages template using the Glide integrated library.

The Media section.

The Media section.

decorative

Image management.

decorative

Select a focal point to keep your images compelling.

File structure

At first glance, file structure is just as simple. Content comes under content, themes under themes.

Tree

Statamic’s file structure.

The default syntax for text is in Markdown, hence the “.md” extension, though you can change this to the more common HTML syntax. But we’ll come back to this.

Types de page

Page types. For the “page” type, translations stay next to the original.

Since we’re dealing with flat files, you can create pages using your favorite editor, as long as you number them. File syntax is a mix of YAML and Markdown (or HTML, depending on your preference).

File structure

Writing a content file is easy. Start with the metadata between the “---“ symbols, including the title, the page template and the set of fields used. Then, insert the content.

File structure

Another example of a page. Notice the YAML at the beginning of the title. In this example, we have a title, a sub-title, a default image (this is a blog article), and the taxonomy. The unique page ID is automatically added by Statamic.

Page templates

Template construction is a two-step process. On the one hand, you have general layouts. These usually have a basic HTML structure. There are two default layouts: default.html and feed.html. The template_content variable calls up the actual content.

The layout tree.

The layout tree

Layout

The “template_content” variable calls up the entire content of all fields selected for the page.

Templates

In “template”, field layouts.

Where do the fields spring from? From the “fieldsets” in the Settings directory.

Each fieldset is a “recipe list” of fields (“fieldtypes” in Statamic lingo) in YAML. The simplicity (or complexity, depending on how you look at it) of the system allows you to configure a bunch of fieldsets outside the interface in order to share them between projects.

Fieldsets

The “fieldsets” directory.

Fieldset

Fieldset example.

Multilingual work

As mentioned earlier, translated files reside in the same directory as the original. However, you still have to create a separate directory, outside the content directory, for each separate language, which will be named according to the language code. These directories are in the root directory and contain the same index.php file as the basic site. Then you have to modify the variables within these files. This idea of duplicating index.php files does seem odd, and runs against the programmer maxim, DRY (Don’t Repeat Yourself). You must also configure the main configuration file, system.yaml.

Configuration

The main configuration file, where languages are defined.

Configuration

The “fr” directory must be created outside the content directory (which is in the “site” directory).

Another irritant: notice that, in the next-to-last image, the root directory for English doesn’t have “/en” in the URL. Though you should be able to add this suffix, in practice, as soon as you do, the system breaks down. There must be a fix somehow, but in any case, it shows that there is still some work to do to make multilingual work seamless.

In conclusion

I feel like I’ve only just scratched the surface of this CMS. I spent a lot of time describing the structure to show how solidly built it is. Statamic developers have succeeded in combining simplicity and usability.

Since Statamic is based on Laravel, it can support programming to go beyond a run-of-the-mill site. A database can be used for more complex sites where there are far too many pages. The advantage of flat files is the ability to version control every last bit of content. However, database CMSes have long been equipped with static cache engines and when, sooner or later, you end up migrating to another CMS, you’ll be happy to be able to use an export query, which is not as easy when you have a pile of small files. But as always, nothing is impossible in programming, as long as you have the right tools. We are dealing with Laravel after all!

Statamic, like many other similar solutions, is hampered by the fact that they don’t have a large share of the market, or a portal for third party modules. However, at the bottom of their Web page, they do promise to add a Marketplace very soon.

While it boasts of being a more secure solution than Wordpress, Statamic requires an experienced programmer or a very talented Web developer, since the interface doesn’t do it all. Being able to build from the ground up from YAML or MD files is appealing, but not everyone is able to do so. This CMS is a good choice for simple sites and showcase sites, as long as the administrator is comfortable working directly with the files. This is a very versatile CMS, and I totally see why some would enjoy programming with this tool. For example, it can be a good starting point for further programming with Laravel.