4.9 KiB
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:
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:
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:
or
