jekyll-highlight-cards

A Jekyll plugin providing styled card components for links and images with Internet Archive integration.

• {% linkcard %} - Styled link cards with optional titles and archive links
• {% polaroid %} - Polaroid-style image cards with titles, links, and archive support
• Markdown Image Sizing - Extended syntax for image dimensions: ![alt](image.jpg =300x200)
• Internet Archive Integration - Automatic lookup and archival for both tags
• Customizable - Override HTML templates and CSS styles

Add to your Gemfile:

gem 'jekyll-highlight-cards'

Add to your _config.yml:

plugins:
  - jekyll-highlight-cards

Run:

bundle install

Add to your main.scss file:

@use "highlight-cards";

Highlight links:

{% linkcard https://example.com %}
{% linkcard https://example.com My Cool Title %}
{% linkcard https://example.com Title archive:none %}
{% linkcard https://example.com archive:https://web.archive.org/... %}

Parameters:

Create polaroid-style image cards:

{% polaroid /assets/image.jpg %}
{% polaroid /assets/image.jpg size=300x200 %}
{% polaroid /assets/image.jpg size=400x title="My Photo" %}
{% polaroid /assets/image.jpg alt="Screen reader description" %}
{% polaroid /assets/image.jpg alt="Alt text" title="Visible Title" %}
{% polaroid /assets/image.jpg title="Photo" link="https://example.com" %}
{% polaroid /assets/image.jpg link="https://example.com" image_link="https://other.com" %}
{% polaroid {{ page.image }} size=x400 title={{ page.title }} %}

Parameters:

Image Alt Text: The alt attribute priority: explicit alt parameter → title parameter → empty string.

This allows you to:

• Set accessible alt text without displaying a visible title
• Use title as both visual label and screen reader description
• Separate concerns: detailed alt for accessibility, brief title for display

Link Behavior:

• No link parameter: Image links to itself, no visible link text shown
• With link parameter: Image and visible link text both point to the specified URL
• With image_link parameter: Image links to image_link URL, overriding default behavior
• With both link and image_link: Image links to image_link, but visible text displays link

Stacking:

By default, the Polaroids are displayed centered in their available space. Two Polaroids in a row will be stacked vertically.

If you want Polaroids to fill the available width side-by-side, add the following to your main.scss file:

.polaroid-container {
  display: inline-block;
  width: auto;
}

Add dimensions to Markdown images:

![Alt text](image.jpg =300x200)
![Alt text](image.jpg =400x)
![Alt text](image.jpg =x300)
![Alt text](image.jpg =400pxx300px)

Sized images are automatically wrapped in links to themselves.

Enable automatic archive lookup:

export JEKYLL_HIGHLIGHT_CARDS_ARCHIVE=1

Or in your shell config:

# In .bashrc, .zshrc, etc.
export JEKYLL_HIGHLIGHT_CARDS_ARCHIVE=1

Default usage:

Import the default styles which include both structure and colors:

@use "highlight-cards";

This provides a complete, ready-to-use appearance.

Full customization:

For complete control over colors and visual effects, import only the structural styles and define your own colors:

@use "highlight-cards-structure";

// Define your own color styles
.polaroid {
  border-color: var(--link-color);
  background-color: var(--body-bg);
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.3);
  
  .polaroid-image {
    border-color: var(--link-color);
  }
}

The structure file contains only layout, positioning, and sizing - no colors, borders, or visual effects. This allows you to fully customize the appearance while maintaining the structural layout.

If the provided HTML structure doesn't work for you, you can override templates by creating files in your Jekyll site:

Linkcard template:

• Create _includes/highlight-cards/linkcard.html

Polaroid template:

• Create _includes/highlight-cards/polaroid.html

Templates receive these variables:

Linkcard variables:

• url, display_url, title, archive_url
• escaped_url, escaped_display_url, escaped_title, escaped_archive_url

Polaroid variables:

• image_url, link_url, image_link_url, title, link_display, archive_url, width, height, alt
• escaped_* versions of all text fields

See default templates in gem's _includes/ directory for examples.

---
title: My Blog Post
---

Check out this cool site:

{% linkcard https://jekyllrb.com Jekyll - Simple, blog-aware, static sites %}

More content here...

---
title: Photo Gallery
photos:
  - url: /assets/photo1.jpg
    title: Sunset
  - url: /assets/photo2.jpg
    title: Mountains
---

{% for photo in page.photos %}
  {% polaroid {{ photo.url }} size=300x300 title={{ photo.title }} %}
{% endfor %}

Here's a large image:

![My Photo](photo.jpg =800x600)

And a smaller one:

![Thumbnail](thumb.jpg =150x150)

See CONTRIBUTING.md for development setup and guidelines.