doc/dev/plugins/image-captions

Image Captions Plugin

Looks for images with defined title attribute and converts them to figure/figcaption syntax.

The Image Captions Plugin is for Grav CMS.

This plugin converts the HTML <img> tag into a <figure> tag with an <figcaption> caption. For example, if you had the following Markdown in your content:

![My Image Alt Text](myimage.jpg?classes=caption "My Image Caption")

The resulting HTML would be:

<img src="/yourpage/mymage.jpg" alt="My Image Alt Text" title="My Image Caption" class="caption" />

And with the plugin enabled, the result would be:

<figure class="image-caption">
    <img src="/yourpage/mymage.jpg" alt="My Image Alt Text" title="My Image Caption" class="caption" />
    <figcaption>My Image Caption</figcaption>
</figure>

Installation

Installing the Image Captions plugin can be done in one of two ways. The GPM (Grav Package Manager) installation method enables you to quickly and easily install the plugin with a simple terminal command, while the manual method enables you to do so via a zip file.

GPM Installation (Preferred)

The simplest way to install this plugin is via the Grav Package Manager (GPM) through your system's terminal (also called the command line). From the root of your Grav install type:

bin/gpm install image-captions

This will install the Image Captions plugin into your /user/plugins directory within Grav. Its files can be found under /your/site/grav/user/plugins/image-captions.

Manual Installation

To install this plugin, just download the zip version of this repository and unzip it under /your/site/grav/user/plugins. Then, rename the folder to image-captions. You can find these files on GitHub or via GetGrav.org.

You should now have all the plugin files under

/your/site/grav/user/plugins/image-captions	

Configuration

Before configuring this plugin, you should copy the user/plugins/image-captions/image-captions.yaml to user/config/plugins/image-captions.yaml and only edit that copy.

Here is the default configuration and an explanation of available options:

enabled: true

Enables and disables the plugin.

built_in_css: true

By default the plugin will load some basic css. See below for details

scope: :not(figure) > img.caption

You can define the scope in which plugin will operate. This typically should be something to define the specific images, for example the default is to find all <img> tags with class caption that are not already inside a <figure> tag. You could find all images without a class by simply setting this to img.

entire_page: false

By default the plugin will only search the page content during the onPageProcessed event. This ensure maximum speed because the results are cached between page loads. However you may have the need to use this plugin on pages where an image is output via Twig or other means, in this case you can set this to true and the entire page will be processed on each request.

figure_class: image-caption

You can provide your own class for the <figure> tag.

figcaption_class: 

You can provide your own class for the <figcaption> tag.

Overriding Config Per Page

You can also override any of the plugin settings on a per-page basis by simply including override values in the page frontmatter. For example:

image-captions:
  enabled: false

Will disable image-captions on this particular page, or:

image-captions:
  figcaption_class: grav-captions 

Will set the figcaption_class for this particular page.

Using the Plugin

To use the plugin you simply need to ensure your image HTML output matches the scope defined. For example the default scope is simply img.caption to you would need to have a title and the .caption class:

![](myimage.jpg?classes=caption "This is my caption text")

CSS Classes

The plugin will take any classes set on the original image tag that start with either caption- or figure and add those to the surrounding <figure> tag. The built in CSS provide a few helper CSS classes:

.figure-left        # float the figure to the left of the content
.figure-right       # float the figure to the right of the content
.caption-left       # align the caption to the left of the image
.caption-right      # align the caption to the right of the image

By default both the Figure and the Caption are center aligned

To use this you can simply put in our markdown:

![](myimage.jpg?classes=caption,figure-right "This is my figure floated right and caption text centered")

or

![](myimage.jpg?classes=caption,figure-left,caption-right "This is my figure floated left with caption text aligned right")