Getting Started with Statamic - A Modern Flat-File CMS

What is Statamic?

Statamic is a modern, flat-file CMS built on Laravel that challenges the conventional wisdom that content management requires a database. Instead of storing content in MySQL or PostgreSQL, Statamic uses markdown files and YAML, making your entire site version-controllable, portable, and blazingly fast.

Unlike WordPress, Drupal, or other traditional CMSs, Statamic embraces the JAMstack philosophy while still providing a powerful control panel for content editors. It's the rare CMS that makes both developers and content creators happy.

Why Choose Statamic Over Traditional CMSs?

No Database Headaches

Traditional CMSs require database setup, backups, and maintenance. With Statamic, your content lives in files alongside your code. Deploy with git, version control everything, and forget about database migrations breaking your site.

Performance by Default

Database queries are slow. File reads are fast. Statamic caches aggressively and serves pages with minimal overhead. On a decent server, you'll see sub-50ms response times without complex caching layers.

Git-Friendly Workflows

Every content change is a file change. Commit it. Review it. Roll it back. Branch for experimental content. Merge when ready. Try doing that cleanly with WordPress.

Modern Developer Experience

Built on Laravel 10, Statamic gives you access to the entire Laravel ecosystem. Eloquent ORM (if you want it), queues, events, service providers, middleware—everything you'd expect from a modern PHP framework.

Laravel Foundation, CMS Convenience

You get Laravel's routing, validation, authentication, and authorization systems out of the box. Need custom functionality? Write a Laravel controller. Need complex business logic? Use service classes. It's just Laravel with a CMS bolted on top.

When Statamic Makes Sense

Statamic excels for:

Marketing Sites: Company websites, product pages, landing pages where content changes moderately
Documentation Sites: Technical docs benefit from markdown and version control
Portfolio Sites: Agencies, designers, photographers need flexible layouts without database complexity
Small to Medium Publications: Blogs, magazines, news sites with manageable content volumes
Headless CMS Applications: JAMstack sites, mobile apps, SPAs needing content APIs

Statamic is NOT ideal for:

User-Generated Content: Forums, social networks, review sites with thousands of daily posts
E-Commerce at Scale: While Statamic has add-ons, Shopify or custom Laravel apps are better for large catalogs
Complex Relationships: If your content model looks like a relational database, use a relational database
Real-Time Applications: Chat apps, live dashboards, collaborative editors need databases

Installation and Setup

Requirements

PHP 8.1 or higher
Composer dependency manager
A local development environment (Valet, Homestead, Docker, or built-in PHP server)

Creating a New Statamic Site

The fastest way to start is with Composer:

composer create-project statamic/statamic my-site

This scaffolds a complete Statamic installation with:

Laravel framework
Statamic CMS
Sample content
Default configuration
Control panel

Initial Configuration

Navigate to your new site and start the development server:

cd my-site
php artisan serve

Visit http://localhost:8000/cp to access the control panel. You'll be prompted to create a super user:

php please make:user

Follow the prompts to create your admin account. This user will have full control panel access.

Environment Configuration

Edit .env to configure your site:

APP_NAME="My Statamic Site"
APP_URL=http://localhost:8000
APP_ENV=local
APP_DEBUG=true
STATAMIC_LICENSE_KEY=
STATAMIC_EDITION=solo

The Solo edition is free for single-site use. Pro edition ($259) adds multi-site, GraphQL, REST API, and team collaboration features.

Understanding Statamic's Structure

Content Collections

Collections organize similar content types. Think of them as custom post types:

# content/collections/articles.yaml
title: Articles
route: /articles/{slug}
sort_by: date
sort_dir: desc
date: true
template: articles/show

Each collection entry is a markdown file:

--- title: My First Article slug: my-first-article date: 2025-10-24 author: John Doe ---

Content goes here in markdown format.

Taxonomies

Taxonomies categorize and tag content:

# content/taxonomies/categories.yaml
title: Categories

Taxonomy terms are individual files:

# content/taxonomies/categories/technology.yaml
title: Technology
slug: technology

Attach taxonomies to collection entries:

---
title: Understanding Kubernetes
categories:
  - technology
  - devops
---

Blueprints

Blueprints define field schemas for content. They determine what fields appear in the control panel:

title: Article sections: main: fields: - handle: title field: type: text validate: required - handle: content field: type: markdown - handle: featured_image field: type: assets container: assets max_files: 1

Globals

Globals store site-wide settings like social links, contact info, or navigation:

# content/globals/settings.yaml
title: Site Settings
data:
  site_name: My Site
  twitter: '@mysite'
  contact_email: 'hello@mysite.com'

Access globals in templates:

<a href="mailto:{{ settings:contact_email }}">Contact</a>

Templating with Antlers

Antlers is Statamic's templating language. It's similar to Twig, Blade, or Liquid:

Basic Syntax

{{ title }}
{{ content }}
{{ date format="F j, Y" }}

Conditionals

{{ if featured_image }}
  <img src="{{ featured_image }}" alt="{{ title }}">
{{ /if }}

Loops

{{ collection:articles limit="5" }}
  <article>
    <h2>{{ title }}</h2>
    <p>{{ excerpt }}</p>
  </article>
{{ /collection:articles }}

Modifiers

Transform data with modifiers:

{{ title | upper }}
{{ content | strip_tags | truncate:150 }}
{{ price | currency }}

Partials and Layouts

Keep templates DRY with partials:

<!-- resources/views/partials/header.antlers.html -->
<header>
  <h1>{{ site:name }}</h1>
  <nav>{{ nav:main }}</nav>
</header>
<!-- Use in templates -->
{{ partial:header }}

Building Your First Collection

Let's create a blog with articles:

1. Create the Collection

php please make:collection articles

Edit content/collections/articles.yaml:

title: Articles
route: /articles/{slug}
sort_by: date
sort_dir: desc
date: true
template: articles/show

2. Create a Blueprint

php please make:blueprint articles

Define fields in resources/blueprints/collections/articles/article.yaml:

title: Article sections: main: fields: - handle: title field: type: text validate: required - handle: excerpt field: type: textarea character_limit: 200 - handle: content field: type: markdown - handle: featured_image field: type: assets container: assets - handle: author field: type: text

3. Create Templates

Index template at resources/views/articles/index.antlers.html:

<div class="articles">
  {{ collection:articles paginate="10" as="entries" }}
    {{ entries }}
      <article>
        <h2><a href="{{ url }}">{{ title }}</a></h2>
        <p>{{ excerpt }}</p>
        <small>{{ date format="F j, Y" }} by {{ author }}</small>
      </article>
    {{ /entries }}
  {{ /collection:articles }}
{{ paginate }}
<nav>
{{ if prev_page }}<a href="{{ prev_page }}">Previous</a>{{ /if }}
{{ if next_page }}<a href="{{ next_page }}">Next</a>{{ /if }}
</nav>
{{ /paginate }}
</div>

Show template at resources/views/articles/show.antlers.html:

<article>
  {{ if featured_image }}
    <img src="{{ featured_image }}" alt="{{ title }}">
  {{ /if }}
<h1>{{ title }}</h1>
<p class="meta">{{ date format="F j, Y" }} by {{ author }}</p>
<div class="content">
{{ content }}
</div>
</article>

4. Add Content

Create your first article at content/collections/articles/my-first-article.md:

--- title: My First Article slug: my-first-article date: 2025-10-24 author: John Doe excerpt: This is a brief summary of my article. featured_image: /assets/images/article-1.jpg --- Introduction This is the full article content written in markdown. Bullet points work Bold text works Links work

Everything markdown supports, Statamic supports.

Using Blade Templates

Prefer Laravel's Blade over Antlers? Statamic supports both:

<!-- resources/views/articles/show.blade.php -->
<article>
    @if($featured_image)
        <img src="{{ $featured_image }}" alt="{{ $title }}">
    @endif
&lt;h1&gt;{{ $title }}&lt;/h1&gt;
&lt;div class=&quot;content&quot;&gt;{!! $content !!}&lt;/div&gt;

</article>

Configure collections to use Blade:

# content/collections/articles.yaml
template: articles.show  # Uses Blade instead of Antlers

Headless CMS with REST API

Enable the REST API for headless implementations:

// config/statamic/api.php
return [
    'enabled' => true,
    'resources' => [
        'collections' => true,
        'taxonomies' => true,
        'globals' => true,
    ],
];

Query your content via HTTP:

GET /api/collections/articles/entries
GET /api/collections/articles/entries/{id}
GET /api/taxonomies/categories/terms
GET /api/globals

Response example:

{
  "data": [
    {
      "id": "abc123",
      "title": "My First Article",
      "slug": "my-first-article",
      "date": "2025-10-24",
      "content": "...",
      "permalink": "/articles/my-first-article"
    }
  ]
}

Performance Optimization

Static Caching

Enable full-page static caching:

// config/statamic/static_caching.php
return [
    'strategy' => 'full',
    'warm_queue' => true,
    'warm_concurrency' => 5,
];

First request generates static HTML. Subsequent requests serve cached files directly—no PHP execution.

Stache (Content Cache)

Statamic's "Stache" caches content structure. Clear it when content doesn't update:

php please stache:clear
php please stache:warm

Asset Optimization

Configure image transformations:

# config/statamic/assets.php
image_manipulation:
  driver: gd
  cache: true
  cache_path: public/img

Generate responsive images:

<img src="{{ featured_image | glide:w=800&h=600&fit=crop }}">

Common Gotchas

The "Date" Field Issue

Statamic reserves the date field. If sorting or filtering breaks, use publish_date instead:

# BAD date: 2025-10-24 GOOD

publish_date: 1698105600 # Unix timestamp

Case-Sensitive Slugs

On case-insensitive filesystems (Windows, Mac), slugs like My-Article and my-article conflict. Always use lowercase slugs.

Cache Not Clearing

If content changes don't appear, clear all caches:

php artisan cache:clear
php please stache:clear
php please static:clear

When to Upgrade to Pro

The Solo edition is powerful, but Pro ($259 one-time) adds:

Multi-site: Run multiple sites from one installation
GraphQL API: Modern API alternative to REST
Git Integration: Push/pull content via control panel
Live Preview: See changes before publishing
Revision History: Track and restore content changes
Conditional Fields: Show/hide fields based on other field values

For most projects, Solo suffices. Upgrade when you hit its limits.

Next Steps

Start building:

Install Statamic and create your first collection
Read the docs at statamic.dev/documentation
Join the Discord for community support
Explore add-ons at statamic.com/addons
Study the starter kits for real-world examples

Statamic rewards investment. The initial learning curve pays dividends in maintainability, performance, and developer happiness.

If you're tired of WordPress plugin hell, Drupal complexity, or building CMSs from scratch, Statamic offers a refreshing middle path: powerful, modern, and surprisingly simple.