Eleventy Plugin Image Caption

• Eleventy Plugin Image Caption
  • Background
  • Examples
  • Limitations
    • Single Image
    • Serve Mode
    • Image Reference Position
  • Installation
  • Plugin Configuration
  • Usage
    • imageCaption
    • imageReference

An Eleventy (11ty) plugin that adds two shortcodes to a site:

| Shortcode | Description | | ---------------- | ------------------------------------ | | imageCaption | Returns an automatically numbered image caption like "Figure 1: A boy with a dog" The shortcode automatically assigns the image/figure number based on an image file's position on the page (top to bottom). | | imageReference | Returns a text string that references a particular image by number like "Figure 2". |

Background

I've always loved the Microsoft Word features that allow you to add an auto numbering caption to an embedded image or table then reference the caption elsewhere in the document. This is something you could do to any Word document manually, but with these features, the numbers and references update automatically whenever you move images around or add new images to the document.

While working on a new Eleventy site, I realized that I wanted the same capability in Eleventy. On this site, I expect to host a lot of tutorials and product reviews, so being able to easily reference image captions in a post was key to readability.

Examples

This repository includes a complete Eleventy site that demonstrates the functionality exposed through the plugin; you can access the site on Netlify.

Here's an example of a simple caption added to an image using the imageCaption shortcode. The shortcut adds a paragraph with the text "Image 1: Dog with Flower" shown in the following figure. Its the first image in the file, so the plugin automatically numbers it with a 1.

When you invoke the shortcode, you give it a unique reference to the image plus the text added to the caption and the plugin handles the rest.

The next example highlights referencing an image in the post image number/reference using the imageReference shortcode.

When you invoke the shortcode, you give it the unique index for the image and the plugin handles the rest.

Limitations

Before we get too deep into the technical details of the plugin, its important to note two limitations.

Serve Mode

When running the site included with this plugin on your local development workstation (starting the Eleventy server with the --serve parameter), you'll notice that the captions don't show the image number in the caption.

This is...deliberate (on purpose). As I coded the plugin, I realized that when I run the server in development mode, every time I save the project and the page refreshes in the browser, the assigned image numbers incremented. This means that they'd be accurate and I made the decision to essentially disable auto numbering in development mode, instead showing a # to represent the image number.

When you publish the site on a server or run you run a local build and look in the project's _site folder, you'll see that the captions number as expected.

Image Reference Position

A page must add a caption an image using the imageCaption shortcode before you can use the imageReference shortcode to reference it. Its the process of adding the image to the page that creates the index used by imageReference to lookup the image number.

Installation

To install the plugin, open a terminal window or command prompt, navigate to an Eleventy project folder, and execute the following command:

npm i eleventy-plugin-image-caption

Plugin Configuration

The plugin supports a few configuration options that allow you to configure the plugin's behavior.

| Configuration Option | Description | | -------------------- | ------------ | | captionBold | Boolean value that controls whether the caption text ("Image #:" or "Figure #:") is bold (HTML strong).Default: true. | | captionClass | String value that specifies the class name added to the Default: caption. | | captionLabel | String value that specifies the text label prepended to the caption.Default: Image. |

As with any Eleventy Plugin, to use it you must import it into your project's configuration file (mine is .eleventy.config.js):

import imageCaptionPlugin from 'eleventy-plugin-image-caption';

Then, within the exported function in the configuration file, add the plugin to the Eleventy configuration. The following code adds the plugin with its default settings (described in the table above):

eleventyConfig.addPlugin(imageCaptionPlugin);

You can also load the plugin and specify configuration options as shown in the following example. The example disables bolding for the caption label and sets the caption label to "Figure: ":

eleventyConfig.addPlugin(imageCaptionPlugin, {
	captionBold: false,
	captionLabel: "Figure"
});

If your site uses a different class name for captions, specify it in the configuration like this:

eleventyConfig.addPlugin(imageCaptionPlugin, {		
	captionBold: false,
	captionClass: "ImageCaption"
});

Here's an example of a complete Eleventy configuration file using the settings from the second example above:

import imageCaptionPlugin from 'eleventy-plugin-image-caption';

export default async function (eleventyConfig) {

  eleventyConfig.addPlugin(imageCaptionPlugin, {
		captionBold: false,
		captionLabel: "Figure"
	});

	eleventyConfig.addPassthroughCopy("src/assets/");
	eleventyConfig.addPassthroughCopy("src/images/");
	
	return {
		dir: {
			input: 'src',
			output: "_site",
			includes: "_includes",
			layouts: "_layouts",
			data: "_data"
		}
	}

};

With that in place, you can start using the shortcodes in your site's pages.

Usage

imageCaption

To add a caption to an image on one of your site's pages, use the imageCaption shortcode which looks something like this:

{% imageCaption "<image-index>" "<caption-text>" %}

In the example:

• <image-index> refers to a unique identifier for the image file being captioned. You'll use this index later to refer to the image using the imageReference shortcode.
• <caption-text> refers to the text you want displayed in the caption.

Here's an example from the sample app included in this repository:

{% imageCaption "richard-brutyo-Sg3XwuEpybU-unsplash.jpg" "Dog with Flower" %}

When Eleventy builds the site, the plugin will replace the shortcode with:

Image 1: Dog with Flower

Which is what you see in the first screenshot on this page.

In this example, I used the file name for the image file, recognizing that it should be unique unless I happen to use the image file twice on the same page. I could have easily used the following:

{% imageCaption "dogFlower" "Dog with Flower" %}

imageReference

Note: As mentioned in the Limitations section of this document, the imageReference shortcode only works images that have already been captioned. The captioned image must be higher in the page content than the associated image reference shortcode.

To calculate the caption label (label text plus image number) on a page, use the imageReference shortcode:

{% imageReference "<image-index>" %}

In the example:

• <image-index> refers to the unique identifier assigned to the caption created earlier.

For example, to calculate a reference to the image from the previous section's example, you would use the following shortcode after the image has already been captioned.

{% imageReference "richard-brutyo-Sg3XwuEpybU-unsplash.jpg" %}

or, for the second example:

{% imageReference "dogFlower" %}

Here's an example from the sample app included in this repository:

I personally think {% imageReference "richard-brutyo-Sg3XwuEpybU-unsplash.jpg" %} is cuter than {% imageReference "mtsjrdl-5yAhL8ViUVg-unsplash.jpg" %}, don't you?

Which generates the following text:

I personally think Image 1 is cuter than Image 2, don't you?

If this code helps you, please consider buying me a coffee.