From 855c301848a1ced7b910e6215a3cc96b6047db67 Mon Sep 17 00:00:00 2001 From: callumalpass Date: Sun, 30 Nov 2025 15:48:31 +1100 Subject: [PATCH] docs: add property types reference documentation (#1259) Add comprehensive documentation for frontmatter property types to help users understand expected data formats when creating tasks via templates or manual editing. --- docs/releases/unreleased.md | 6 + docs/settings/property-types-reference.md | 331 ++++++++++++++++++++++ docs/settings/task-properties.md | 4 +- mkdocs.yml | 1 + 4 files changed, 341 insertions(+), 1 deletion(-) create mode 100644 docs/settings/property-types-reference.md diff --git a/docs/releases/unreleased.md b/docs/releases/unreleased.md index 964ab262..0fd31782 100644 --- a/docs/releases/unreleased.md +++ b/docs/releases/unreleased.md @@ -26,6 +26,12 @@ Example: ## Added +- (#1259) Added [Property Types Reference](../settings/property-types-reference.md) documentation + - Documents expected data types (text, list, date, number) for all frontmatter properties + - Includes format specifications, examples, and a complete YAML reference + - Helps users create tasks via templates or manual frontmatter editing + - Thanks to @Oblique82 for the suggestion + - (#1248) Added formula property support for sub-grouping in Bases Task List view - Formula properties (e.g., `formula.myFormula`) now appear in the Sub-group by dropdown - Supports all Bases Value types including strings, numbers, booleans, dates, and lists diff --git a/docs/settings/property-types-reference.md b/docs/settings/property-types-reference.md new file mode 100644 index 00000000..c2f29c05 --- /dev/null +++ b/docs/settings/property-types-reference.md @@ -0,0 +1,331 @@ +# Property Types Reference + +This reference documents the expected data types for each frontmatter property that TaskNotes uses. + +[← Back to Settings](../settings.md) + +## Quick Reference + +| Property | Type | Example | +|----------|------|---------| +| title | text | `"My Task"` | +| status | text | `"open"`, `"in-progress"`, `"done"` | +| priority | text | `"low"`, `"normal"`, `"high"` | +| due | text (date) | `"2025-01-15"` | +| scheduled | text (date) | `"2025-01-10"` | +| completedDate | text (date) | `"2025-01-20"` | +| dateCreated | text (datetime) | `"2025-01-01T08:00:00Z"` | +| dateModified | text (datetime) | `"2025-01-15T10:30:00Z"` | +| tags | list | `["work", "urgent"]` | +| contexts | list | `["@office", "@home"]` | +| projects | list | `["[[Project A]]"]` | +| timeEstimate | number | `120` (minutes) | +| recurrence | text | `"FREQ=WEEKLY;BYDAY=MO"` | +| recurrence_anchor | text | `"scheduled"` or `"completion"` | +| timeEntries | list (objects) | See [Time Entries](#time-entries) | +| blockedBy | list (objects) | See [Dependencies](#dependencies-blockedby) | +| reminders | list (objects) | See [Reminders](#reminders) | +| complete_instances | list | `["2025-01-08", "2025-01-15"]` | +| skipped_instances | list | `["2025-01-22"]` | +| icsEventId | list | `["event-abc123"]` | + +--- + +## Property Details + +### Text Properties + +#### title +- **Type:** text (string) +- **Description:** The task's title or name +- **Example:** `title: "Complete project documentation"` + +#### status +- **Type:** text (string) +- **Description:** The task's current status. Must match one of the status values configured in your settings. +- **Default values:** `"open"`, `"in-progress"`, `"done"` +- **Example:** `status: "in-progress"` +- **Note:** Also supports boolean values (`true`/`false`) for Obsidian checkbox compatibility. See [Boolean Status Values](task-properties.md#boolean-status-values). + +#### priority +- **Type:** text (string) +- **Description:** The task's priority level. Must match one of the priority values configured in your settings. +- **Default values:** `"low"`, `"normal"`, `"high"` +- **Example:** `priority: "high"` + +--- + +### Date Properties + +All date properties are stored as **text strings** in your frontmatter. TaskNotes expects specific formats: + +#### due + +- **Type:** text (date string) +- **Format:** `YYYY-MM-DD` or ISO 8601 timestamp +- **Description:** The task's due date +- **Examples:** + ```yaml + due: "2025-01-15" + due: "2025-01-15T17:00:00" + ``` + +#### scheduled + +- **Type:** text (date string) +- **Format:** `YYYY-MM-DD` or ISO 8601 timestamp +- **Description:** When the task is scheduled to be worked on +- **Examples:** + ```yaml + scheduled: "2025-01-10" + scheduled: "2025-01-10T09:00:00" + ``` + +#### completedDate + +- **Type:** text (date string) +- **Format:** `YYYY-MM-DD` +- **Description:** The date when the task was completed +- **Example:** `completedDate: "2025-01-20"` + +#### dateCreated + +- **Type:** text (datetime string) +- **Format:** ISO 8601 timestamp +- **Description:** When the task was created +- **Example:** `dateCreated: "2025-01-01T08:00:00Z"` + +#### dateModified + +- **Type:** text (datetime string) +- **Format:** ISO 8601 timestamp +- **Description:** When the task was last modified +- **Example:** `dateModified: "2025-01-15T10:30:00Z"` + +--- + +### List Properties + +List properties must be arrays, even when containing a single value. + +#### tags + +- **Type:** list (array of strings) +- **Description:** Tags associated with the task +- **Examples:** + ```yaml + tags: ["work", "documentation"] + tags: + - work + - documentation + ``` + +#### contexts + +- **Type:** list (array of strings) +- **Description:** Context labels for the task +- **Examples:** + ```yaml + contexts: ["office", "computer"] + contexts: + - "office" + - "computer" + ``` + +#### projects + +- **Type:** list (array of strings) +- **Description:** Project references (typically wiki-links) +- **Examples:** + ```yaml + projects: ["[[Website Redesign]]", "[[Q1 Planning]]"] + projects: + - "[[Website Redesign]]" + - "[[Q1 Planning]]" + ``` + +--- + +### Numeric Properties + +#### timeEstimate +- **Type:** number +- **Unit:** minutes +- **Description:** Estimated time to complete the task +- **Example:** `timeEstimate: 120` (2 hours) + +--- + +### Recurrence Properties + +#### recurrence + +- **Type:** text (string) +- **Format:** RFC 5545 RRULE format +- **Description:** Defines how the task repeats +- **Examples:** + ```yaml + recurrence: "FREQ=DAILY" + recurrence: "FREQ=WEEKLY;BYDAY=MO,WE,FR" + recurrence: "FREQ=MONTHLY;BYMONTHDAY=1" + ``` + +#### recurrence_anchor + +- **Type:** text (string) +- **Valid values:** `"scheduled"` or `"completion"` +- **Description:** Determines whether the next occurrence is calculated from the scheduled date or when the task was completed +- **Example:** `recurrence_anchor: "scheduled"` + +#### complete_instances + +- **Type:** list (array of date strings) +- **Format:** `YYYY-MM-DD` +- **Description:** Dates when recurring task instances were completed +- **Example:** + ```yaml + complete_instances: + - "2025-01-08" + - "2025-01-15" + ``` + +#### skipped_instances + +- **Type:** list (array of date strings) +- **Format:** `YYYY-MM-DD` +- **Description:** Dates when recurring task instances were skipped +- **Example:** + ```yaml + skipped_instances: + - "2025-01-22" + ``` + +--- + +### Complex Properties + +These properties contain structured data with multiple fields. + +#### Time Entries + +- **Type:** list (array of objects) +- **Description:** Time tracking entries for the task +- **Structure:** + ```yaml + timeEntries: + - startTime: "2025-01-15T10:30:00Z" # Required: ISO 8601 timestamp + endTime: "2025-01-15T11:15:00Z" # Optional: ISO 8601 timestamp + description: "Initial work" # Optional: text + ``` + +#### Dependencies (blockedBy) + +- **Type:** list (array of objects) +- **Description:** Tasks that must be completed before this task can start +- **Structure:** + ```yaml + blockedBy: + - uid: "path/to/blocking-task.md" # Required: path to blocking task + reltype: "FINISHTOSTART" # Required: relationship type + gap: "P1D" # Optional: ISO 8601 duration offset + ``` +- **Relationship types:** `FINISHTOSTART`, `STARTTOSTART`, `FINISHTOFINISH`, `STARTTOFINISH` + - Note: As of version 4.1.0, only the FINISHTOSTART duration offset is supported + +#### Reminders + +- **Type:** list (array of objects) +- **Description:** Reminder notifications for the task +- **Structure for relative reminders:** + ```yaml + reminders: + - id: "rem_1" # Required: unique identifier + type: "relative" # Required: "relative" or "absolute" + relatedTo: "due" # Required for relative: "due" or "scheduled" + offset: "-PT1H" # Required for relative: ISO 8601 duration + description: "1 hour before due" # Optional: description + ``` +- **Structure for absolute reminders:** + ```yaml + reminders: + - id: "rem_2" + type: "absolute" + absoluteTime: "2025-01-15T09:00:00Z" # Required for absolute: ISO 8601 timestamp + description: "Morning reminder" + ``` + +#### icsEventId + +- **Type:** list (array of strings) +- **Description:** ICS calendar event IDs linked to this task +- **Example:** + ```yaml + icsEventId: + - "event-abc123" + - "event-def456" + ``` + +--- + +## Complete Example + +Here's a complete task with all property types: + +```yaml +--- +title: "Complete quarterly report" +status: "in-progress" +priority: "high" +due: "2025-01-31" +scheduled: "2025-01-25" +tags: + - work + - reports +contexts: + - "@office" +projects: + - "[[Q1 Planning]]" +timeEstimate: 240 +dateCreated: "2025-01-01T08:00:00Z" +dateModified: "2025-01-20T14:30:00Z" +timeEntries: + - startTime: "2025-01-20T10:00:00Z" + endTime: "2025-01-20T11:30:00Z" +blockedBy: + - uid: "tasks/gather-data.md" + reltype: "FINISHTOSTART" +reminders: + - id: "rem_1" + type: "relative" + relatedTo: "due" + offset: "-P1D" + description: "Due tomorrow" +--- +``` + +--- + +## Field Mapping + +All property names can be customized via **Settings → Task Properties → Field Mapping**. If you change a field mapping, TaskNotes will read and write using your custom property name. + +For example, if you map `due` to `dueDate`, TaskNotes will expect: +```yaml +dueDate: "2025-01-15" +``` + +See [Field Mapping](task-properties.md#field-mapping) for configuration details. + +--- + +## Custom User Fields + +You can define additional properties with these types: + +- **text** - Single text value +- **number** - Numeric value +- **date** - Date string (YYYY-MM-DD) +- **boolean** - true/false +- **list** - Array of values + +See [Custom User Fields](task-properties.md#custom-user-fields) for configuration details. diff --git a/docs/settings/task-properties.md b/docs/settings/task-properties.md index 0da1f383..e5ffb3cf 100644 --- a/docs/settings/task-properties.md +++ b/docs/settings/task-properties.md @@ -1,10 +1,12 @@ - # Task Properties Settings These settings allow you to define custom statuses, priorities, and user fields for your tasks. [← Back to Settings](../settings.md) +!!! tip "Looking for property type documentation?" + See the [Property Types Reference](property-types-reference.md) for detailed documentation on the expected data types (text, list, date, etc.) for each frontmatter property. + ## Task Statuses Customize the status options available for your tasks. These statuses control the task lifecycle and determine when tasks are considered complete. diff --git a/mkdocs.yml b/mkdocs.yml index a14c7113..afa0fc00 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -60,6 +60,7 @@ nav: - General: settings/general.md - Features: settings/features.md - Task Properties: settings/task-properties.md + - Property Types Reference: settings/property-types-reference.md - Defaults & Templates: settings/defaults.md - Task Defaults: settings/task-defaults.md - Appearance & UI: settings/appearance.md