expl0it3r / kirby-timeline

1.0.1 2026-10-04 10:41 UTC

Requires

• getkirby/composer-installer: ^1.2

MIT

• Lukas Dürrenberger

Published on Packagist.org on 2026-10-04 10:45 UTC

README

A vertical timeline for Kirby: events on both sides of a line, grouped by year, with category filters and a search.

The events are rendered by PHP, so the timeline is complete without JavaScript. The script adds the filters, the search and folds the details away until an event is clicked.

Installation

Both Composer and git submodules are supported. Built and tested with Kirby 5.

Composer

composer require expl0it3r/kirby-timeline

Git Submodule

git submodule add https://github.com/eXpl0it3r/kirby-timeline.git site/plugins/kirby-timeline

Download

Download the repository and copy its files to site/plugins/kirby-timeline.

Usage

Add the field to the blueprint of a page and set your categories, e.g. in site/blueprints/pages/history.yml:

title: History
fields:
  timeline:
    extends: fields/timeline
    fields:
      category:
        options:
          release: Releases
          patch: Patches

Enter the events in the Panel, or write them directly to the content file:

Title: History

----

Timeline:

- 
  date: 2014-07-29
  category: release
  major: true
  title: Version 1.0 released
  detail: After two years of beta the first stable version is out.
- 
  date: 2014-09
  category: patch
  title: Version 1.0.1 fixes the installer

Then call the snippet in the template, here site/templates/history.php:

<?php snippet('timeline', [
    'events'     => $page->timeline(),
    'categories' => ['release' => 'Releases', 'patch' => 'Patches'],
]) ?>

That's all you need, the stylesheet and the script are loaded by the snippet. The sections below cover the options in more detail.

Blueprint

The plugin comes with a structure field for the events. Extend it and set the categories of your site:

fields:
  timeline:
    extends: fields/timeline
    fields:
      category:
        options:
          release: Releases
          patch: Patches

An event has the following fields:

• date as YYYY, YYYY-MM or YYYY-MM-DD, an event with only a year or a month comes before the dated ones of that year or month
• category is one of your options
• major marks the event with an accent
• title
• detail is shown once the event is clicked
• label replaces the formatted date, e.g. "Second half of 2015"

Snippet

<?php snippet('timeline', [
    'events'     => $page->timeline(),
    'categories' => [
        'release' => ['label' => 'Releases', 'shape' => 'diamond', 'color' => '#f78f0b'],
        'patch'   => ['label' => 'Patches', 'shape' => 'square'],
    ],
]) ?>

• events is the structure field, its structure or an array of arrays

• categories are the filters. A category is either just its label or an array with label, shape (diamond, square, circle or triangle) and color (any CSS color, also var(--something)). Events of a category that isn't listed are left out. Without categories there are no filters and every event is shown.

• groups are the headings: 'year' (default), 'none' or your own, as start dates with their headings:

  'groups' => ['0000' => 'Early Days', '2012' => 'Beta', '2014' => 'After the Release'],

• placeholder is the placeholder of the search

• search set to false leaves the search out

• assets set to false skips the tags for the stylesheet and the script, if you'd rather bundle them yourself. Otherwise the first timeline of a page brings them along.

Styling

Everything that depends on the site is a custom property. Set them on .timeline or anywhere above it:

.timeline {
    --timeline-bg: #fff;
    --timeline-surface: #f4f4f4;
    --timeline-surface-active: #e6e6e6;
    --timeline-text: #333;
    --timeline-heading: #111;
    --timeline-muted: #777;
    --timeline-border: #ddd;
    --timeline-accent: #f78f0b;
    --timeline-line: linear-gradient(#5cb8ff, #f78f0b);
    --timeline-radius: 5px;
    --timeline-font-mono: monospace;
    /* Height of a fixed navigation, so the filters stick below it */
    --timeline-sticky-top: 60px;
}

The defaults are made for a dark page.

Languages

The texts of the plugin are translated to English and German. Add or overwrite them in your language files:

'timeline.search' => 'Search the timeline',
'timeline.count'  => '{count} of {total} events',
'timeline.empty'  => 'Nothing matches. Try a different filter or search term.',
'timeline.months' => 'Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec',

License

This software is available under the MIT license, see the license file.