DOCSEARCHbyAlgolia
Submit Docs

Grav Documentation

repository·develop·Indexed 42 days ago

https://github.com/getgrav/grav-learn

Comprehensive guides for the Grav CMS, including installation via ZIP, Composer, or GitHub; server configuration for Apache, IIS, Nginx, Caddy, and Lighttpd; PHP requirements (7.3.6+); and tutorials on content storage, YAML front matter, and page ordering.

Tokens
305.9K
Snippets
946
Records
1.3K
Agent score
53%

What's inside Grav

  1. Overview of Admin2 Extension Points

    develop

    Admin2 provides several surfaces for plugins to contribute UI elements. Most follow a pattern: a GET endpoint fires an event, plugins append data to that event, and Admin2 renders the results. Web-component payloads (where applicable) are located at admin-next/{subdir}/{slug}.js within the plugin and are served via dedicated script endpoints.

    SurfaceEndpointRegistration eventWeb componentScript endpoint
    Full plugin pageGET /gpm/plugins/{slug}/pageonApiPluginPageInfoadmin-next/pages/{slug}.jsGET /gpm/plugins/{slug}/page-script
    Custom blueprint field(automatic discovery)(filesystem)admin-next/fields/{type}.jsGET /gpm/plugins/{slug}/field/{type}
    Sidebar itemGET /sidebar/itemsonApiSidebarItems(none)—
    Settings panelGET /settings/panelsonApiAdminSettingsPanels(blueprint-mode only)—
    Menubar itemGET /menubar/itemsonApiMenubarItems(none)—
    Menubar actionPOST /menubar/actions/{plugin}/{action}onApiMenubarAction——
    Floating widgetGET /floating-widgetsonApiFloatingWidgetsadmin-next/widgets/{slug}.jsGET /gpm/plugins/{slug}/widget-script
    Context panelGET /context-panelsonApiContextPanelsadmin-next/panels/{slug}.jsGET /gpm/plugins/{slug}/panel-script
    Custom reportGET /reportsonApiGenerateReportsadmin-next/reports/{reportId}.jsGET /gpm/plugins/{slug}/report-script/{reportId}

  2. What is Grav?

    develop

    Grav is a fast, simple, and flexible file-based web platform. Unlike traditional CMS platforms that require complex database installations, Grav is a flat-file system with zero installation required. You can get a site running immediately by simply extracting a ZIP archive.

    Grav's design philosophy focuses on turning content structure into a navigable site, using a simple core that can be extended via an extensive event system. This makes it suitable for rapid development and easy maintenance compared to heavy-weight CMS solutions like WordPress or Drupal.

  3. Understand the Grav folder structure

    develop

    Because Grav is a flat-file based CMS (no database), its folder structure is critical. The top-level structure consists of system/cache directories and the /user directory, which contains all site-specific data.

    Top-level directories:

    • /assets: Processed .css and .js files. Do not store user data here (it is routinely flushed).
    • /backup: Default location for Grav backups.
    • /bin: Contains the Grav CLI application.
    • /cache: Temporary cached files and pre-compiled Twig templates. Do not store user data here (it is routinely flushed).
    • /images: Image cache for automatically generated/resized images. Do not store user data here (it is routinely flushed).
    • /logs: Error logs and profiling data.
    • /system: Core Grav files. Do not edit these, as updates may overwrite changes.
    • /tmp: Temporary files used by Grav and plugins. Do not store user data here (it is routinely flushed).
    • /vendor: Important libraries used by Grav. Do not edit these. If installing from GitHub, run bin/grav install or composer install to populate this.
    • /user: The primary directory for site configuration, content, and customization.
    /assets
/backup
/bin
/cache
/images
/logs
/system
/tmp
/vendor
/user

  4. Member profiles and directory features

    develop

    Forum Pro includes built-in interfaces for member discovery and management:

    • Public Profiles: Located at {forum}/u/<username>. Displays avatars, ranks, badges, reputation, join date, post/topic counts, and recent posts. Signed-in users can send messages or block members.
    • Member Directory: Located at {forum}/members. A searchable, sortable list of all members. Pagination is controlled by frontend.members_per_page (default 48). Online status visibility is controlled by frontend.online_window_minutes.
    • Member Settings: Located at {forum}/settings. Allows members to manage their display name, avatar, profile fields, password, email preferences, and account deletion.

  5. Manage YetiSearch Pro via the Admin Dashboard

    develop

    YetiSearch Pro provides a comprehensive admin dashboard within the Grav Admin plugin to manage search functionality:

    • Index Dashboard: Monitor index health (size, document count, last update) and perform maintenance like reindexing or clearing indexes.
    • Search Analytics: View engagement metrics such as query volume, result clicks, zero-result searches, and response times.
    • Index Browser: Inspect, search, and edit indexed documents directly in JSON format.
    • Permissions: Granular control via yetisearch-pro.view, yetisearch-pro.modify, and yetisearch-pro.admin permissions.

  6. Understand the Grav top-level folder structure

    develop

    Grav is a flat-file CMS, meaning it does not use a database. The site's configuration, content, and assets are managed through a specific directory structure at the installation root.

    Top-level directories:

    • /assets: Stores processed .css and .js files. Caution: This folder is routinely flushed; do not store user data here.
    • /backup: Default location for Grav backups.
    • /bin: Contains the Grav CLI application.
    • /cache: Stores temporary cached files and pre-compiled Twig templates to improve performance. Caution: This folder is routinely flushed; do not store user data here.
    • /images: Acts as a cache for automatically generated/resized images. Caution: This folder is routinely flushed; do not store user data here.
    • /logs: Stores error logs and profiling data.
    • /system: Core Grav files. Do not edit these, as updates may overwrite changes.
    • /tmp: Stores temporary files used by Grav and plugins. Caution: This folder is routinely flushed; do not store user data here.
    • /vendor: Contains third-party libraries required by Grav. Do not edit these. If installing from GitHub, you must run bin/grav install or composer install to populate this folder.
    • /user: The primary directory for site customization, content, and configuration.
    /assets
/backup
/bin
/cache
/images
/logs
/system
/tmp
/vendor
/user

  7. Markdown Syntax Overview

    develop

    Grav uses Markdown for content creation. In Grav 2.0, GitHub Flavored Markdown (GFM) features are enabled by default, including task lists, highlight/subscript/superscript marks, and automatic linking of bare www. and email addresses.

    Note on Grav 2.0 HTML Security: Grav 2.0 uses a tagfilter that escapes a specific denylist of raw HTML tags (title, textarea, style, xmp, iframe, noembed, noframes, script, and plaintext) to prevent accidental breakage. This is a convenience feature and not a primary security boundary.

  8. Overview of Grav API Events

    develop

    The Grav API fires events before and after every write operation. These events allow plugins to extend the Admin2 UI (such as sidebars, menubars, widgets, context panels, settings panels, custom field components, and custom reports).

    Plugins can react to these events to:

    • Validate data
    • Modify data
    • Cancel operations
    • Compose UI elements

  9. What is Flex and when to use it

    develop

    Flex is Grav's framework for custom structured data. It is designed for collections of records (like products, events, or team members) that do not fit the model of a standard Page or a simple Config file.

    When to use Flex

    Use Flex if you would typically reach for a database table on another platform. Specifically, use it when you have many structured records of the same kind that require:

    • Querying/filtering capabilities
    • An editing UI (via the Flex Objects plugin)
    • A REST API
    • Frontend rendering

    Comparison with other Grav data models

    Use caseTool
    Editorial content with a URL, body, and mediaPages
    Small, mostly static site options (e.g., site title)Config / YAML
    Login usersAccounts (a built-in Flex type)
    Many structured records needing querying/API/UIFlex

  10. Overview of Algolia Pro Twig templates

    develop

    The Algolia Pro User Interface is a Vue application built using Twig templates and Vue InstantSearch widgets. Developers can override specific parts of the interface by following the Grav template overriding system.

    Key templates include:

    • instantsearch.html.twig: The main entry point that initializes the <ais-instant-search> widget.
    • instantsearch-scopes.html.twig: A container for importing and defining main Twig blocks.
    • searchbox.html.twig & searchbox_input.html.twig: Handle the search input and query logic.
    • hits.html.twig, hits_items.html.twig, & hits_preview.html.twig: Manage the display of search results and the selected item preview.
    • footer.html.twig & pagination.html.twig: Handle the bottom area and result pagination.
    • assets.html.twig: Manages CSS and JS loading.
    • configure.html.twig: Proxies settings to the <ais-configure> widget.

  11. Core technologies used in Grav

    develop

    Grav is built using several industry-standard technologies to ensure extensibility and performance:

    • Twig Templating: For UI control.
    • Markdown: For content creation.
    • YAML: For configuration.
    • Parsedown: For Markdown and Markdown Extra support.
    • Doctrine Cache: For performance optimization.
    • Pimple Dependency Injection Container: For maintainability and extensibility.
    • Symfony Event Dispatcher: For plugin event handling.
    • Symfony Console: For the Command Line Interface (CLI).
    • Gregwar Image Library: For dynamic image manipulation.

  12. Make plugin data available to Twig templates

    develop

    There are three primary ways to expose data from your plugin to Twig templates:

    1. Via the Config Namespace: Use $this->config->set() to store data under the config.plugins.PLUGIN_NAME namespace. In Twig, access it via {{ config.plugins.PLUGIN_NAME.variable_name }}.
    2. Via the Twig Instance: Pass variables directly to the Twig engine using grav['twig']. These variables are then available directly in the template context.
    3. Via Page Headers: Inject data directly into the page header (e.g., using the Import plugin pattern).