Task File Format

Every Daylight task is a Markdown file with YAML frontmatter. The frontmatter contains structured metadata; the body contains your notes.

Why it matters

Portable. Your tasks work in any Markdown editor, version control system, or text processor.
Inspectable. When something seems wrong, you can open the file and see exactly what Daylight sees.
Scriptable. Build your own tools, reports, or integrations using standard YAML parsers.

Canonical example

---
title: Weekly team review
status: active
created: 2026-01-15
scheduled: 2026-01-28
due: 2026-01-31
priority: high
tags:
  - work
  - meetings
project: Q1 Planning
recurrence:
  rule: FREQ=WEEKLY;BYDAY=TU
  instances:
    - date: 2026-01-21
      status: completed
    - date: 2026-01-28
      status: active
time_entries:
  - date: 2026-01-21
    duration: 45
    notes: Reviewed roadmap priorities
---

## Agenda

- Sprint retrospective
- Roadmap check-in
- Blockers discussion

Field reference

Required fields

Field	Type	Description
`title`	string	Task name displayed in the UI
`status`	enum	`active`, `completed`, or `archived`
`created`	date	When the task was created (ISO 8601: `YYYY-MM-DD`)

Scheduling fields

Field	Type	Description
`scheduled`	date	When you plan to work on this task
`due`	date	Hard deadline (informational—Daylight doesn’t enforce it)
`priority`	enum	`low`, `medium`, or `high`

Organization fields

Field	Type	Description
`tags`	string[]	Categories for filtering (e.g., `work`, `home`, `errand`)
`project`	string	Parent project name

Recurrence fields

Field	Type	Description
`recurrence.rule`	string	iCalendar RRULE format (see Recurring Tasks)
`recurrence.instances`	array	Individual occurrences with their own status

Time tracking fields

Field	Type	Description
`time_entries`	array	Manual time log entries
`time_entries[].date`	date	When the work happened
`time_entries[].duration`	number	Minutes spent
`time_entries[].notes`	string	Optional description of the work

Status and grouping

The status field controls where a task appears:

Status	Behavior
`active`	Shows in Past/Now/Upcoming based on `scheduled` date
`completed`	Shows in Wrapped (if completed today) or hidden
`archived`	Hidden from all views

Grouping logic:

Past: scheduled < today AND status = active
Now: scheduled = today (or no scheduled date) AND status = active
Upcoming: scheduled > today AND status = active
Wrapped: status = completed AND completed today

Safe manual edits

You can safely edit these fields by hand:

title, tags, project, priority
scheduled, due
The Markdown body (notes)

[!warning] Be careful when manually editing:

recurrence.instances — Daylight tracks instance state here; incorrect edits can cause duplicate or missing instances

status — Changing from completed to active may have unexpected effects on recurring tasks

created — Used for sorting; changing it affects task order

Common patterns

Minimal task (just a title)

---
title: Call dentist
status: active
created: 2026-01-28
---

Scheduled task with tags

---
title: Submit expense report
status: active
created: 2026-01-28
scheduled: 2026-01-31
tags:
  - work
  - admin
---

Task with time tracking

---
title: Write documentation
status: active
created: 2026-01-28
project: Daylight
time_entries:
  - date: 2026-01-28
    duration: 90
    notes: Schema reference page
---

Troubleshooting

Task doesn’t appear in any view

Check that status is active (not completed or archived)
Verify the YAML frontmatter is valid (no syntax errors)
Ensure the file has the --- delimiters around the frontmatter

Task appears in wrong group

Check the scheduled date—it controls Past/Now/Upcoming placement
For recurring tasks, check recurrence.instances for the relevant date

YAML parse error

Ensure strings with special characters are quoted: title: "Meeting: Q1 Review"
Check that arrays use consistent indentation
Validate your YAML at yamllint.com

Getting Started — Create your first task
Recurring Tasks — RRULE format and instance tracking
Limitations — What Daylight doesn’t do