4cb6700a20
- New gtd-matrix block: 2x2 prioritisation grid with axis headers (Urgent / Not urgent x Important / Not important) - Quadrants from two configurable tags (urgent-tag default 'urgent', important-tag default 'important'): both -> Do First; important -> Schedule; urgent -> Delegate; neither -> Eliminate (default bucket) - Completed to-dos excluded entirely (prioritisation view, not tracking; kanban Done is where completions live); to-dos only; matrix note excluded; warns when both axis tags are identical - Same scope/todos/sort-type/sort/card-detail options as kanban; cards reuse kanban rendering (compact, recurrence mark, drilldown) - Quadrant colour accents: red Do First, blue Schedule, amber Delegate, grey Eliminate - SPEC roadmap restructured: matrix shipped as v0.4.0 (views axis); drag-and-drop + create-from-view clustered as the v0.5.0+ authoring epic with multi-board refresh and trigger/target questions recorded - Version 0.4.0; 11 new tests (80 total); README documented
191 lines
11 KiB
Markdown
191 lines
11 KiB
Markdown
# 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](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.
|
||
|
||
## 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 | `this-folder` | Same folder-scanning rules as the calendar. |
|
||
| `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.)
|
||
|
||
## Eisenhower Matrix
|
||
|
||
A third view: a 2×2 prioritisation matrix, driven by two tags. Add a `gtd-matrix` block anywhere:
|
||
|
||
````
|
||
```gtd-matrix
|
||
title: Priorities
|
||
todos: all
|
||
urgent-tag: urgent
|
||
important-tag: important
|
||
```
|
||
````
|
||
|
||
To-dos are sorted into four quadrants by which of the two axis tags they carry:
|
||
|
||
| | **Urgent** | **Not urgent** |
|
||
|---|---|---|
|
||
| **Important** | Do First | Schedule |
|
||
| **Not important** | Delegate | Eliminate |
|
||
|
||
A to-do with neither tag lands in **Eliminate** — the matrix's pointed default. **Completed to-dos don't appear at all**: the matrix is for prioritising open work (the kanban's Done column is where completions live).
|
||
|
||
| Option | Values | Default | Description |
|
||
|---|---|---|---|
|
||
| `title` | text | — | Heading above the matrix. |
|
||
| `scope` | `this-folder`, `children`, integer | `this-folder` | Same folder-scanning rules as the calendar and kanban. |
|
||
| `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` | The tag marking the urgent axis. |
|
||
| `important-tag` | any tag name | `important` | The tag marking the important axis. |
|
||
| `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.
|
||
|
||
## 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.
|