jekyll-highlight-cards

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

Features

{% 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
jekyll freeze-archives - Opt-in command to freeze archive URLs into source
Customizable - Override HTML templates and CSS styles

Installation

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";

Usage

Linkcard Tag

Highlight links:

Linkcard visual example

{% 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:

Parameter	Description
URL	(required, first parameter)
Title	(optional, everything after URL until `archive:`)
`archive:URL`	Explicit archive URL
`archive:none`	Disable archive lookup

Polaroid Tag

Create polaroid-style image cards:

Polaroid visual example

{% 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:

Parameter	Description
Image URL	(required, first parameter)
`size=WxH`	Image dimensions. Formats: `300x200`, `300x`, `x200`, `300`, `400pxx300px`
`alt="..."`	Alt text for image (for accessibility)
`title="..."`	Title text displayed below image (also used as alt fallback)
`link="..."`	Explicit URL to link to (shows as visible link text)
`image_link="..."`	Override where the image links to (independent of visible link text)
`archive="..."`	Archive URL or `none` to disable

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;
}

Markdown Image Sizing

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.

Configuration

Internet Archive

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

Flag	Description
`JEKYLL_HIGHLIGHT_CARDS_ARCHIVE`	Enable build-time lookup to see if there is an IA snapshot available
`JEKYLL_HIGHLIGHT_CARDS_ARCHIVE_SAVE`	Also submit the URL to SavePageNow (runs even when CDX already found a snapshot)

You can selectively skip archive attempts for URLs that match site-configured regexes. Patterns are matched against the full URL string; use anchors when needed.

highlight_cards:
  noarchive:
    - ^https?://x\.com/.*
    - \Ahttps://something\.example\.com/.*

Freeze Archives Into Source

To look up Internet Archive snapshots once (instead of on each build) and write them into your source tags, run the freeze-archives Jekyll subcommand:

# Rehearse first — reports planned edits, writes nothing
bundle exec jekyll freeze-archives --dry-run

# Write archive: / archive= into eligible tags
bundle exec jekyll freeze-archives

Review the diff, then commit. The command does not commit for you, and it does not run as part of jekyll build.

How it differs from build-time lookup

Invoking freeze-archives performs CDX lookup — you do not need JEKYLL_HIGHLIGHT_CARDS_ARCHIVE=1.
SavePageNow stays gated: set JEKYLL_HIGHLIGHT_CARDS_ARCHIVE_SAVE=1 or pass --save.
Only literal http(s) URLs are frozen. Liquid targets like {{ page.url }} are skipped; build-time auto-lookup still covers those when enabled.
Tags that already have archive: / archive= / archive:none are left alone.

CSS Styles

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.

Template Customization

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.

Examples

Blog post with link card

---
title: My Blog Post
---

Check out this cool site:

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

More content here...

Gallery with polaroids

---
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 %}

Sized images in Markdown

Here's a large image:

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

And a smaller one:

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

Development

See CONTRIBUTING.md for development setup and guidelines.