Folder Structure

Because Grav is a flat-file based CMS, meaning there is no database that underpins it, the folder structure of your site is very important. At the top level of your Grav installation the folder structure looks like:

/assets
/bin
/cache
/images
/logs
/system
/user
/vendor

So let us dig a little deeper into each of these top level folders and explain what they are for:

/assets

(v0.9.0+) The assets folder is used by the new asset management system within Grav to store processed .css and .js files.

This folder should not be used to store any user data, as it is routinely flushed of all data.

/bin

The bin folder contains the Grav CLI application that can be used to perform some handy tasks from the command line. This is a relatively advanced feature primarily intended for developers so we'll set this topic aside for later discussion.

/cache

The cache folder is used to store temporary cached files that are automatically generated by Grav to improve performance. By default, Grav handles caching automatically, selecting the best available option for your hosting environment to ensure your site runs as fast as possible.

If Grav decides that the filesystem is the best caching method, the cached files it generates will be stored here. The Twig template engine also uses this location to store its pre-compiled template files. Again, this is done to ensure that Grav performs at its optimum speed.

This folder should not be used to store any user data, as it is routinely flushed of all data.

/images

Grav comes with a built-in powerful yet very easy-to-use image manipulation library. This means you can easily resize an image on-the-fly from your content or even from a plugin. These images are stored in the images folder so that they can be reused if the same image with the same size is requested again.

This folder acts like an image cache and is intended for automatically generated files. User provided media should be stored in the user/pages/, user/themes/ or even a custom user/images/ folder.

This folder should not be used to store any user data, as it is routinely flushed of all data.

/logs

When Grav detects an error, or if you have extra logging or profiling turned on, it stores the relevant logfiles in the logs folder.

/system

The system folder is where the files that make Grav actually function live. You should not edit anything in this folder because an update to Grav could overwrite your changes. If you need to change something related to how Grav works, you can use plugins as discussed in later chapters.

/vendor

The vendor folder contains important libraries that Grav relies on. This folder is similar to the system folder in that its contents should not be edited unless you're really sure you know what you're doing.

(v0.9.2+) If you installed Grav from GitHub, the vendor folder won't have been installed with it. In order to create and populate the vendor folder you will have to run bin/grav install or composer install from the root of your Grav instance. More details can be found under the installation section.

/user

This is the most important folder for the majority of Grav users. This folder is where you will spend your time creating content, using plugins and editing your themes. Let us burrow a little further into this folder:

/user/accounts
/user/config
/user/data
/user/pages
/user/plugins
/user/themes

/user/accounts

The accounts folder is where you will define user accounts if access restrictions are required to certain portions of your site.

/user/config

The files in the config directory are used to configure the web site and have been discussed in the previous chapter.

/user/data

The data folder can be used by plugins to store data that you can reference later. A good example of a plugin that utilizes this folder is the Forms plugin that can take a web form and store the submitted data in a text file in this folder. You can also store other things such as user-uploads or anything you wish to really.

This folder is not accessible via a browser by default.

/user/pages

This is the heart of Grav. The pages folder is where you create and edit your content. We will go into much more depth in the next section.

/user/plugins

A plugin can extend the fast core of Grav with particular features you may need for your Website. Plugins can be downloaded from GetGrav.org/downloads/plugins or you can develop your own.

/user/themes

A theme turns your content into a true website. It converts the content you have constructed into the HTML that a browser understands and displays to your audience. There is a base theme that is provided with Grav but you can also download others from GetGrav.org/downloads/themes or even create your own. The Themes section will outline this in further detail.