What is Grav CMS? — Flat-File CMS Explained for Beginners

In this tutorial, you'll learn what Grav CMS is, why its flat-file approach is different from traditional CMS platforms, and when to use it.

What You'll Learn

• What a flat-file CMS is and why it matters
• How Grav compares to WordPress, Drupal, and Joomla
• Grav's key features: Twig, taxonomy, caching, blueprints
• The kinds of projects Grav is best (and worst) for

Why It Matters

Most CMS platforms store content in a database. That means backups require SQL dumps, version control is difficult, and performance depends on database query optimization.

Grav flips this model: content is files on disk. Every page is a folder with a Markdown file inside. No database, no SQL, no complex setup. You can put your entire site in Git, edit with any text editor, and deploy with git pull.

Real-World Use

Developer documentation sites, project wikis, and static-ish marketing sites are perfect for Grav. For example, a product documentation site with 500 pages — where content changes frequently and multiple contributors use Git — is far simpler in Grav than in a database-driven CMS.

What is a Flat-File CMS?

A flat-file CMS stores content as structured text files rather than database records. When a visitor requests a page:

1. The CMS reads the Markdown file from disk
2. Processes it through a template engine
3. Returns HTML

No database connection, no SQL queries, no caching layer for queries that don't exist.

flowchart LR
  A["Browser Request"] --> B["Grav reads .md file from disk"]
  B --> C["Renders via Twig template"]
  C --> D["Returns HTML"]
  
  style B fill:#38bdf8,color:#0f172a
  style C fill:#38bdf8,color:#0f172a

Traditional CMS vs Flat-File

Key Features

Flat-File Architecture

Every page is a folder inside user/pages/. The folder name determines the URL:

user/pages/
├── 01.home/
│   └── default.md          # /
├── 02.about/
│   └── default.md          # /about
└── 03.blog/
    ├── blog.md             # /blog
    └── 01.my-post/
        └── item.md         # /blog/my-post

The number prefix (01, 02) controls ordering in menus and listings. The filename (default.md, blog.md, item.md) determines the page template type.

Twig Templating

Grav uses Twig, the same templating engine as Symfony and Drupal. Templates are plain PHP-rendered Twig files with full inheritance:

{% extends 'partials/base.html.twig' %}

{% block content %}
    <h1>{{ page.title }}</h1>
    {{ page.content|raw }}
{% endblock %}

No PHP mixed into templates. Clean separation of logic and presentation.

Taxonomy System

Tags, categories, and custom taxonomies are defined in page frontmatter:

---
title: My Post
taxonomy:
    tag:
        - php
        - grav
        - cms
    category: tutorial
---

You can list pages by taxonomy tag in any template.

Blueprints

Blueprints are YAML files that define form fields for the Admin plugin. They work like content type definitions:

fields:
    header.title:
        type: text
        label: Title
    header.published:
        type: toggle
        label: Published

Built-in Caching

Grav supports file, Redis, and Memcached caching. In production, Grav compiles Twig to PHP once and serves cached output for subsequent requests — no database, no compilation overhead.

No Database

This is the headline feature. No MySQL, no PostgreSQL, no SQLite. No connection strings, no migrations, no query optimization. Just files.

When to Use Grav

Grav excels at:

• Developer documentation — Git-friendly, Markdown-native, fast
• Marketing sites — Fast loading, easy content updates, no database attacks
• Personal blogs — Simple setup, no maintenance overhead
• Knowledge bases — Flat-file structure maps naturally to documentation trees
• Prototypes — Go from zip download to working site in 2 minutes

Not ideal for:

• Forums or social networks (needs a database)
• Large e-commerce stores (use Magento or WooCommerce)
• User-generated content at scale
• Sites where non-technical editors need a rich admin experience (use WordPress)

Common Misconceptions

"Flat-file means static site"

No. Grav is a dynamic PHP application. It processes templates on each request (with caching). It's not a static site generator like Hugo or Jekyll — though you can cache aggressively.

"No database means not secure"

The opposite. Database injection attacks are impossible because there's no database. File permissions and server config are your security surface.

"Grav is new and unproven"

Grav was first released in 2014. It powers thousands of production sites, has over 200 plugins, and is actively maintained. It's not as big as WordPress, but it's mature and stable.

Learning Path

flowchart LR
  A["What is Grav?
← You are here"]:::current
  A --> B["Installation"]
  B --> C["Pages & Content"]
  C --> D["Navigation"]
  D --> E["Twig Templating"]
  E --> F["Themes"]
  F --> G["Taxonomy & Blog"]
  G --> H["Plugins & Admin"]
  H --> I["Configuration & Caching"]
  I --> J["Deployment & Maintenance"]

  classDef current fill:#38bdf8,color:#0f172a,stroke-width:2px

Practice Questions

1. What makes Grav different from WordPress? Answer: Grav uses flat-file storage (Markdown files) instead of a database. No SQL setup, no database migrations, and the entire site can be version-controlled with Git.

2. What is the folder structure for a Grav page? Answer: Every page is a folder in user/pages/. The folder name determines the URL. An optional number prefix controls ordering. Inside is a Markdown file whose filename determines the template type.

3. What is a blueprint in Grav? Answer: A YAML file that defines form fields for the Admin plugin. It works like a content type definition, specifying what fields appear when editing a page.

4. When would you NOT use Grav? Answer: For user-generated content (forums, social networks), large e-commerce stores, or any site requiring complex relational data.

5. How does Grav cache work? Answer: Twig templates are compiled to PHP and cached. Page output is also cached. Redis or Memcached backends are available for high-traffic sites.

What's Next

Now that you understand what Grav is, let's install it and get a site running:

Continue to Lesson 2: Installation — Download Grav, run the installer, and see your first page.