Go to main content

Image with caption shortcode

Adding an image as a figure with caption is a common desire with web publishers. With a flexible short-tag and shortcode combination, this is easy and reusable.



Consider the following raw HTML example:

<figure class="some-class">
    <img src="https://example.org/images/130.jpg" alt="The throne of Zeus" />
    <figcaption>A view from Mount Olympus</figcaption>

Writing that block of nested markup each time you want a figure is tedious, and a messy distraction in your article copy when editing. It’s also a pain to find and edit such markup when you need to later, notably the caption.

Let’s do better.

Form to use

Create a new Form template (of any type), name it figure, paste the following code in, and save the template:

<figure<txp:if_yield name="class"> class="<txp:yield name="class" />"</txp:if_yield>>
    <txp:image id='<txp:yield name="id" />' />
    <txp:if_yield name="caption">
        <figcaption><txp:yield name="caption" escape="tidy,textile" /></figcaption>
    <txp:else />
        <txp:image_info id='<txp:yield name="id" />' wraptag="figcaption" escape="tidy,textile" />

Now you have a custom shortcode. By creating that code, you automatically create a corresponding short-tag too.

The Textile attribute (and values), escape="tidy,textile", used in the example above is optional. It enables rendering any Textile you may want to use in your image captions (e.g. a source link). See Escaping tags for more about this new attribute functionality, which works on every Textpattern tag.

Short-tag to use

The corresponding short-tag reflects the name of your shortcode form: <txp::figure />.

See Custom short-tags and shortcodes doc for tag usage when short-tag functionality is disabled in Preferences.

Tag attributes

This new tag, as designed, takes up to three attributes:

  • id (mandatory) — The id of the image you wish to display.
  • class (optional) — A CSS class to apply to the HTML figure element (i.e. <figure class="">.
  • caption (optional) — The caption to apply to the image. If omitted, it will use the one associated with the image itself.

Example usage

You can use the custom short-tag any way you like:

  • <txp::figure id="130" />
  • <txp::figure id="130" class="photo" />
  • <txp::figure id="130" class="photo" caption="The throne of Zeus at Mount Olympus." />

Or as part of a grid of images:

<txp:images category="travel" wraptag="div" class="grid">
    <txp::figure id='<txp:image_info type="id" />' />

See more Shortcode examples.

If you notice any kind of problem with this page’s construction or content (outdated information, typos, broken links, or whatever), open an issue to have it sorted. Or have a go at it yourself. :)