Project

jekyll-timeline

0.0
The project is in a healthy, maintained state
jekyll-timelinejchance/jekyll-timelineHomepageDocumentationSource CodeBug TrackerWiki
A Jekyll plugin providing {% timeline %} and {% event %} block tags that render a vertical timeline component. Pure HTML+CSS output — no JavaScript, no external dependencies. Supports icon libraries (Font Awesome, emoji, or plain text) and per-event color customization.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
2,709
Stars
1
Forks
0
Watchers
0
 Releases
Current version
0.1.0
Total releases
1
First release
2026-08-22
Latest release
2026-08-22
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2026-08-22
Reverse Dependencies
0

 Dependencies

Runtime

jekyll
~> 4.0
 Project Readme

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.

Gem Version

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