Skip to content

Grav CMS Tutorials — Complete Project-Based Guide

In this tutorial series, you'll learn Grav CMS from zero by building a real project — a developer documentation site.

Grav is a flat-file content management system — it uses Markdown files instead of a database. Unlike WordPress (database-driven) or Drupal (enterprise-grade), Grav is designed for speed, simplicity, and Git-friendly workflows. Every page is a folder with a Markdown file inside. No database setup, no complex queries, just files.

What You'll Learn

  • Install Grav locally and configure PHP and web server prerequisites
  • Create content with pages, collections, modular pages, and advanced frontmatter
  • Build dynamic templates with Twig filters, macros, inheritance, and debugging
  • Customize themes with blueprints, assets, inheritance, and multilingual strings
  • Develop plugins using events, forms, admin widgets, and CLI commands
  • Implement multilingual sites, user management, media handling, and REST APIs
  • Optimize caching, performance, security, and Git-based deployment workflows

How to Use This Series

Each lesson builds on the previous one. Start with Module 1 if you are new to Grav, or jump to any module that matches your skill level.

Module 1: Getting Started

# Lesson What You'll Learn
01 What is Grav Flat-file CMS, comparison with WordPress and Drupal
02 Installation PHP setup, Grav download, built-in PHP server

Module 2: Content & Theming

# Lesson What You'll Learn
03 Pages & Content Home page, About page, Markdown, folder structure
04 Navigation Custom menus, page ordering, breadcrumbs
05 Twig Templating Template variables, includes, page content rendering
06 Themes Theme structure, custom theme development
07 Taxonomy & Blog Tags, categories, blog listing page
08 Plugins & Admin Admin panel, essential plugins
09 Configuration & Caching Production-ready performance tuning
10 Deployment & Maintenance Live deployment to production

Module 3: Advanced Content & Pages

# Lesson What You'll Learn
11 Custom Page Types Modular pages, folder types
12 Page Meta & Frontmatter Advanced YAML, overrides, image headers
13 Page Collections List pages, children filters, modular collections
14 Markdown & Shortcodes Grav markdown extras, custom shortcode plugins

Module 4: Advanced Twig

# Lesson What You'll Learn
15 Twig Filters & Functions Date, translate, repeat, range, batch
16 Twig Macros Reusable template blocks, import and export
17 Twig Inheritance Multi-level extends, blocks, embeds
18 Twig Debugging Dump, debug bar, variables inspector
19 Custom Twig Extensions Register custom filters in plugins

Module 5: Advanced Themes

# Lesson What You'll Learn
20 Theme Configuration Blueprints.yaml, theme.yaml, form fields
21 Theme Assets CSS/JS pipeline, asset merging, minification
22 Theme Inheritance Child themes, overriding parent templates
23 Theme Languages Multilingual theme strings, translations

Module 6: Advanced Plugins

# Lesson What You'll Learn
24 Plugin Architecture Folder structure, events, DI container
25 Plugin Events onPageContentRaw, onTwigSiteVariables, event reference
26 Plugin Forms Form state, validation, file uploads, multi-step
27 Plugin Admin Custom admin pages, widgets, dashboard panels
28 Plugin CLI Console commands, task scheduling, cron integration

Module 7: Advanced Features

# Lesson What You'll Learn
29 Multilingual Language switcher, translations workflow, fallbacks
30 User Management Login plugin, permissions, user accounts
31 Media Handling Image manipulation, thumbnails, media aliases
32 Grav API REST API, JSON responses, external integrations
33 Web Services Webhooks, OAuth, SSO, LDAP authentication
34 E-commerce SimpleCart, payment gateways, product management

Module 8: Performance, Security & Deployment

# Lesson What You'll Learn
35 Caching Deep Dive Cache types, cache warming, cache busting
36 Performance Optimization Page speed, CDN, image optimization
37 Security Hardening, .htaccess, CSP headers, XSS prevention
38 Git Workflow Git-based deployment, CI/CD, multi-environment
39 CLI Tools bin/grav commands, automated tasks, maintenance
40 Production Deployment Nginx config, SSL, monitoring, scaling

What You'll Build

By the end of this series, you will build a complete developer documentation site with Grav:

  • A fully themed documentation site with custom Twig templates
  • Blog functionality with tags, categories, and pagination
  • Admin panel for non-technical content editors
  • Multilingual support for international audiences
  • Automated Git-based deployment pipeline
  • Production server with caching, security, and monitoring

Let's begin with Lesson 1.

Published Topics

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

Learn what Grav CMS is, how flat-file CMS works, and why Grav is different from WordPress, Drupal, and Joomla. Start your Grav journey here.

✓ Live

Grav Installation Guide — Local Development Setup

Install Grav CMS on Windows, Mac, or Linux. Download, unzip, run the installer, and see your first page in under 5 minutes with no database required.

✓ Live

Grav Pages & Content — Creating Your First Pages

Learn Grav's page system: folder-based URLs, Markdown content, YAML frontmatter, page types, and creating a home page and about page.

✓ Live

Grav Navigation & Menus — Organizing Your Site

Learn how Grav handles navigation: folder ordering, custom menu labels, visible/hidden pages, external links, and breadcrumbs.

✓ Live

Grav Twig Templating — Build Dynamic Page Templates

Learn Twig templating in Grav CMS: template inheritance, page variables, Twig filters, loops, conditions, and creating custom page templates.

✓ Live

Grav Themes & Customization — From Quark to Your Own Design

Learn how to customize Grav themes: child themes, custom CSS, template overrides, theme inheritance, and creating a branded design.

✓ Live

Grav Taxonomy & Blog Setup — Tags, Categories, and Listing Pages

Learn Grav's taxonomy system: tags, categories, custom taxonomies, blog listing pages with pagination, and displaying filtered content.

✓ Live

Grav Plugins & Admin Panel — Extending Your CMS

Learn how to install and configure Grav plugins via GPM, set up the Admin panel, and explore essential plugins for forms, SEO, and more.

✓ Live

Grav Configuration & Caching — Production Performance Tuning

Learn how to configure Grav for production: system.yaml settings, caching backends, Twig compilation, asset pipeline, and performance optimization.

✓ Live

Grav Deployment & Maintenance — Going Live and Staying Safe

Deploy Grav to production: shared hosting, VPS, Git-based deployment, backup strategies, updates, and ongoing maintenance.

✓ Live

Grav Custom Page Types — folder.md vs default.md and Modular Pages

Learn Grav custom page types: folder.md vs default.md, modular page types, template mapping, and combining page types for complex layouts.

✓ Live

Grav Page Meta & Frontmatter — Advanced YAML and Image Headers

Learn Grav page meta and frontmatter: advanced YAML frontmatter techniques, field overrides, image headers, custom metadata, and SEO optimization.

✓ Live

Grav Page Collections — Listing, Filtering and Traversing Pages

Learn Grav page collections: listing child pages, filtering by taxonomy, traversing siblings, modular collections, and building dynamic page lists.

✓ Live

Grav Markdown & Shortcodes — Extras, Custom Shortcodes and Formatting

Learn Grav Markdown extras and shortcodes: Markdown Extra syntax, custom shortcode creation, content formatting, and extending Markdown with Twig.

✓ Live

Grav Twig Filters & Functions — Date, Translate, Array and Utility Filters

Learn Grav Twig filters and functions: date formatting, translation filters, array manipulation, string utilities, and Grav-specific Twig extensions.

✓ Live

Grav Twig Macros — Reusable Template Blocks and Imports

Learn Grav Twig macros: creating reusable template blocks, importing macros across templates, macro parameters, and best practices for template composition.

✓ Live

Grav Twig Inheritance — Extends, Blocks and Template Hierarchy

Learn Grav Twig inheritance: template hierarchy with extends, block overrides, multi-level inheritance, embeds, and parent theme fallback strategies.

✓ Live

Grav Twig Debugging — Dump, Debug Bar and Variable Inspection

Learn Grav Twig debugging techniques: dump variables, enable the debug bar, inspect template variables, use the DevTools plugin, and troubleshoot common template errors.

✓ Live

Grav Custom Twig Extensions — Registering Filters and Functions

Learn Grav custom Twig extensions: register custom filters, functions, and tests in plugins, extend Twig with PHP logic, and share extensions across themes.

✓ Live

Grav Theme Configuration — Blueprints, Form Fields and Theme Settings

Learn Grav theme configuration: blueprints.yaml, theme.yaml, form fields for the Admin panel, theme options, and adding configurable settings to your theme.

✓ Live

Grav Theme Assets — CSS/JS Pipeline, Merging and Minification

Learn Grav theme assets: CSS/JS pipeline management, asset merging, minification, loading strategies, inline assets, and performance optimization.

✓ Live

Grav Theme Inheritance — Child Themes and Template Overrides

Learn Grav theme inheritance: creating child themes, overriding parent templates, extending parent functionality, and best practices for theme customization.

✓ Live

Grav Theme Languages — Multilingual Strings and Translations

Learn Grav theme language support: creating translation files, multilingual theme strings, language-aware templates, and best practices for internationalization.

✓ Live

Grav Plugin Architecture — Structure, Events and DI Container

Learn Grav plugin architecture: plugin folder structure, the event system, dependency injection container, service providers, and building your first plugin.

✓ Live

Grav Plugin Events — Complete Event Reference and Lifecycle

Learn Grav plugin events: complete event reference, request lifecycle events, onPageContentRaw, onTwigSiteVariables, and practical event-driven development.

✓ Live

Grav Plugin Forms — Form State, Validation and File Uploads

Learn Grav plugin forms: form state management, validation rules, file upload handling, multi-step forms, and integrating forms with the Form plugin.

✓ Live

Grav Plugin Admin — Custom Admin Pages, Widgets and Panels

Learn Grav plugin admin: custom admin pages, dashboard widgets, admin panels, extending the Admin plugin with custom functionality, and admin UI components.

✓ Live

Grav Plugin CLI — Console Commands, Task Scheduling and Cron

Learn Grav plugin CLI: creating console commands, task scheduling, cron job integration, automated maintenance tasks, and command-line plugin utilities.

✓ Live

Grav Multilingual Sites — Language Switcher, Translations and Fallbacks

Learn Grav multilingual sites: language switcher configuration, translation workflows, fallback strategies, multi-language content, and SEO for multilingual sites.

✓ Live

Grav User Management — Login Plugin, Permissions and Accounts

Learn Grav user management: Login plugin configuration, user accounts, permissions and access control, user groups, registration, and authentication.

✓ Live

Grav Media Handling — Image Manipulation, Thumbnails and Responsive Images

Learn Grav media handling: image manipulation, thumbnail generation, media aliases, responsive images, lazy loading, and optimizing images for web performance.

✓ Live

Grav REST API — JSON Responses, Endpoints and External Integrations

Learn Grav REST API: creating JSON endpoints, returning page collections as JSON, building custom API controllers, authentication, and external integrations.

✓ Live

Grav Web Services — Webhooks, OAuth, SSO and LDAP Integration

Learn Grav web services: webhook integration, OAuth authentication, single sign-on (SSO), LDAP integration, and connecting Grav with external services.

✓ Live

Grav E-commerce — SimpleCart, Payment Gateways and Products

Learn Grav e-commerce: SimpleCart plugin, payment gateway integration, product management, shopping cart, checkout flow, and selling digital/physical goods.

✓ Live

Grav Caching Deep Dive — Cache Types, Warming and Cache Busting

Learn Grav caching: cache types (file, Redis, Memcached), cache warming strategies, cache busting techniques, and optimizing cache configuration for performance.

✓ Live

Grav Performance Optimization — Page Speed, CDN and Image Optimization

Learn Grav performance optimization: page speed optimization, CDN integration, image optimization, lazy loading, performance testing, and Lighthouse score improvement.

✓ Live

Grav Security — Hardening, CSP, XSS Prevention and Secure Configuration

Learn Grav security: site hardening, .htaccess configuration, Content Security Policy headers, XSS prevention, file permissions, and secure deployment practices.

✓ Live

Grav Git Workflow — Git-Based Deployment, CI/CD and Multi-Environment

Learn Grav Git workflow: Git-based deployment pipelines, CI/CD integration, multi-environment setup (development, staging, production), and team collaboration.

✓ Live

Grav CLI Tools — bin/grav Commands, Automation and Maintenance

Learn Grav CLI tools: complete bin/grav command reference, automated maintenance tasks, GPM commands, custom console commands, and CLI automation.

✓ Live

Grav Production Deployment — Nginx, SSL, Monitoring and Scaling

Learn Grav production deployment: Nginx and Apache configuration, SSL/TLS setup, monitoring and alerting, horizontal scaling, and go-live checklist.

✓ Live

All 40 topics in Grav CMS Tutorials — Complete Project-Based Guide are published.