jekyll-image-links 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6b9c59cd6053f748b0f8dcf7552df298abb667f7298ff717af6acd4dffab5148
+  data.tar.gz: c3855e305456f92098aacd45ff07a8ae188b6eae6df1cc95cd9866faef3c96cf
+SHA512:
+  metadata.gz: c8d2a5dc878d212dd91f299e837c09dc789bda8eefdbd745287a7bbd0c646df81694e8b9cdf05487fa68b231509661e3947a0d188defc955c1d3fa94ad77871d
+  data.tar.gz: '008678f930adeaad4ebcbdeaa93b32c87f16dc1fa99ab546634c4d89b3b21fc9b7f103f0e2a0c134d1f68f7c548cb0369c0232ea08645ff7de99fed48c41d6a3'

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 directsun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,195 @@
+# jekyll-image-links
+
+A Jekyll plugin for [Just the Docs](https://github.com/just-the-docs/just-the-docs) sites that adds clickable polygon regions on images.
+
+Inspired by the Dynamic Map Viewer in [5etools](https://github.com/5etools/5etools-src), which uses custom JavaScript (not HTML `<map>` tags) to define polygon click areas on large map images.
+
+## Features
+
+- Define polygon click regions in Markdown using a Liquid tag
+- Click a region to navigate to an internal or external link
+- Hold **Shift** while clicking to open the link in a new tab
+- Integrates with [jekyll-hover-popup](https://github.com/directsun/jekyll-hover-popup) when both plugins are enabled: region clicks open pinned hover-popup windows (no page darkening), and the map viewer opens inside a hover-popup window too
+- Optional **Dynamic Map Viewer** button with zoom, pan, and region highlighting
+- Optional region labels overlaid on the image
+- Load region data inline or from a YAML file
+
+## Install
+
+Add to your site `Gemfile`:
+
+```ruby
+group :jekyll_plugins do
+  gem "jekyll-image-links", path: "/path/to/image-links"
+end
+```
+
+Then in `_config.yml`:
+
+```yml
+plugins:
+  - jekyll-image-links
+```
+
+## Configuration
+
+Optional `_config.yml` settings:
+
+```yml
+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.
+
+## Usage
+
+### Inline regions
+
+```liquid
+{% 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 %}
+```
+
+### External YAML file
+
+`assets/maps/example-map.yml`:
+
+```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:
+
+```liquid
+{% image_map src="/assets/maps/example.webp" file="assets/maps/example-map.yml" style="width:100%;max-width:900px;height:auto" %}
+{% endimage_map %}
+```
+
+Legacy form still works — numeric `width`/`height` on the tag or `<img>` define the native coordinate system when the YAML file does not include them:
+
+```liquid
+{% image_map src="/assets/maps/example.webp" width="1200" height="800" file="assets/maps/example-map.yml" %}
+{% endimage_map %}
+```
+
+### Tag options
+
+| Attribute | Description |
+|-----------|-------------|
+| `src` | Image URL (required) |
+| `width` | Native image width in pixels (required unless set in YAML) |
+| `height` | Native image height in pixels (required unless set in YAML) |
+| `title` | Caption and viewer title |
+| `alt` | Image alt text (defaults to `title`) |
+| `file` | Path to a YAML regions file relative to site source |
+| `style` | CSS display sizing (for example `width:100%;max-width:900px;height:auto`) |
+| `viewer="false"` | Disable the Dynamic Map Viewer button |
+| `inline="false"` | Disable direct click regions on the inline image |
+| `labels="true"` | Show region labels on the inline image |
+
+### Manual HTML (portable markup)
+
+You can also write image maps directly in Markdown using `{::nomarkdown}` blocks. Only an `<img>` tag is required — no `<figure>` wrapper. 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.
+
+```markdown
+{::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`:
+
+```yml
+width: 1413
+height: 1455
+regions:
+  - href: /docs/room-a/
+    title: Room A
+    points: [[120, 80], [420, 80], [420, 320], [120, 320]]
+```
+
+Display sizing alternatives on the `<img>`:
+
+| Attribute | Example | Description |
+|-----------|---------|-------------|
+| `style` | `width:100%;max-width:900px;height:auto` | Full CSS control (recommended) |
+| `width` / `height` | `width="100%"` or `width="800"` | Display size when YAML provides native dimensions |
+| `data-jil-max-width` | `900px` or `80%` | Shorthand for `max-width` |
+| `data-jil-max-height` | `600px` | Shorthand for `max-height` |
+
+Portable images are detected by `class="jil-map-image"` together with region data (`data-jil-regions`, an adjacent `<script class="jil-regions-data">` block, or legacy `data-jil-map="true"`). Legacy `<figure data-jil-map="true">` markup is still supported.
+
+| Attribute | Description |
+|-----------|-------------|
+| `class="jil-map-image"` | Marks the image for enhancement (required) |
+| `data-jil-regions` | Path to a YAML regions file relative to site source |
+| `data-jil-title` | Caption and viewer title |
+| `data-jil-viewer` | Enable/disable the Dynamic Map Viewer button |
+| `data-jil-inline` | Enable/disable direct click regions on the inline image |
+| `data-jil-labels` | Show region labels on the inline image |
+
+## Coordinate system
+
+Region `points` use the image's native pixel coordinates, matching the 5etools `mapRegions` format. 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.
+
+## How this relates to 5etools
+
+5etools stores regions as `mapRegions` on image entries in JSON data, then renders them with a custom `RenderMap` class (`js/render-map.js`) that:
+
+- draws the image on a `<canvas>`
+- overlays clickable polygons
+- uses a ray-casting algorithm for hit detection
+- opens linked adventure content in hover windows
+
+This plugin uses the same polygon coordinate model and the same hit-detection approach, adapted for Jekyll pages with normal `href` links instead of 5etools' internal book area IDs.
+
+## License
+
+MIT

data/assets/jekyll-image-links/image_links.css

@@ -0,0 +1,180 @@
+.jil-figure {
+  margin: 1.25rem 0;
+}
+
+.jil-map-host {
+  position: relative;
+  display: block;
+  max-width: 100%;
+}
+
+.jil-map-host.jil-inline .jil-map-image {
+  display: block;
+  width: 100%;
+  height: auto;
+  max-width: 100%;
+  vertical-align: top;
+}
+
+.jil-map-host.jil-height-constrained {
+  overflow: hidden;
+}
+
+.jil-map-host.jil-height-constrained.jil-inline .jil-map-image {
+  width: auto;
+  max-width: 100%;
+  max-height: 100%;
+  height: auto;
+}
+
+.jil-caption {
+  margin-top: 0.5rem;
+  font-size: 0.95rem;
+  color: var(--jil-caption-color, inherit);
+}
+
+.jil-toolbar {
+  margin-top: 0.75rem;
+}
+
+.jil-viewer-button {
+  font: inherit;
+}
+
+.jil-label-layer {
+  position: absolute;
+  pointer-events: none;
+}
+
+.jil-label {
+  position: absolute;
+  transform: translate(-50%, -50%);
+  pointer-events: auto;
+  padding: 0.1rem 0.35rem;
+  border-radius: 0.2rem;
+  background: rgba(255, 255, 255, 0.82);
+  color: #1f2937;
+  font-size: 0.75rem;
+  font-weight: 700;
+  text-decoration: none;
+  line-height: 1.2;
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.18);
+}
+
+.jil-viewer-backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 10050;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 1rem;
+  background: rgba(0, 0, 0, 0.55);
+}
+
+.jil-viewer-panel {
+  display: flex;
+  flex-direction: column;
+  width: min(96vw, 1200px);
+  height: min(92vh, 900px);
+  background: var(--body-background-color, #fff);
+  color: var(--body-text-color, #272727);
+  border: 1px solid var(--border-color, #dee2e6);
+  border-radius: 0.35rem;
+  box-shadow: 0 12px 40px rgba(0, 0, 0, 0.35);
+  overflow: hidden;
+}
+
+.jil-viewer-backdrop .jil-viewer-panel {
+  width: min(96vw, 1200px);
+  height: min(92vh, 900px);
+}
+
+.jil-viewer-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  padding: 0.75rem 1rem;
+  border-bottom: 1px solid var(--border-color, #dee2e6);
+}
+
+.jil-viewer-title {
+  font-weight: 700;
+}
+
+.jil-viewer-controls {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  padding: 0.75rem 1rem;
+  border-bottom: 1px solid var(--border-color, #dee2e6);
+}
+
+.jil-viewer-scroll {
+  flex: 1;
+  overflow: auto;
+  background: #111;
+}
+
+.jil-viewer-canvas {
+  display: block;
+  cursor: grab;
+}
+
+.jil-viewer-close {
+  margin-left: auto;
+}
+
+.jhp-hwin__content:has(.jil-viewer-in-popup) {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.jhp-hwin__content .jil-viewer-in-popup {
+  display: flex;
+  flex-direction: column;
+  flex: 1 1 auto;
+  width: 100%;
+  min-width: min(88vw, 760px);
+  min-height: 0;
+  max-height: none;
+  overflow: hidden;
+  background: transparent;
+  color: inherit;
+  border: 0;
+  border-radius: 0;
+  box-shadow: none;
+}
+
+.jhp-hwin__content .jil-viewer-in-popup .jil-viewer-header,
+.jhp-hwin__content .jil-viewer-in-popup .jil-viewer-close {
+  display: none;
+}
+
+.jhp-hwin__content .jil-viewer-in-popup .jil-viewer-controls {
+  flex: 0 0 auto;
+  padding: 0.5rem 0 0.75rem;
+  border-bottom: 1px solid var(--jhp-border-color, var(--border-color, #dee2e6));
+}
+
+.jhp-hwin__content .jil-viewer-in-popup .jil-viewer-scroll {
+  flex: 1 1 auto;
+  min-height: 240px;
+  max-height: none;
+  overflow: auto;
+  background: #111;
+}
+
+.jhp-hwin__content .jil-viewer-in-popup .jil-viewer-canvas {
+  display: block;
+  cursor: grab;
+}
+
+@media (prefers-color-scheme: dark) {
+  .jil-label {
+    background: rgba(24, 24, 24, 0.88);
+    color: #f3f4f6;
+  }
+}