jekyll-figure

A liquid tag for Jekyll that generates <figure> elements.

Installation

1. Add gem 'jekyll-figure' to your site’s Gemfile and run bundle
2. Add the following to your site’s _config.yml:

plugins:
  - jekyll-figure

Note: If you are using a Jekyll version less than 3.5.0, use the gems key instead of plugins.

Usage

This plugin provides a liquid tag that enables you to generate a <figure> element. It takes optional caption and class parameters.

{% figure [caption:"Caption (markdown)"] [class:"class1 class2"] %}
Figure content (markdown)
{% endfigure %}

Examples

In simplest usage:

{% figure %}
Content
{% endfigure %}

<figure>
  <p>Content</p>
</figure>

You can provide a caption, for which any markdown will be rendered:

{% figure caption:"*Markdown* caption" %}
Content
{% endfigure %}

<figure>
  <p>Content</p>
  <figcaption><em>Markdown</em> caption</figcaption>
</figure>

You can also provide a class name(s) for CSS styling:

{% figure caption:"A caption" class:"classname" %}
Content
{% endfigure %}

<figure class="classname">
  <p>Content</p>
  <figcaption>A caption</figcaption>
</figure>

The caption parameter also accepts liquid markup:

{% figure caption:"{{ page.title }}" %}
Content
{% endfigure %}

<figure>
  <p>Content</p>
  <figcaption>The title of my page</figcaption>
</figure>

You can also add labels and reference them:

{% figure caption:"A caption." label:example %}
An example figure that can be referenced later.
{% endfigure %}

You can see an example in {% figref example %}.

<figure id="example">
  <p>An example figure that can be referenced later.</p>
  <figcaption><em>Figure 1:</em> A caption.</figcaption>
</figure>

<p>You can see an example in <a href="#example">figure 1</a></p>

The word ‘Figure’ in the figcaption is translated according to the lang you set in the yaml header of your post. If your language is not supported simple set figure to the yaml header of your post to the value you want to use instead of ‘Figure’.

Configuration

Any markdown provided within the {% figure %} block is rendered using Jekyll’s Markdown parser, Kramdown. However, this means images and other content will be wrapped within <p> tags, like so:

<figure>
  <p><img src="/path/to/image.jpg" alt="Image"></p>
</figure>

To disable this behaviour, in your Jekyll configuration set the paragraphs value for this plugin to false:

plugins:
  - jekyll-figure

jekyll-figure:
  paragraphs: false

Note however that this will remove all paragraph tags, even those nested within other elements.

Testing

1. bundle install
2. bundle exec rake spec

Contributing

1. Fork the project
2. Create a descriptively named feature branch
3. Add your feature
4. Submit a pull request