jekyll-timeline 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6ba528cce1ef2c9f28ba15637bb84e820e0daa26cef50676d47ed500d732cf01
+  data.tar.gz: 314be5deed55191ada292275d17b0a0ef3e3af3416d3c1613c517c493235134d
+SHA512:
+  metadata.gz: c427bda6e18cfbd29b8c30f9553ac6f249030f6fc2ad83993d7c4762a3deda4763c4ab120c2eecaad009fc6c8d22f13e6fe6c12451aab0bbd11c90de86b386d8
+  data.tar.gz: 2c8593e301ba653a05f14530ea3d6b6ea1a5359fb7de9caa2bf989210b3aaf587624b4925b598888e505e2b8b11b6f57b6848f000eabcc8437762dc9b190b704

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-08-22
+
+### Added
+- Initial release
+- `{% timeline %}` / `{% endtimeline %}` outer block tag
+- `{% event %}` / `{% endevent %}` inner block tag with `date`, `title`, `icon`, `color` attributes
+- `order="asc"` (default) and `order="desc"` sort support
+- Icon support: Font Awesome classes, emoji, plain text, or empty dot fallback
+- `timeline.default_icon_prefix` config option (default: `fa-solid`)
+- Pure HTML+CSS output — no JavaScript, no external dependencies

data/CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jchance/jekyll-timeline.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason Chance
+
+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,124 @@
+# 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](https://badge.fury.io/rb/jekyll-timeline.svg)](https://rubygems.org/gems/jekyll-timeline)
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "jekyll-timeline"
+```
+
+Add to `_config.yml`:
+
+```yaml
+plugins:
+  - jekyll-timeline
+```
+
+Run `bundle install`.
+
+Copy `_timeline.scss` from the gem into your site's SCSS directory and import it:
+
+```scss
+@import "timeline";
+```
+
+## Usage
+
+Wrap events in a `{% timeline %}` block. Each `{% timeline_event %}` block is one entry.
+
+```liquid
+{% 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
+
+```liquid
+{% 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:
+
+```liquid
+{% 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:**
+
+```liquid
+{% timeline_event icon="🚀" %}
+```
+
+**No icon** — omit the attribute entirely for a neutral dot:
+
+```liquid
+{% timeline_event date="2024" title="Something happened" %}
+```
+
+## Configuration
+
+All options are optional:
+
+```yaml
+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:
+
+```css
+: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

data/lib/jekyll/timeline_tag.rb

@@ -0,0 +1,100 @@
+require "jekyll"
+
+module Jekyll
+  TIMELINE_ATTR_RE = /(\w+)\s*=\s*(?:"([^"]*)"|'([^']*)'|(\S+))/
+
+  def self.parse_attrs(markup)
+    attrs = {}
+    markup.scan(TIMELINE_ATTR_RE) do |key, dq, sq, bare|
+      attrs[key] = dq || sq || bare || ""
+    end
+    attrs
+  end
+
+  # Inner block tag — registered so Liquid knows about it.
+  # When rendered standalone (excerpt, search.json), outputs nothing silently.
+  # When rendered inside {% timeline %}, its output is collected by the outer tag.
+  class TimelineEventTag < Liquid::Block
+    def initialize(tag_name, markup, tokens)
+      super
+      @attributes = Jekyll.parse_attrs(markup)
+    end
+
+    def render(context)
+      site   = context.registers[:site]
+      config = site.config["timeline"] || {}
+      default_prefix = config["default_icon_prefix"] || "fa-solid"
+
+      content = super.strip
+
+      rendered_content = begin
+        converter = site.find_converter_instance(Jekyll::Converters::Markdown)
+        converter.convert(content)
+      rescue StandardError
+        content
+      end
+
+      date  = @attributes["date"]  || ""
+      title = @attributes["title"] || ""
+      icon  = @attributes["icon"]
+      color = @attributes["color"]
+
+      color_style = color ? %( style="--timeline-event-color: #{color};") : ""
+
+      icon_html = if icon.nil? || icon.strip.empty?
+        '<span class="timeline__icon timeline__icon--empty"></span>'
+      elsif !icon.match?(/[a-zA-Z]/) || (icon.length <= 4 && !icon.include?("-"))
+        %(<span class="timeline__icon timeline__icon--text">#{icon}</span>)
+      else
+        classes = icon.include?(" ") ? icon : "#{default_prefix} #{icon}"
+        %(<span class="timeline__icon"><i class="#{classes}" aria-hidden="true"></i></span>)
+      end
+
+      html = <<~HTML
+        <div class="timeline__event"#{color_style}>
+          #{icon_html}
+          <div class="timeline__content">
+            <div class="timeline__date">#{date}</div>
+            <div class="timeline__title">#{title}</div>
+            <div class="timeline__body">#{rendered_content.strip}</div>
+          </div>
+        </div>
+      HTML
+
+      # If inside a timeline, accumulate; otherwise silently drop
+      if context.registers[:timeline_events]
+        context.registers[:timeline_events] << html.strip
+      end
+      ""
+    end
+  end
+
+  # Outer block tag
+  class TimelineTag < Liquid::Block
+    def initialize(tag_name, markup, tokens)
+      super
+      @attributes = Jekyll.parse_attrs(markup)
+    end
+
+    def render(context)
+      context.registers[:timeline_events] = []
+      super
+
+      events = context.registers[:timeline_events] || []
+      order  = @attributes["order"] || "asc"
+      events = events.reverse if order == "desc"
+
+      # Clean up so nested timelines don't bleed
+      context.registers[:timeline_events] = nil
+
+      <<~HTML
+        <div class="timeline">
+          #{events.join("\n  ")}
+        </div>
+      HTML
+    end
+  end
+end
+
+Liquid::Template.register_tag("timeline_event", Jekyll::TimelineEventTag)
+Liquid::Template.register_tag("timeline", Jekyll::TimelineTag)

data/lib/jekyll-timeline.rb

@@ -0,0 +1,4 @@
+require "jekyll"
+require "liquid"
+
+require_relative "jekyll/timeline_tag"

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-timeline
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jason Chance
+bindir: bin
+cert_chain: []
+date: 2026-08-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: 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.
+email:
+- jchance@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- lib/jekyll-timeline.rb
+- lib/jekyll/timeline_tag.rb
+homepage: https://jasonchance.com/projects/jekyll-timeline/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://jasonchance.com/projects/jekyll-timeline/
+  source_code_uri: https://github.com/jchance/jekyll-timeline
+  changelog_uri: https://github.com/jchance/jekyll-timeline/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/jchance/jekyll-timeline/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Jekyll Liquid tags for rendering a pure HTML/CSS vertical timeline
+test_files: []