Grav - Image Linking

In this chapter, we will understand image linking in Grav. Grav allows you to link images from one page to another and even to remote pages. If you have linked the files using HTML, that would be very easy to understand image linking in Grav.

Grav Image Linking

Using this structure, we will see how to display media files in the page using different types of links. Every folder under this structure contains images and there is a special directory under / which acts as a page but contains only media files.

Let's look into some of the common elements of Grav markdown-based image tag.

![Alt Text](../path/image.ext)
  • ! − It indicates an image tag when you place it at the beginning of markdown link tag.

  • [] − It specifies optional alt-text for the image.

  • () − It is placed directly after the square bracket which contains file path.

  • ../ − It indicates a move up a directory.

Grav uses five types of image links as listed below −

  • Slug Relative

  • Directory Relative

  • Absolute

  • Remote

  • Media Actions on Images

Slug Relative

It sets relative image links to the current page and links another file in the same directory. While using relative links, the location of the source file is as important as that of the destination. If you change the path in the file while moving, then the link can be broken. The advantage of using this image linking structure is that you can switch between local development server and a live server with a different domain name, as long as the file structure stays constant.



Here ../ indicates that your link moves up one folder and then down one folder and img.jpg is the destination.

When you use the above path, you will receive the following output −

Grav Image Linking

Grav supports slugs in the header of the page's primary markdown file and this slug takes the place of the folder name for the given page.

If folder has a slug set through its .md file, i.e., /pages/, then the header of the file would be as −

title: Sky
slug: test-slug
   category: blog

In the above code, we have set the slug test-slug which is an optional. Once you set the slug, you can then link to the media file which will have Slug Relative or Absolute URL set for the link.

Directory Relative

In this type of link, you can set directory relative image links to the current page. Instead of using the URL slugs, you can reference through the full path with their folder names in directory relative image links.


![My image](../../blue/img01/img.jpg)

When you use the above path, it will display the output as shown below −

Grav Image Linking


Absolute links are same as relative links but the only difference is that they are relative to the root of the site and present in the /user/pages/ directory.

You can use absolute links in two different ways −

  • You can use Slug Relative style that includes slug or directory names in the path and commonly used in absolute linking.

  • You can use Absolute Link which opens the link with a/.

![My image](/blue/img01/img.jpg)

When you use the above path, you will receive the following output −

Grav Image Linking


Remote image links allow displaying any media file directly through its URL. These links do not include your own site's content. The following example shows how to display image using remote URL −

![Remote Image 1](

When you click on the link as shown in the image below, it will display the image from the given URL.

Grav Image Linking

Media Actions on Images

Images associated with pages enable us to use the advantage of Grav's media actions. You can display some media files like images, videos and other files when creating content in Grav.


You can load an image by using the format given below −

![Styling Example](../img01/img.jpg?cropResize = 400, 200)

When you use the above path, you will receive an output as shown below −

Grav Image Linking