Handling Images in Grav

I’m trying to understand the best way to handle images in Grav.

I was considering a central image directory at /user/pages/images (as this would be easy to sync with production), but then I realised that page.media.images requires all associated image files to live in the individual page directory, along with the .md file that contains the content for the page.

Does this mean that I should just store my images in Git and use Git to deploy them along with the .md file, etc?

There are many ways to control the use of images.

The page.media is what is standard to use, but you can customize it as you like by for example adding:

<img src="{{ site.rul }}/images/{{ page.header.imagename }}" />

This is only a basic example and there is many other solutions for this to creat many different kind of media collections.

Also, there is always a reason to use git, it is basically the same as backuping in wordpress, just a lot more valuable and customizable.

1 Like


In WP land I always try to avoid adding images to Git, but maybe this is different. As you say, having a complete backup is attractive.

For me, images are just as important as the content. I recommend you using GIt for everything in user folder except some private stuff like accounts and security.yaml. This will backup everything. In WordPress you backup consists of several parts like the database.

I see your point.

On the other hand, adding images to Git will mean that the repository could grow very large over time.

Also, Git doesn’t work well with binary files.

I’ve been tinkering around after your suggestion above and I now have images defined in the header of my .md file, and being served from /user/pages/images/ with operations still working successfully.

I’m now thinking about simply syncing the images directory with production on deploy.

I’m blown away by the way Grav handles responsive images, it’s awesome.

The more I delve into this, the more I like it!

For any WordPress users who might see this, you can define a responsive retina enabled featured image for your page in the header of the .md file like this:

title: 'My Grav Page'
featuredImage: 'some-image.jpeg'

Make an images directory at /user/pages/images, and then upload the image file to the directory. Make sure it’s an oversized image for retina displays, and give it the filename ‘some-image@3x.jpeg’

In your twig template, add the following to show the image:


Grav will now create and output the correct size image automatically. Once generated, the new images will be stored in the image cache. Neat.

You can add whatever custom variables you need, so the possibilities are endless, and very simple to manage.


Remember to mark it as solved so that the people looking for an answer do not miss it :slight_smile: Also it is a great way to help people who did not get an answer yet.

Great example BTW! There are basically limitless possibilities to customize without knowing any PHP!

1 Like

Well I’m not sure it is solved - I think it’s an ongoing discussion because the platform is so flexible!

I need to use lot of images on more than one page and prefer a central image directory for those images. So I did create a directory user/pages/images and use those images in several pages this way:


To reference those images in element-style CSS included in templates or in CSS files, use:

<div style="background: url('/images/myimage.png') no-repeat center top;">

Old school, works best for me, but I have not that much image references in twig templates and if I have, I place them in plain HTML, so twig variables are used for the name part, but not the directory. I place only images specific to a single web page in the web page’s directory, but for shared images I do not want to duplicate them, since this would break caching in browsers.

1 Like

Out of interest, do you store these images in Git?

It’s content, so I do store them, yes.

It seems that this is the default method when using Grav.

I guess I will need to get over my “never store binary files in Git” concerns…

No, the site is in plain webspace on my own server (not using git nor github).

Having spent a bit longer playing with GraV, I’ve come to the conclusion that images should not be stored in the repo.

I’m experimenting with a deploy script that deploys the markdown and twig files from git, compiles the styles locally (and copies them to the target host) and then syncs the image directory using unison.

Seems like a good solution. It should also work with multiple users.

Would love to see how you have implemented this if you don’t mind! Still trying to figure out the best way to deal with images - some are styled directly into the code so I can control the quality and size and whatnot, but the ones that are uploaded through grav or that the user would add I am still having small issues with.

SrcSet doesn’t work always as expected, haven’t gotten that golden jump of sizes just yet.

As for images not being in the repo, how are you going around the issue of images in posts?

thank you so much <3 . I will try it.

This is working for center images:

![RUST Logo](folder.jpg?classes=p-centered  "RUST Logo")