Description

Day, week, and month calendars populated by your notes and to-dos, with click-through to the source note. Configure with simple YAML blocks. A GTD-friendly fork of Event Calendar by Franco Speziali.

Additional Information

Links:	Repository Homepage View source
Maintainers:	victorwiebe
Version:	0.7.0
Minimum app version:	2.7
Downloads: This version:	21
Last updated:	2026-07-18T21:31:31Z

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, a number, or all	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. scope: all scans every notebook in your entire profile — powerful for a global dashboard, but potentially slow on large profiles; a footnote reports how much was scanned, and a ⚠ appears past ~2000 notes. notebook: is ignored under scope: all.
notebook	notebook name, Parent/Child path, or folder id	this note's folder	Root the scan at a specific notebook instead of the one holding this note — even one in a different tree. scope then applies relative to it. A bare name must be unique; if several notebooks share it, qualify with a path (Work/Archive). Unknown/ambiguous → ⚠ warning + falls back to this note's folder.
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.

Kanban board

Alongside calendars, GTD Calendar can render a kanban board from your to-dos. Add a gtd-kanban block — on its own, or stacked beneath a calendar in the same dashboard note:

```gtd-kanban
title: Editorial Board
scope: this-folder
todos: all
sort-type: due-date
in-progress-tag: in-progress
card-detail: hover
done-window: 7
```

Three columns, driven by your to-dos' state:

• Backlog — every uncompleted to-do without the in-progress tag.
• In Progress — to-dos carrying the in-progress tag (default tag name in-progress; configurable).
• Done — completed to-dos, limited to those finished within done-window days (default 7; set all for the full history).

A completed to-do always lands in Done, even if it still carries the in-progress tag.

Option	Values	Default	Description
title	text	—	Heading above the board.
scope	this-folder, children, integer, all	this-folder	Same folder-scanning rules as the calendar, including all (every notebook — see the calendar table's caution).
notebook	notebook name, Parent/Child path, or folder id	this note's folder	Root the scan at a specific notebook (see the calendar table for the full resolution rules). scope applies relative to it.
todos	gtd-only, all, none	gtd-only	Which to-dos appear. gtd-only requires a gtd block; all includes every to-do in scope. (Plain notes never appear on the board.)
sort-type	due-date, title, modified-date	due-date	Order of cards within each column. Under due-date, cards with no due date sort last.
sort	asc, desc	asc	Sort direction.
in-progress-tag	text	in-progress	The tag that places a to-do in the In Progress column.
card-detail	hover, always, none	hover	Whether each card's due date / hover text shows on hover, always, or never.
done-window	integer or all	7	How many days back the Done column reaches.

Cards are compact (title, recurrence ↻ if applicable) and click through to the to-do. The board is read-only in this version — it reflects your to-dos' state but doesn't change it. (Drag-and-drop to move cards between columns is planned.)

The Matrix (Skeleton & Eisenhower)

A third view: a 2×2 prioritisation matrix. Add a gtd-matrix block anywhere:

```gtd-matrix
title: Priorities
todos: all
mode: skeleton
```

Two modes:

mode: skeleton (default) — the Skeleton Matrix

Built to complement the kanban and calendar, using the tags and dates you already maintain. Rows ask am I on this? (the in-progress tag); columns ask is the clock running? (due within urgent-window days — overdue counts — or carrying the urgent tag as a manual override):

	Due soon	Not due soon
Active	Do Next	Scheduled
Not active	On Deck	Backlog

On Deck is the quadrant to watch: due soon, not yet started. Nothing is ever labelled "Eliminate" — a Backlog item is simply low priority, not condemned. Dateless in-progress work sits in Scheduled (active, no clock). Completed to-dos don't appear at all.

mode: eisenhower — the classic

Quadrants from the urgent/important tags: Do First (both), Schedule (important), Delegate (urgent), Eliminate (neither).

Options

Option	Values	Default	Description
mode	skeleton, eisenhower	skeleton	Which matrix semantics to use.
title	text	—	Heading above the matrix.
scope	this-folder, children, integer, all	this-folder	Same folder-scanning rules as the calendar and kanban, including all (every notebook — see the calendar table's caution).
notebook	notebook name, Parent/Child path, or folder id	this note's folder	Root the scan at a specific notebook (see the calendar table for the full resolution rules). scope applies relative to it.
todos	gtd-only, all, none	gtd-only	Which to-dos appear. Plain notes never do.
sort-type	due-date, title, modified-date	due-date	Order within each quadrant; dateless cards sort last under due-date.
sort	asc, desc	asc	Sort direction.
urgent-tag	any tag name	urgent	Eisenhower's urgent axis; the Skeleton mode's manual due-soon override.
important-tag	any tag name	important	Eisenhower's important axis (unused in Skeleton mode).
in-progress-tag	any tag name	in-progress	Skeleton mode's active row — same tag as the kanban's In Progress column.
urgent-window	integer (days)	3	Skeleton mode: how close a due date must be to count as "due soon".
card-detail	hover, always, none	hover	Card detail line behaviour, as on the kanban.

Cards behave like kanban cards: compact, ↻ for recurring, click to open. Read-only.

Gantt chart

A timeline of projects built from items across your notes. Unlike the other views, gantt items opt in with their own ```gtd-gantt block (not the gtd block), and every item declares a project: — that's what groups items into swimlanes.

The same fence name does two jobs:

• A ```gtd-gantt block with a project: key is an item declaration. It renders in place as a small inline badge (gantt: <project>), and the item appears on any gantt chart that scans it.
• A ```gtd-gantt block without a project: key is the chart itself.

Item blocks

Put one in any note or to-do you want on the timeline:

```gtd-gantt
project: bluesky
begin-date: 2026-07-01     # notes only — the bar's span
end-date: 2026-07-14
bg-colour: teal            # optional, same styling keys as the gtd block
fg-colour: white
title: Design phase        # optional; defaults to the note title
text: Hover detail         # optional
```

• Notes become bars — a span from begin-date to end-date. Both are required and must be valid, with end-date on or after begin-date; otherwise the item is excluded with a ⚠ warning.
• To-dos become milestones — a ◆ marker on the to-do's native due date. begin-date/end-date on a to-do are ignored (with a warning). A to-do with no due date is excluded with a warning. Completed milestones render dimmed and struck through; recurring to-dos get a ↻.
• Dates accept yyyy-mm-dd (and mm-dd-yyyy), same as everywhere else.

There is no "Unscheduled" section — an item with no usable date simply doesn't appear (the warning tells you why).

Chart block

Put this where you want the timeline drawn:

```gtd-gantt
title: Roadmap
scope: children           # this-folder | children | N | all
filter-project: bluesky   # optional — limit the chart to one project
```

Option	Values	Default	What it does
title	text	—	Heading above the chart.
scope	this-folder, children, a number, or all	this-folder	Same folder-scanning rules as every other view.
notebook	notebook name, Parent/Child path, or folder id	this note's folder	Root the scan at a specific notebook (see the calendar table). Ignored under scope: all.
filter-project	project name	—	Limit the chart to a single project (case-insensitive).
sort-type	begin-date, title, modified-date	begin-date	Row order within each project.
sort	asc, desc	asc	Sort direction.
card-detail	hover, always, none	hover	none suppresses the hover tooltip on bars/milestones.

Note there is no notes/todos option — items opt in via their project: block, so those keys aren't used (and warn as unknown if set). Projects are shown alphabetically; the chart draws a month tick header, a red "today" line when today falls in range, and scrolls horizontally for wide ranges. Bars and milestones are clickable — they open the source note. Read-only.

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. See the note below.
• 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.

Mobile / Android

This plugin is built for Joplin desktop and is not expected to work on the Android or iOS apps. It depends on rendering custom code blocks in the note viewer and on two-way messaging between that view and the plugin — capabilities Joplin's mobile apps have historically not supported, or supported only partially. On mobile, a gtd-calendar block will most likely render as plain text or not at all, and drilldown won't work. The companion Repeating To-Dos plugin is desktop-only as well.

Your data is unaffected, though: the calendar is only a view. Your to-dos and their due dates are ordinary Joplin items that sync to mobile normally and appear in Joplin's built-in to-do list and search, with alarms intact — you just won't see the calendar rendering there. If you want a quick scheduled-items view on mobile, pair the calendar with Joplin's native to-do view or the Embed Search plugin on desktop.

Bugs & feedback

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

Development

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

Design notes and the full specification live in SPEC.md. Release history is in CHANGELOG.md.

Cutting a release

1. Bump version in both src/manifest.json and package.json (they must match — the Joplin plugin repo reads the manifest, npm reads package.json).
2. Add an entry to CHANGELOG.md.
3. npm publish (the prepare script rebuilds the .jpl fresh from source, so you can't accidentally publish a stale build).

If npm publish fails with E404 on the PUT, check npm whoami first — a 401 there means your login session has expired, which npm surfaces as a misleading 404 on publish. Fix with npm login --auth-type=legacy, or avoid it entirely with a granular access token so publishing never needs an interactive session.

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.