d3c0f0ee7f
- New gtd-kanban block renders a three-column board from to-dos: Backlog / In Progress / Done. Notes excluded; to-dos only. - Bucketing: Done wins (todo_completed), else in-progress tag, else Backlog. in-progress tag name configurable (IN_PROGRESS_TAG constant, in-progress-tag: option). - Backlog shows all uncompleted untagged to-dos; Done filtered to a configurable done-window (default 7 days; 'all' for full history). - Per-column sort: due-date (default; dateless last) | title | modified-date, asc/desc. - Compact cards with configurable detail panel (hover/always/none), recurrence ↻, click-to-open drilldown. Empty columns still shown. - Reuses the calendar data layer: scope resolution, inclusion, the getNoteTagTitles tag fetch from v0.2.0, gtd block parsing. - markdown-it renderer now handles both gtd-calendar and gtd-kanban fences (data-block-type); webview branches getEvents/getKanban. - SPEC sort-type vocabulary noted for cross-block consistency (modified_date accepted as alias). - Version 0.3.0; 32 new tests (65 total). Read-only — drag-and-drop write-back is v0.4.0.
156 lines
9.1 KiB
Markdown
156 lines
9.1 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.)
|
|
|
|
## 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.
|