If you want to develop with Grav, you will benefit from a more sophisticated setup than the one required for a regular Grav user. This includes just about any type of development, such as: Grav Core, Grav Plugins, Grav Skeletons, or even Grav Themes.
First, let us break down the various types of development:
When we talk about the Grav Core, we are effectively talking about things in the
system folder. This folder controls everything about Grav and is really the very essence of the Grav workflow and lifecycle.
Grav is intentionally focused on working with pages in an efficient manner. Manipulation of pages and extensive functionality are often best served by creating a plugin. We strongly encourage our community to contribute bug fixes, and even propose development of appropriate functionality within the core of Grav.
First, install the development dependencies by running composer install from the Grav root.
Then you can run the tests:
This will run the full suite of existing tests which should always be executed successfully on any site.
You can also run a single unit test file, e.g.
composer test tests/unit/Grav/Common/Markdown/ParsedownTest::testAttributeLinks
An alternative method to calling these tests is:
./vendor/bin/codecept run ./vendor/bin/codecept run tests/unit/Grav/Common/Markdown/ParsedownTest::testAttributeLinks
Most development effort will probably take the form of a Grav Plugin. Because Grav has plenty of Event Hooks, it's very easy to provide enhanced and specific functionality via the creation of a plugin. We have already developed many plugins that work in a variety of ways using many different events to show off the power of this functionality.
There are many benefits of providing functionality in plugins, but a couple of the key benefits are:
A proper Grav plugin requires certain files in order to function properly, be listed in the Grav repository, and be visible in the Grav admin plugin. Please ensure your plugin contains all these files:
A Grav Skeleton is effectively an all-in-one sample site. They include the Grav Core, required plugins, as well as appropriate pages for content and a theme for pulling it all together.
Grav was designed to make the process of creating a site as easy as possible. For that reason, everything you need for a site can be contained in the
user folder. Each of the skeletons we currently have available are simply a
user folder on GitHub that we package up with various dependencies (required plugins, and theme) into a package that can be simply unzipped to provide a working example.
These skeletons are a base on which you can grow your site, quickly and efficiently. You aren't locked into a specific set of features. It is every bit as flexible as any other Grav install.
A proper Grav skeleton requires certain files in order to function properly, be listed in the Grav repository, and be visible in the Grav admin plugin. Please ensure your skeleton contains all these files:
Because of the tight coupling with Grav pages and themes, a Grav Theme is an integral and very important part of a Grav site. By this we mean that each Grav page references a template in the theme, so your theme needs to provide the appropriate Twig templates that your pages are using.
The Twig templating engine is a very powerful system, and because there really are no restrictions by Grav itself, you are free to create any kind of design you wish. This is one of the great things that sets Grav apart from a traditional CMS that has a loose coupling between content and design.
A proper Grav theme requires certain files in order to function properly, be listed in the Grav repository, and be visible in the Grav admin plugin. Please ensure your theme contains all these files:
You are able to provide demo content as part of a plugin or theme package. This means that anything found in a folder called
_demo/ will be copied over to the
user/ folder as part of the installation procedure. This means you can provide pages, or configuration or anything else that sits in the
user/ folder. The user is prompted to do this, and it's purely optional.
Please note that demo content is not copied when your plugin or theme is installed via the
When you have created your new theme or plugin and would like to see it added to the Grav Repository there are a few standard things that you need to ensure:
LICENSEfile that provides an MIT compatible license Example Here
README.mdfile with a summary of functionality and instructions on how to install and configure it. Example Here
blueprints.yamlfile with all required fields. Example Here
CHANGELOG.mdin the correct format an Example Here
Ensure your naming for each tag is consistent. GPM uses this information to determine if your plugin/theme is newer than the last. We recommend using Semantic Version Numbers for tags. E.g.
1.2.4. Consistency for all tags is paramount!
The GetGrav.org site uses a custom ChangeLog format that is written in standard markdown but can be manipulated with some simple CSS and displayed in an attractive format. In order to ensure your ChangeLogs can be parsed and formatted properly, please use this syntax:
# vX.Y.Z ## 01/01/2015 1. (#new) * New features added * Another new feature 2. (#improved) * Improvement made * Another improvement 3. (#bugfix) * Bugfix implemented * Another bugfix ...repeat...
#new, #improved, #bugfix are optional, just include the sections you need.
Dates can use either the American
m/d/y date format, or the European
d-m-y format. Also make sure there is an empty newline between the headers (version and date) and lists (new, improved, bugfix).
As is the way of things these days, GitHub is going to be your best friend when it comes to developing for Grav. We have created some tools to make this as easy as possible, but there are some development patterns that you should follow to make the process simpler.
Clone all the repositories you plan to work with into a single
Development folder on your computer. This will allow our provided tools to find the repositories they need.
We use the GitFlow branching model for all our Grav development. The core concept of the GitFlow methodology is that development happens in the
develop branch, but new features and functionality are created in separate
feature branches that are merged into
develop when complete. Releases merge
master, and you can apply
hotfix branches as needed during the release process. Most modern git clients support this. However, we recommend Atlassian SourceTree as it's free, cross-platform, and easy to use.
Grav also has some dependencies (dictated by the
.dependencies file) which include the Error and Problems plugins, as well as the Antimatter theme. You can follow these instructions to clone these bits on your own computer.
If you wish to make additions or changes to any of the
getgrav repositories, you will need to fork the appropriate repository and then clone your fork's url rather than the
getgrav repository directly. The example below is using the direct
getgrav repositories for example only.
cd mkdir Projects cd Projects mkdir Grav cd Grav git clone https://github.com/getgrav/grav.git git clone https://github.com/getgrav/grav-plugin-error.git git clone https://github.com/getgrav/grav-plugin-problems.git git clone https://github.com/getgrav/grav-theme-antimatter.git
This will clone all 4 repositories into your
Usually, the normal procedure for setting up a test site for Grav is to use the
bin/grav new-project command. This is true for development, except for one important difference. Because we want to to be able to develop from your web root, but have any changes show up in your cloned code, we need to symbolically link the relevant parts. We do this by passing a
-s flag to the
bin/grav new-project command.
There is one extra step required. You must tell the command where it can find your repositories. So, follow these steps to create a configuration file in a new
.grav/ folder which you will need to create in the root of your home directory:
cd mkdir .grav vi .grav/config
In this file: provide a simple mapping of where the relevant files are located:
Make sure you save this file and that it's readable. You can now set up your symbolically linked site where
~/www is your webroot and
~/www/grav is the location where your new grav test site will be created:
cd ~/Projects/Grav/grav bin/grav new-project -s ~/www/grav
You should see quite a bit of output like this:
rhukster@gibblets:~/Projects/Grav/grav(develop○) » bin/grav new-project -s ~/www/grav Creating Directories /cache /logs /images /assets /user/accounts /user/config /user/pages /user/data /user/plugins /user/themes Resetting Symbolic Links /index.php -> /Users/rhuk/www/grav/index.php /composer.json -> /Users/rhuk/www/grav/composer.json /bin -> /Users/rhuk/www/grav/bin /system -> /Users/rhuk/www/grav/system Pages Initializing /Users/rhuk/Projects/Grav/grav/user/pages -> Created File Initializing /.dependencies -> Created /.htaccess -> Created /user/config/site.yaml -> Created /user/config/system.yaml -> Created Permissions Initializing bin/grav permissions reset to 755 read local config from /Users/rhuk/.grav/config Symlinking Bits =============== SUCCESS symlinked grav-plugin-problems -> user/plugins/problems SUCCESS symlinked grav-plugin-error -> user/plugins/error SUCCESS symlinked grav-theme-antimatter -> user/themes/antimatter
As you can see, a number of default directories were created, and an initial
pages folder was also created. After the base has been set up, the other dependencies are symbolically linked in.
You should be able to point your browser to
http://localhost/grav and see the test site you just set up. Now, any changes you make in your
~/www/grav folder will show up ready to commit and push in your cloned repositories.
People move on, and user-generated content like plugins and themes may become abandoned. If you wish to take over the maintenance of an existing theme or plugin, you must follow this protocol:
Submit a well-formed, tested pull request to the original repository.
If the maintainer does not respond at all after 30 days, or if the maintainer states that they are abandoning the resource and are not willing to grant someone else write access, then proceed to the next step.
Submit a new issue to Grav's GitHub repository with the following details:
[change-resource] Take over plugin/theme
Provide the name of the plugin and link to the original repository.
Link to your pull request that went unanswered or a link to the conversation in which the maintainer has abandoned the resource.
The Grav maintainers will review the case and let you know if the takeover is approved. If approval is granted, proceed to the next step.
Prepare your forked repository with a new release.
Add a note to the README that this repository is the new master and link back to the old repository.
Reply to the issue, giving the maintainers the new URL for the plugin.
The maintainers will update GPM and new and updated installs will now come from your forked repository.
Found errors? Think you can improve this documentation? Simply click the Edit link at the top of the page, and then the icon on Github to make your changes.