2ec8d5f1c5
- README rewritten for end users: quick start, full option reference for both blocks, date-resolution rules, drilldown, limitations, credits - Four screenshots added under docs/screenshots/ - SPEC.md remains the design/developer document, linked from README
109 lines
5.4 KiB
Markdown
109 lines
5.4 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).
|
|
|
|
Manual install: download the `.jpl` from the [releases](https://gitea.skeletonworks.online/vwiebe/joplin-plugin-gtd-calendar/releases), then *Plugins → gear icon → Install from file*.
|
|
|
|
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.
|
|
|
|
## 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](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.
|