Skip to content

Commit 833b252

Browse files
callumalpasscallumalpass
committed
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.
1 parent 96bb0b1 commit 833b252

File tree

3 files changed

+335
-1
lines changed

3 files changed

+335
-1
lines changed

‎docs/settings/property-types-reference.md‎

Lines changed: 331 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,331 @@
1+
# Property Types Reference
2+
3+
This reference documents the expected data types for each frontmatter property that TaskNotes uses.
4+
5+
[← Back to Settings](../settings.md)
6+
7+
## Quick Reference
8+
9+
| Property | Type | Example |
10+
|----------|------|---------|
11+
| title | text | `"My Task"` |
12+
| status | text | `"open"`, `"in-progress"`, `"done"` |
13+
| priority | text | `"low"`, `"normal"`, `"high"` |
14+
| due | text (date) | `"2025-01-15"` |
15+
| scheduled | text (date) | `"2025-01-10"` |
16+
| completedDate | text (date) | `"2025-01-20"` |
17+
| dateCreated | text (datetime) | `"2025-01-01T08:00:00Z"` |
18+
| dateModified | text (datetime) | `"2025-01-15T10:30:00Z"` |
19+
| tags | list | `["work", "urgent"]` |
20+
| contexts | list | `["@office", "@home"]` |
21+
| projects | list | `["[[Project A]]"]` |
22+
| timeEstimate | number | `120` (minutes) |
23+
| recurrence | text | `"FREQ=WEEKLY;BYDAY=MO"` |
24+
| recurrence_anchor | text | `"scheduled"` or `"completion"` |
25+
| timeEntries | list (objects) | See [Time Entries](#time-entries) |
26+
| blockedBy | list (objects) | See [Dependencies](#dependencies-blockedby) |
27+
| reminders | list (objects) | See [Reminders](#reminders) |
28+
| complete_instances | list | `["2025-01-08", "2025-01-15"]` |
29+
| skipped_instances | list | `["2025-01-22"]` |
30+
| icsEventId | list | `["event-abc123"]` |
31+
32+
---
33+
34+
## Property Details
35+
36+
### Text Properties
37+
38+
#### title
39+
- **Type:** text (string)
40+
- **Description:** The task's title or name
41+
- **Example:** `title: "Complete project documentation"`
42+
43+
#### status
44+
- **Type:** text (string)
45+
- **Description:** The task's current status. Must match one of the status values configured in your settings.
46+
- **Default values:** `"open"`, `"in-progress"`, `"done"`
47+
- **Example:** `status: "in-progress"`
48+
- **Note:** Also supports boolean values (`true`/`false`) for Obsidian checkbox compatibility. See [Boolean Status Values](task-properties.md#boolean-status-values).
49+
50+
#### priority
51+
- **Type:** text (string)
52+
- **Description:** The task's priority level. Must match one of the priority values configured in your settings.
53+
- **Default values:** `"low"`, `"normal"`, `"high"`
54+
- **Example:** `priority: "high"`
55+
56+
---
57+
58+
### Date Properties
59+
60+
All date properties are stored as **text strings** in your frontmatter. TaskNotes expects specific formats:
61+
62+
#### due
63+
64+
- **Type:** text (date string)
65+
- **Format:** `YYYY-MM-DD` or ISO 8601 timestamp
66+
- **Description:** The task's due date
67+
- **Examples:**
68+
```yaml
69+
due: "2025-01-15"
70+
due: "2025-01-15T17:00:00"
71+
```
72+
73+
#### scheduled
74+
75+
- **Type:** text (date string)
76+
- **Format:** `YYYY-MM-DD` or ISO 8601 timestamp
77+
- **Description:** When the task is scheduled to be worked on
78+
- **Examples:**
79+
```yaml
80+
scheduled: "2025-01-10"
81+
scheduled: "2025-01-10T09:00:00"
82+
```
83+
84+
#### completedDate
85+
86+
- **Type:** text (date string)
87+
- **Format:** `YYYY-MM-DD`
88+
- **Description:** The date when the task was completed
89+
- **Example:** `completedDate: "2025-01-20"`
90+
91+
#### dateCreated
92+
93+
- **Type:** text (datetime string)
94+
- **Format:** ISO 8601 timestamp
95+
- **Description:** When the task was created
96+
- **Example:** `dateCreated: "2025-01-01T08:00:00Z"`
97+
98+
#### dateModified
99+
100+
- **Type:** text (datetime string)
101+
- **Format:** ISO 8601 timestamp
102+
- **Description:** When the task was last modified
103+
- **Example:** `dateModified: "2025-01-15T10:30:00Z"`
104+
105+
---
106+
107+
### List Properties
108+
109+
List properties must be arrays, even when containing a single value.
110+
111+
#### tags
112+
113+
- **Type:** list (array of strings)
114+
- **Description:** Tags associated with the task
115+
- **Examples:**
116+
```yaml
117+
tags: ["work", "documentation"]
118+
tags:
119+
- work
120+
- documentation
121+
```
122+
123+
#### contexts
124+
125+
- **Type:** list (array of strings)
126+
- **Description:** Context labels for the task
127+
- **Examples:**
128+
```yaml
129+
contexts: ["office", "computer"]
130+
contexts:
131+
- "office"
132+
- "computer"
133+
```
134+
135+
#### projects
136+
137+
- **Type:** list (array of strings)
138+
- **Description:** Project references (typically wiki-links)
139+
- **Examples:**
140+
```yaml
141+
projects: ["[[Website Redesign]]", "[[Q1 Planning]]"]
142+
projects:
143+
- "[[Website Redesign]]"
144+
- "[[Q1 Planning]]"
145+
```
146+
147+
---
148+
149+
### Numeric Properties
150+
151+
#### timeEstimate
152+
- **Type:** number
153+
- **Unit:** minutes
154+
- **Description:** Estimated time to complete the task
155+
- **Example:** `timeEstimate: 120` (2 hours)
156+
157+
---
158+
159+
### Recurrence Properties
160+
161+
#### recurrence
162+
163+
- **Type:** text (string)
164+
- **Format:** RFC 5545 RRULE format
165+
- **Description:** Defines how the task repeats
166+
- **Examples:**
167+
```yaml
168+
recurrence: "FREQ=DAILY"
169+
recurrence: "FREQ=WEEKLY;BYDAY=MO,WE,FR"
170+
recurrence: "FREQ=MONTHLY;BYMONTHDAY=1"
171+
```
172+
173+
#### recurrence_anchor
174+
175+
- **Type:** text (string)
176+
- **Valid values:** `"scheduled"` or `"completion"`
177+
- **Description:** Determines whether the next occurrence is calculated from the scheduled date or when the task was completed
178+
- **Example:** `recurrence_anchor: "scheduled"`
179+
180+
#### complete_instances
181+
182+
- **Type:** list (array of date strings)
183+
- **Format:** `YYYY-MM-DD`
184+
- **Description:** Dates when recurring task instances were completed
185+
- **Example:**
186+
```yaml
187+
complete_instances:
188+
- "2025-01-08"
189+
- "2025-01-15"
190+
```
191+
192+
#### skipped_instances
193+
194+
- **Type:** list (array of date strings)
195+
- **Format:** `YYYY-MM-DD`
196+
- **Description:** Dates when recurring task instances were skipped
197+
- **Example:**
198+
```yaml
199+
skipped_instances:
200+
- "2025-01-22"
201+
```
202+
203+
---
204+
205+
### Complex Properties
206+
207+
These properties contain structured data with multiple fields.
208+
209+
#### Time Entries
210+
211+
- **Type:** list (array of objects)
212+
- **Description:** Time tracking entries for the task
213+
- **Structure:**
214+
```yaml
215+
timeEntries:
216+
- startTime: "2025-01-15T10:30:00Z" # Required: ISO 8601 timestamp
217+
endTime: "2025-01-15T11:15:00Z" # Optional: ISO 8601 timestamp
218+
description: "Initial work" # Optional: text
219+
```
220+
221+
#### Dependencies (blockedBy)
222+
223+
- **Type:** list (array of objects)
224+
- **Description:** Tasks that must be completed before this task can start
225+
- **Structure:**
226+
```yaml
227+
blockedBy:
228+
- uid: "path/to/blocking-task.md" # Required: path to blocking task
229+
reltype: "FINISHTOSTART" # Required: relationship type
230+
gap: "P1D" # Optional: ISO 8601 duration offset
231+
```
232+
- **Relationship types:** `FINISHTOSTART`, `STARTTOSTART`, `FINISHTOFINISH`, `STARTTOFINISH`
233+
- Note: As of version 4.1.0, only the FINISHTOSTART duration offset is supported
234+
235+
#### Reminders
236+
237+
- **Type:** list (array of objects)
238+
- **Description:** Reminder notifications for the task
239+
- **Structure for relative reminders:**
240+
```yaml
241+
reminders:
242+
- id: "rem_1" # Required: unique identifier
243+
type: "relative" # Required: "relative" or "absolute"
244+
relatedTo: "due" # Required for relative: "due" or "scheduled"
245+
offset: "-PT1H" # Required for relative: ISO 8601 duration
246+
description: "1 hour before due" # Optional: description
247+
```
248+
- **Structure for absolute reminders:**
249+
```yaml
250+
reminders:
251+
- id: "rem_2"
252+
type: "absolute"
253+
absoluteTime: "2025-01-15T09:00:00Z" # Required for absolute: ISO 8601 timestamp
254+
description: "Morning reminder"
255+
```
256+
257+
#### icsEventId
258+
259+
- **Type:** list (array of strings)
260+
- **Description:** ICS calendar event IDs linked to this task
261+
- **Example:**
262+
```yaml
263+
icsEventId:
264+
- "event-abc123"
265+
- "event-def456"
266+
```
267+
268+
---
269+
270+
## Complete Example
271+
272+
Here's a complete task with all property types:
273+
274+
```yaml
275+
---
276+
title: "Complete quarterly report"
277+
status: "in-progress"
278+
priority: "high"
279+
due: "2025-01-31"
280+
scheduled: "2025-01-25"
281+
tags:
282+
- work
283+
- reports
284+
contexts:
285+
- "@office"
286+
projects:
287+
- "[[Q1 Planning]]"
288+
timeEstimate: 240
289+
dateCreated: "2025-01-01T08:00:00Z"
290+
dateModified: "2025-01-20T14:30:00Z"
291+
timeEntries:
292+
- startTime: "2025-01-20T10:00:00Z"
293+
endTime: "2025-01-20T11:30:00Z"
294+
blockedBy:
295+
- uid: "tasks/gather-data.md"
296+
reltype: "FINISHTOSTART"
297+
reminders:
298+
- id: "rem_1"
299+
type: "relative"
300+
relatedTo: "due"
301+
offset: "-P1D"
302+
description: "Due tomorrow"
303+
---
304+
```
305+
306+
---
307+
308+
## Field Mapping
309+
310+
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.
311+
312+
For example, if you map `due` to `dueDate`, TaskNotes will expect:
313+
```yaml
314+
dueDate: "2025-01-15"
315+
```
316+
317+
See [Field Mapping](task-properties.md#field-mapping) for configuration details.
318+
319+
---
320+
321+
## Custom User Fields
322+
323+
You can define additional properties with these types:
324+
325+
- **text** - Single text value
326+
- **number** - Numeric value
327+
- **date** - Date string (YYYY-MM-DD)
328+
- **boolean** - true/false
329+
- **list** - Array of values
330+
331+
See [Custom User Fields](task-properties.md#custom-user-fields) for configuration details.

‎docs/settings/task-properties.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,12 @@
1-
21
# Task Properties Settings
32

43
These settings allow you to define custom statuses, priorities, and user fields for your tasks.
54

65
[← Back to Settings](../settings.md)
76

7+
!!! tip "Looking for property type documentation?"
8+
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.
9+
810
## Task Statuses
911

1012
Customize the status options available for your tasks. These statuses control the task lifecycle and determine when tasks are considered complete.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ nav:
6060
- General: settings/general.md
6161
- Features: settings/features.md
6262
- Task Properties: settings/task-properties.md
63+
- Property Types Reference: settings/property-types-reference.md
6364
- Defaults & Templates: settings/defaults.md
6465
- Task Defaults: settings/task-defaults.md
6566
- Appearance & UI: settings/appearance.md

0 commit comments

Comments
 (0)