Grav Plugins & Admin Panel — Extending Your CMS

In this tutorial, you'll learn how to extend Grav with plugins and manage your site through the Admin panel.

What You'll Learn

• Using GPM (Grav Package Manager) to find and install plugins
• Setting up the Admin plugin for visual content management
• Essential plugins: Forms, SEO, Email, Sitemap, and more
• Configuring plugins via YAML files and the Admin panel

Why It Matters

Grav's core is intentionally minimal — it does pages, templates, and taxonomy well. Everything else comes through plugins. The plugin ecosystem lets you add exactly what you need without bloating the core. The Admin plugin, in particular, makes Grav accessible to non-technical editors.

Real-World Use

DodaTech documentation sites use: Admin plugin for editors who prefer a GUI, Forms plugin for contact pages, SEO plugin for meta tags, and Sitemap plugin for search engines. All installed via GPM, all configurable from the Admin panel.

GPM: Grav Package Manager

GPM is Grav's CLI tool for finding, installing, and updating plugins and themes.

Searching for Packages

# Search plugins
bin/gpm search

# Search with keyword
bin/gpm search form
bin/gpm search seo

Installing Plugins

# Install a single plugin
bin/gpm install admin

# Install multiple
bin/gpm install form email seo sitemap

Managing Plugins

# List installed
bin/gpm index

# Update all packages
bin/gpm update

# Check for updates
bin/gpm version

# Remove a plugin
bin/gpm uninstall form

The Admin Plugin

The Admin plugin provides a web-based interface for managing content, users, and configuration.

Installation

bin/gpm install admin

Creating an Admin User

bin/gpm install admin
bin/grav new-admin-user

You'll be prompted for:

• Username
• Full name
• Email address
• Password (minimum 8 characters)

Accessing the Admin Panel

Visit http://localhost:8000/admin:

http://localhost:8000/admin

You'll see the login screen. Enter your admin credentials.

Admin Panel Tour

The Admin panel is organized into sections:

Pages — Create, edit, delete, and organize pages. Lists all pages in a tree view matching Grav's folder structure.

Plugins — View installed plugins, enable/disable, and configure plugin settings.

Themes — View active theme, change themes, customize theme options.

Users — Manage admin users, roles, and permissions.

Tools — Cache management, reports, installation logs.

Configuration — Edit system.yaml and site.yaml through a GUI.

Creating a Page in the Admin Panel

1. Click Pages in the sidebar
2. Click Add button
3. Enter the page title (e.g., "Contact")
4. Choose a template type (e.g., Default)
5. Set visibility (Published)
6. Write content in the editor
7. Click Save

The Admin panel creates the folder and Markdown file for you — same result as creating it manually.

Essential Plugins

Forms Plugin

Adds form creation capabilities. Define forms in YAML and handle submissions via email or file storage.

bin/gpm install form

Example form in a page:

---
title: Contact
form:
    name: contact
    fields:
        name:
            label: Name
            type: text
            validate:
                required: true
        email:
            label: Email
            type: email
            validate:
                required: true
        message:
            label: Message
            type: textarea
            validate:
                required: true
    buttons:
        submit:
            value: Send Message
    process:
        email:
            subject: "[Contact Form] {{ form.value.name }}"
            template: formdata
        save:
            file: "user/data/contact/{{ form.value.name|slugize }}.yaml"
        message: "Thank you for your message!"
---

# Contact Us

Fill out the form below to get in touch.

Email Plugin

Required by the Forms plugin for email delivery.

bin/gpm install email

Configure in user/config/plugins/email.yaml:

enabled: true
mailer:
    engine: smtp
    smtp:
        host: smtp.gmail.com
        port: 587
        encryption: tls
        user: your@email.com
        password: your-password

SEO Plugin

Generates meta tags, Open Graph, Twitter Cards, and XML sitemaps.

bin/gpm install seo

After installation, configure SEO settings per-page in the Admin panel under the SEO tab.

Sitemap Plugin

Generates sitemap.xml for search engines.

bin/gpm install sitemap

Visit http://localhost:8000/sitemap.xml to verify it works.

Related Pages Plugin

Shows related content based on shared taxonomy.

bin/gpm install relatedpages

Add to your blog template:

{% if config.plugins.relatedpages.enabled %}
    <div class="related-posts">
        <h3>Related Posts</h3>
        <ul>
        {% for related in relatedpages(page) %}
            <li><a href="{{ related.url }}">{{ related.title }}</a></li>
        {% endfor %}
        </ul>
    </div>
{% endif %}

JS and CSS Assets Plugin

Allows adding custom JS and CSS from the Admin panel without editing templates.

bin/gpm install assets

Login Plugin

Required by the Admin plugin. Manages user authentication.

bin/gpm install login

Plugin Configuration

Plugins can be configured in two ways:

1. Via the Admin panel — Navigate to Plugins, find the plugin, and edit settings.
2. Via YAML files — Create/edit user/config/plugins/pluginname.yaml.

Example: user/config/plugins/relatedpages.yaml:

enabled: true
limit: 5
order:
    by: date
    dir: desc

Creating a Simple Custom Plugin

Plugins are PHP classes that hook into Grav events.

<?php
namespace Grav\Plugin;

use Grav\Common\Plugin;

class HelloWorldPlugin extends Plugin
{
    public static function getSubscribedEvents()
    {
        return [
            'onPageContent' => ['onPageContent', 0]
        ];
    }

    public function onPageContent()
    {
        $this->grav['page']->setContent(
            str_replace('world', 'Grav', $this->grav['page']->content())
        );
    }
}

Save as user/plugins/helloworld/helloworld.php and enable it. This plugin replaces "world" with "Grav" in all page content.

Common Plugin Mistakes

Learning Path

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

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

Practice Questions

1. What command installs a plugin in Grav? Answer: bin/gpm install <plugin-name>. For example, bin/gpm install admin.

2. How do you create an admin user? Answer: After installing the Admin plugin, run bin/grav new-admin-user and follow the prompts.

3. What does the Forms plugin do? Answer: Adds form creation to pages. Forms can handle submissions via email, file storage, or custom processing.

4. Where are plugin configurations stored? Answer: In user/config/plugins/ as YAML files (e.g., user/config/plugins/email.yaml).

5. Challenge: Install the Admin, Forms, Email, and Sitemap plugins. Create a contact form that sends an email (configure SMTP). Verify the sitemap generates at /sitemap.xml.

What's Next

Your site is feature-rich. Let's make it fast and production-ready:

Continue to Lesson 9: Configuration & Caching — Optimize Grav for production performance.