GTD Calendar — a Joplin plugin

Your notes and to-dos, on a calendar, inside a note.

GTD Calendar renders day, week, and month calendars in any Joplin note — populated not by hand-maintained YAML, but by the actual notes and to-dos in the surrounding folder. Click an event and it opens the note. Items without a date collect in an Unscheduled bucket below the calendar, GTD-style.

How it works

Put a gtd-calendar fenced code block in a note. That note becomes a calendar of the notes and to-dos around it:

```gtd-calendar
view: month-grid
title: GTD Calendar
todos: all
```

Notes and to-dos opt in to the calendar with a gtd fenced code block — even an empty one. The block can also set a date (for plain notes), colours, an icon, and hover text:

```gtd
date: 2026-06-19
fg-colour: red
text: Seen on hover
```

To-dos don't need any of that for scheduling — their normal Joplin due date places them on the calendar automatically (when admitted by your todos: setting):

Installation

Search for GTD Calendar in Tools → Options → Plugins (desktop).

Requires Joplin 2.7+ on desktop.

The gtd-calendar block

Goes in the note that should display the calendar. All options are optional.

Option	Values	Default	What it does
view	day, week, month, month-grid	day	day/week/month (or d/w/m) render a compact tile strip spanning all events. month-grid (or grid) renders the entire current calendar month as a classic 7-column grid with weekday headers.
title	text	—	Heading above the calendar.
scope	this-folder, children, or a number	this-folder	Which folders to scan: just this one, all descendants, or n levels down (scope: 2). Broad scopes scan every note body in the tree — fine for normal folders, worth knowing for huge ones.
notes	gtd-only, all, none	gtd-only	Which plain notes appear: only those with a gtd block, every note in scope, or none.
todos	gtd-only, all, none	gtd-only	Same, for to-dos. todos: all is handy — every to-do with a due date lands on the calendar with zero markup.
sort	asc, desc	asc	Order of events within each day/week/month and in Unscheduled. The timeline itself is always chronological.
sort-type	title, modified_date	title	What sort sorts by.

Invalid values fall back to defaults and show a ⚠ warning above the calendar.

The gtd block

Goes in any note or to-do that should appear on the calendar. An empty block is valid — it's the minimal opt-in. All properties are optional:

Property	Example	What it does
date	2026-07-04	Schedules the item (yyyy-mm-dd or mm-dd-yyyy). Required for plain notes to appear in the grid; for to-dos it overrides the Joplin due date.
bg-colour	teal, #264653	Tile/chip background. Any CSS colour. (bgColor also accepted.) Without it, the item gets a stable pastel derived from its note ID.
fg-colour	white	Tile/chip text colour.
icon	🦴	Shown on the tile/chip instead of the first two characters of the title.
title	Launch day	Replaces the note's title on the calendar only.
text	Seen on hover	Detail line in the hover card / tooltip.

Where do dates come from?

1. A date: in the gtd block always wins.
2. Otherwise, a to-do uses its Joplin due date.
3. No date at all → the item appears in the Unscheduled section below the calendar: your dateless next-actions, always in view, one click from their notes.

To-dos keep being real Joplin to-dos throughout — due dates still sort, alarm, and sync exactly as before. Completed to-dos render checked and struck through.

Repeating to-dos

GTD Calendar plays nicely with the Repeating To-Dos plugin (v2). Install it, set a to-do to repeat (e.g. every Tuesday), and that to-do appears on the calendar at its next due date like any other — no extra setup. Recurring to-dos are marked with a ↻ symbol so you can tell them apart at a glance.

Because that plugin keeps a recurring to-do as a single item at its next due date, the calendar shows the next occurrence rather than every future one. Recurrence is detected via the recurring tag the plugin maintains; if you use a different recurrence tool that tags its to-dos recurring, the ↻ will appear for those too.

Drilldown

Everything is clickable: single-event tiles, every row of a multi-event hover card, every chip in the month grid, every Unscheduled chip. Clicking opens the source note.

Limitations

• Desktop only (relies on plugin messaging and the openNote command; mobile plugin support is partial).
• month-grid always shows the current month; there is no month navigation yet.
• The calendar refreshes when the note re-renders (e.g. switching notes); edits to other notes don't live-update an open calendar.

Bugs & feedback

Issues and ideas: the repository, or find me on the Joplin forum.

Development

npm install
npm test        # 47 unit tests
npm run dist    # builds publish/*.jpl

Design notes and the full v1 specification live in SPEC.md.

Credits & license

A fork of Event Calendar by Franco Speziali (WeMakeMachines), whose tile-strip design this plugin proudly keeps. Forked with gratitude under the MIT license; this plugin is MIT as well.

Made by Victor Wiebe. Creative work for an uncaring world.