jekyll-image-links

A Jekyll plugin for Just the Docs sites that adds clickable polygon regions on images.

Inspired by the Dynamic Map Viewer in 5etools.

• Define polygon click regions in Markdown using a Liquid tag inline or using an external YAML file
• Click a region to navigate to an internal or external link
• Automatic point rescaling for variable image dimensions (i.e. width: 50%)
• Hold Shift while clicking to open the link in a new tab
• Optional Dynamic Map Viewer button with zoom, pan, and region highlighting
• Optional region labels overlaid on the image
• Integrates with jekyll-hover-popup when both plugins are enabled:
  • Map viewer opens inside a hover-popup window
  • Region clicks open pinned hover-popup windows

Add to your site Gemfile:

group :jekyll_plugins do
  gem "jekyll-image-links", path: "/path/to/image-links"
end

Then in _config.yml:

plugins:
  - jekyll-image-links

Optional _config.yml settings:

image_links:
  enabled: true
  assets_path: /assets/jekyll-image-links
  viewer_by_default: true
  inline_by_default: true
  labels_by_default: false
  use_hover_popup: auto # auto | true | false

When jekyll-hover-popup is also installed, image map region clicks open section previews in hover-popup windows instead of navigating the page. Set use_hover_popup: false to disable that integration.

{% image_map src="/assets/maps/example.webp" width="1200" height="800" title="Example Map" %}
- href: /docs/room-a/
  title: Room A
  label: A
  points:
    - [120, 80]
    - [420, 80]
    - [420, 320]
    - [120, 320]
- href: /docs/room-b/
  title: Room B
  label: B
  points:
    - [480, 120]
    - [760, 120]
    - [760, 420]
    - [480, 420]
{% endimage_map %}

assets/maps/example-map.yml:

width: 1200
height: 800
regions:
  - href: /docs/room-a/
    title: Room A
    points: [[120, 80], [420, 80], [420, 320], [120, 320]]
  - href: /docs/room-b/
    title: Room B
    points: [[480, 120], [760, 120], [760, 420], [480, 420]]

When width and height are in the YAML file, you can omit them from the tag and control display size separately:

{% image_map src="/assets/maps/example.webp" file="assets/maps/example-map.yml" style="width:100%;max-width:900px;height:auto" %}
{% endimage_map %}

You can also write image maps directly in Markdown using {::nomarkdown} blocks. Only an <img> tag is required. Put configuration on the image itself using data-jil-* attributes.

Store the native image dimensions in the YAML file. Region points use that coordinate system. Use CSS on the <img> for display size (percentages, max width/height, and so on). At build time those display styles are moved to the surrounding .jil-map-host wrapper so percentage sizes resolve against the page layout correctly.

If the plugin is disabled or not installed, the image still renders normally and browsers ignore the extra data-jil-* attributes.

{::nomarkdown}
<img
  class="jil-map-image"
  src="/assets/images/a-familiar-tower/tower-1-combined-cropped.png"
  alt="Level 1"
  style="width: 100%; max-width: 900px; height: auto;"
  loading="lazy"
  data-jil-title="Level 1"
  data-jil-regions="assets/maps/a-familiar-tower-1.yml"
  data-jil-viewer="true"
  data-jil-inline="true"
  data-jil-labels="true"
/>
{:/nomarkdown}

assets/maps/a-familiar-tower-1.yml:

width: 1413
height: 1455
regions:
  - href: /docs/room-a/
    title: Room A
    points: [[120, 80], [420, 80], [420, 320], [120, 320]]

Qualified images are detected by class="jil-map-image" together with region data (data-jil-regions)

Region points use the image's native pixel coordinates. Define the native size once in the YAML file (width and height) or on the tag/image when not using YAML dimensions. For example, a 4937×3439 map uses coordinates in that range.

The plugin scales clicks from whatever size the image is displayed at back into that native coordinate system. Changing display size with CSS, percentages, or max width/height does not require editing region points.

MIT