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>
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
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
Before configuring this plugin, you should copy the
user/config/plugins/image-captions.yaml and only edit that copy.
Here is the default configuration and an explanation of available options:
Enables and disables the plugin.
By default the plugin will load some basic css. See below for details
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. You could find all images without a class by simply setting this to
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.
You can provide your own class for the
You can provide your own class for the
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
!(myimage.jpg?classes=caption "This is my caption text")
The plugin will take any classes set on the original image tag that start with either
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")
!(myimage.jpg?classes=caption,figure-left,caption-right "This is my figure floated left with caption text aligned right")