jekyll-timeline

A Jekyll plugin providing {% timeline %} and {% timeline_event %} block tags that render a vertical timeline component. Pure HTML+CSS output — no JavaScript, no external dependencies.

Installation

Add to your Gemfile:

gem "jekyll-timeline"

Add to _config.yml:

plugins:
  - jekyll-timeline

Run bundle install.

Copy _timeline.scss from the gem into your site's SCSS directory and import it:

@import "timeline";

Usage

Wrap events in a {% timeline %} block. Each {% timeline_event %} block is one entry.

{% timeline %}

{% timeline_event date="January 2024" title="Project launched" icon="fa-rocket" %}
We shipped the first public release after six months of development.
{% endtimeline_event %}

{% timeline_event date="March 2024" title="1,000 users" icon="fa-users" color="#2ecc71" %}
Crossed 1,000 active users. Added team management features.
{% endtimeline_event %}

{% timeline_event date="June 2024" title="v2.0 released" icon="fa-bolt" %}
Complete rewrite with improved performance and a new API.
{% endtimeline_event %}

{% endtimeline %}

Reverse order

{% timeline order="desc" %}
...
{% endtimeline %}

Event attributes

Attribute	Required	Description
date	No	Display date string (any format — it's not parsed)
title	No	Event headline
icon	No	Icon class(es), emoji, or plain text. Omit for dot fallback.
color	No	CSS color value for this event's icon background

Icon formats

Font Awesome classes — pass one or two CSS classes:

{% timeline_event icon="fa-rocket" %}          <!-- uses default_icon_prefix -->
{% timeline_event icon="fa-solid fa-rocket" %} <!-- explicit style -->
{% timeline_event icon="fa-brands fa-github" %}
{% timeline_event icon="fa-duotone fa-star" %} <!-- FA Pro -->

Emoji:

{% timeline_event icon="🚀" %}

No icon — omit the attribute entirely for a neutral dot:

{% timeline_event date="2024" title="Something happened" %}

Configuration

All options are optional:

timeline:
  default_icon_prefix: "fa-solid"  # prepended when icon has no spaces (default: fa-solid)

Styling

Copy _timeline.scss into your site and customize via CSS custom properties:

:root {
  --timeline-line-color: #dee2e6;     /* vertical line color */
  --timeline-icon-bg: #6c757d;        /* default icon circle background */
  --timeline-icon-color: #fff;        /* icon/emoji color */
  --timeline-date-color: #6c757d;     /* date label color */
  --timeline-title-color: inherit;    /* event title color */
  --timeline-body-color: inherit;     /* body text color */
}

Per-event color override via the color= attribute sets --timeline-event-color inline on that event, overriding --timeline-icon-bg for that circle only.

GitHub Pages compatibility

Compatible with GitHub Pages when built via a custom GitHub Actions workflow. Not compatible with the default GitHub Pages safe-mode build.

License

MIT