Timeline for Tropy

Timeline adds a navigable chronological view to a Tropy project. It reads the project already open in Tropy, arranges items by a chosen metadata date, and opens an item in Tropy when its title is clicked.

The interface follows Tropy's light and dark themes and is translated into English, Italian, French, and Spanish. All processing remains local.

Features

• Vertical timeline with collapsible year, month, or day groups.
• Clickable document titles that open the corresponding Tropy item.
• A second item-view toolbar button returns directly to the timeline after an item was opened from it; Tropy's normal library button remains available.
• Overview histogram for quickly jumping to a year or range of years.
• Automatic detection of the most likely date and title fields, with manual field selection.
• Scope by one Tropy list (folder), optionally including all nested lists.
• Required and excluded tags; required tags can use all or any matching.
• Additional include and exclude rules for any metadata field, title, date, tags, lists, creation date, or modification date.
• Search across title, metadata, tags, and list paths.
• Inclusive date range, ascending/descending order, comfortable, compact, and condensed views, plus an optional section for undated items.
• Native Tropy tag colors in cards and filter controls, including dot-only tag indicators in the compact and condensed views.
• Per-project filter persistence.
• Lazy-loaded cover thumbnails from Tropy's own local cache.

Installation

1. Download tropy-timeline-1.1.0.zip from the release.
2. Open Tropy → Preferences → Plugins.
3. Click Install Plugin and select the ZIP file.
4. Enable Timeline if Tropy does not enable it automatically.
5. Return to a project. A timeline button appears immediately to the left of the main search field.

Do not install GitHub's automatically generated “Source code” archives. Tropy expects the named release ZIP.

Use

Open a project and click the timeline icon in the main toolbar.

Lists and tags

Choose a list to limit the timeline to that list. “Include nested lists” treats all descendants as part of the same scope.

Each tag filter has three states:

1. neutral;
2. required (+);
3. excluded (−).

Clicking a tag cycles through these states. If several tags are required, choose whether an item must match all of them or at least one.

Tropy's synthetic ROOT list is omitted from displayed folder paths.

Navigation and display density

Click a period heading to collapse or expand it. The state is saved separately for each project.

After opening a document from Timeline, use the additional timeline button next to Tropy's normal back button to return to the same timeline and filters.

The Condensed density fits each document on a single row while retaining its date and tag-color dots.

Additional conditions

An inclusion rule keeps matching items. Inclusion rules can be combined with Match all or Match any. An exclusion rule removes a matching item; exclusion rules always use any semantics.

Available operators include text matching, equality, empty/not-empty checks, regular expressions, and date comparisons.

Dates

Timeline recognizes:

• ISO dates such as 1947-05-12, 1947-05, and 1947;
• numeric dates in day/month/year or month/day/year order;
• month names in English, Italian, French, Spanish, and German;
• common approximate or bracketed forms such as circa [1947].

For a range or a field containing several dates, the first recognizable date determines the item's position. The original metadata string remains visible on the card.

Compatibility and implementation note

The code targets Tropy 1.17.3 and the 1.18 development line.

Tropy's public plugin hooks currently cover import and export, but not custom project views. Timeline therefore uses the project window context supplied to plugins to add its toolbar button and reads Tropy's Redux project state. This is read-only except for dispatching Tropy's normal item.open command when a title is clicked. A future Tropy UI refactor may require a compatibility update.

Developing and debugging

Requirements: Node.js 18 or later and npm.

npm install
npm test
npm run build

For live development, run:

npm run watch

Then open Tropy's plugin folder from Help → Show Plugin Folder, create a tropy-timeline directory there, and symlink these built files into it:

ln -s /absolute/path/to/tropy-timeline/package.json package.json
ln -s /absolute/path/to/tropy-timeline/index.js index.js
ln -s /absolute/path/to/tropy-timeline/timeline.css timeline.css
ln -s /absolute/path/to/tropy-timeline/icon.svg icon.svg

Enable Developer mode in Tropy, reload the project window after a build, and use Tropy's Developer Tools for renderer logs and inspection. This follows the workflow recommended by the official Tropy sample plugin.

Tests

npm test
npm run lint

The tests cover multilingual and partial date parsing, metadata field detection, nested-list scope, required/excluded tags, additional conditions, date boundaries, ordering, and histogram bucketing.

Building a release

npm run build creates the two runtime files, index.js and timeline.css. The included GitHub Actions workflow runs tests and creates the correctly wrapped installable ZIP whenever a tag beginning with v is pushed.

git tag v1.1.0
git push origin v1.1.0

License

GNU Affero General Public License v3.0 or later.