Hello everyone! Today we’re going to talk about Grav’s folder structure (folder structure?) and where you can go to find, create, and edit pages and settings within your Grav site.
Let’s start by talking about what Grav is. Grav is a flat-file content management system. The flat-file part of that title means that there are no databases or complex data structures to deal with. Everything from your site’s configuration to its content is kept in simple, human-readable files that you can easily access and edit.
Another important thing to note is that virtually every configuration option you can access from the site’s file system is also reachable through the Admin Panel. A well-written theme or plugin should make it easy to adjust anything you need to without ever having to open a code editor.
To make things simple, let’s look at the root directory of a typical Grav site. There is one directory here you as the user [Grav site author?] should pay attention to the /user directory.
This is home to just about everything you’ll interact with. Your site and system configuration, plugins, themes, and content are kept in this directory. Everything else is part of Grav’s core system and doesn’t require any direct interaction.
Ideally, you should be able to duplicate any Grav site by copying everything in this directory.
Now that we’ve narrowed it down to one directory, we can focus on what each subdirectory brings to the table.
User accounts are stored in the /accounts folder. Here, you will find YAML files that store information such as the name, user level, and a hashed copy of the account’s password. YAML files are text-based configuration files.
If you need to modify the access rights of a user accounts, editing their associated YAML file from this directory will do the trick.
The /blueprints directory is where custom blueprints are stored. Blueprints are YAML files that let Grav know what configuration options are available for a given plugin or theme.
The /config folder is where your configuration options are stored. This folder not only contains your site and system options, but the settings for all of your plugins and themes, as well.
Want to change the name of your website? You’ll find the site.yaml file where you can do it here. Want to enable or disable a specific plugin? You can do so here.
The /data folder is where custom data generated by plugins and other interactive aspects of your site is stored.
This directory is home to any images you want to access in various areas of your site. Your site’s logo would likely be stored here, as well as images that are commonly accessed by your theme.
You can also store images used in specific pages in their individual page directories.
For multilingual sites, this folder is essential. It contains translation files that tell Grav what text to display depending on which language is selected by the visitor.
The /pages directory is home to your site’s content. Every page on your site resides somewhere in this folder’s structure, from your home page to a single blog post.
Subfolders here generally include a markdown file and any image(s) that apply specifically to its related page. You can nest page folders within page folders to create your site’s content structure.
For example, you might have a /pages/blog/ directory containing a markdown file that builds your site’s blog archive. Then, within that directory are numerous other folders containing their own markdown folders, each of these pages being individual blog posts.
In short: think your sites’ pages directory as a mirror of your website. It’s organized in much the same way, with its folder structure following in step with the pages on your site.
The /plugins directory contains all of the plugins for your site. Each plugin sits in its own subdirectory here. As a user [Grav site author?], You generally don’t need to edit anything here as your custom configuration changes are instead stored in the /config folder using a copy of the plugin’s named YAML file.
Finally, we have the /themes directory. This is where any installed themes live for your site. Like the plugins directory, you would make your custom configurations in the /config folder using a copy of the theme’s named YAML file.
You can see a lot of the folder structure reflected in the Admin Panel. Looking at the sidebar, you can see the Configuration, Pages, Plugins, and Themes sections. Each of these sections reflects their associated folders within the /users directory.
One small difference is that configuration options for a specific plugin or theme are accessible directly in that item’s page in the Admin.
For example, when you make a change to a plugin’s settings, those changes are stored in a plugin-specific YAML file in the /config folder for you.
With Grav, you have the choice of modifying your site using the Admin Panel or editing files directly - it’s up to you!
Notice an error? Think you can improve this documentation?
Edit this Page