# 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.

![Month grid view](https://gitea.skeletonworks.online/vwiebe/joplin-plugin-gtd-calendar/raw/branch/master/docs/screenshots/month-grid.png)

## 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
    ```

![Config and result side by side](https://gitea.skeletonworks.online/vwiebe/joplin-plugin-gtd-calendar/raw/branch/master/docs/screenshots/month-grid-config.png)

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
    ```

![A note with a gtd block](https://gitea.skeletonworks.online/vwiebe/joplin-plugin-gtd-calendar/raw/branch/master/docs/screenshots/gtd-block.png)

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):

![A todo scheduled by its native due date](https://gitea.skeletonworks.online/vwiebe/joplin-plugin-gtd-calendar/raw/branch/master/docs/screenshots/todo-due-date.png)

## 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](https://joplinapp.org/plugins/plugin/com.github.TheScriptingGuy.joplin-plugin-repeating-todos/)** 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.** 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](https://gitea.skeletonworks.online/vwiebe/joplin-plugin-gtd-calendar/issues), or find me on the Joplin forum.

## Development

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

Design notes and the full v1 specification live in [SPEC.md](SPEC.md).

## Credits & license

A fork of [Event Calendar](https://github.com/WeMakeMachines/joplin-plugin-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](https://victorwiebe.com). Creative work for an uncaring world.