DOCSEARCHbyAlgolia
Submit Docs

TaskNotes Documentation

repository·main·Indexed 24 days ago

https://github.com/callumalpass/tasknotes

A task management plugin for Obsidian (version 4.11.1) that treats tasks as individual Markdown notes with YAML frontmatter. It integrates with Obsidian Bases to provide Kanban, Calendar, and List views, and features pomodoro and time-tracking integration. The plugin supports RRULE recurring tasks, Google and Microsoft Calendar integrations, and customizable webhook notifications via JSON transform files.

Tokens
124K
Snippets
192
Records
589
Agent score
83%

What's inside TaskNotes

  1. Navigate the TaskNotes directory structure

    main

    The project is organized by architectural layers to maintain separation of concerns:

    • /src/main.ts: Plugin entry point; initializes services, views, and commands.
    • /src/types.ts: Crucial. Contains all shared type definitions. Add new types here.
    • /src/views/: ItemView implementations (e.g., TaskListView, AgendaView, KanbanView).
    • /src/ui/: Reusable "dumb" UI components (e.g., TaskCard, NoteCard, FilterBar) that render data without fetching it.
    • /src/modals/: User interaction modals (e.g., TaskCreationModal, TaskEditModal).
    • /src/services/: Core business logic (e.g., TaskService for CRUD, FilterService for querying, PomodoroService for timers).
    • /src/editor/: CodeMirror extensions (e.g., TaskLinkWidget, InstantConvertButtons).
    • /src/utils/: Helper classes (e.g., MinimalNativeCache, dateUtils, DOMReconciler).
    • /src/settings/: Settings tab UI and default configurations.
    • /styles/: CSS files compiled into styles.css.

  2. Understand the TaskNotes data specification

    main

    The TaskNotes specification defines the standard for reading, writing, and reasoning about task data stored in markdown files with YAML frontmatter. It ensures interoperability between different implementations such as the Obsidian plugin, terminal UIs, and CLI tools.

    Key areas covered by the specification include:

    • Data Model & Mapping: How task data is structured and mapped to fields.
    • Temporal Semantics: Rules for dates, datetimes, and timezones.
    • Recurrence: RRULE semantics, per-instance state, and materialized occurrence semantics.
    • Operations: Standard behaviors for creating, updating, completing, skipping, deleting, archiving, or materializing tasks.
    • Configuration: The tasknotes.yaml schema and the provider model.
    • Dependencies & Reminders: Semantics for task relationships and reminders.
    • Links: Syntax and resolution for task links.

  3. Understand Companion Plugins in TaskNotes

    main

    Companion plugins are optional Obsidian plugins that extend TaskNotes functionality without bloating the core plugin. They run within the same Obsidian app and use the TaskNotes JavaScript Runtime API to perform live task reads and writes. This ensures that task data remains in standard Markdown files while staying consistent with TaskNotes' internal logic (cache, events, time tracking, etc.).

    Key Characteristics:

    • Decoupled Workflows: They allow for specialized surfaces (like Canvas boards or automation workflows) while TaskNotes remains focused on storage and core views.
    • Non-Destructive: If a companion plugin is disabled, TaskNotes task notes remain standard Markdown files and core views continue to function normally.

  4. CSS file structure and loading order

    main

    The CSS build system concatenates files in a specific dependency order. When adding new styles, ensure you understand where they fit in this sequence to manage specificity correctly:

    1. variables.css (CSS custom properties - loaded first)
    2. utilities.css (utility classes)
    3. base.css (foundational styles)
    4. task-card-bem.css (BEM TaskCard component)
    5. note-card-bem.css (BEM NoteCard component)
    6. filter-bar-bem.css (BEM FilterBar component)
    7. modal-bem.css (BEM Modal components)
    8. View-specific BEM files (e.g., task-list-view.css, calendar-view.css, kanban-view.css, etc.)
    9. components.css (general components)
    10. Legacy files (pomodoro.css, settings.css)

  5. How TaskNotes views work with Obsidian Bases

    main
    All task-focused views in TaskNotes are implemented as .base files located in the TaskNotes/Views/ directory. To use these views, you must have Obsidian's Bases core plugin enabled. These views act as different entry points into your underlying task notes, allowing you to visualize the same data through different organizational lenses (lists, kanbans, calendars, etc.).

  6. Handle filtering and grouping logic

    main

    Filtering, grouping, and sorting are handled by the FilterService ecosystem. These concerns are separated into specialized modules to decouple query planning from predicate evaluation:

    • Query Planning: src/services/filter-service/FilterQueryPlanner.ts handles index-backed candidate selection.
    • Field Normalization: src/services/filter-service/userFieldValues.ts manages custom user-field token normalization and sort comparison.
    • Grouping: src/services/filter-service/filterTaskGrouping.ts manages project/tag fan-out and date bucket labels.
    • Sorting: src/services/filter-service/filterTaskSorting.ts manages date comparison and natural fallback ordering.
    • Option Assembly: src/services/filter-service/filterOptions.ts handles dynamic user-property definitions and task-folder extraction.
    • State Management: src/services/filter-service/filterQueryState.ts manages default query construction and quick-toggle mutations.

  7. Manage data access via TaskManager and Adapters

    main

    Data access is handled through specialized utilities and adapters to ensure a stable contract between the raw Obsidian metadata and the TaskNotes domain model.

    Key components include:

    • src/utils/TaskManager.ts: Manages metadata-cache-backed task reads.
    • Task Identification (src/utils/taskIdentification.ts): Identifies task-frontmatter using Obsidian metadata-cache tag prefixes, hierarchical tags, and list-valued properties.
    • TaskInfo Assembly (src/utils/taskInfoAssembly.ts): Assembles the final TaskInfo object from FieldMapper output, including path identity, display defaults, and computed tracked time.
    • Bases Adapters: Handles conversion between Bases data and TaskNotes representations, including property coercion at integration boundaries.

  8. Use FieldMapper to translate task properties

    main

    The FieldMapper is a translation service that decouples internal TaskInfo property names from user-configurable YAML frontmatter keys.

    How it Works

    • Reading (File $\rightarrow$ TaskInfo): Use fieldMapper.mapFromFrontmatter(frontmatter). It uses settings.fieldMapping to convert user keys (e.g., deadline) into standardized internal keys (e.g., due).
    • Writing (TaskInfo $\rightarrow$ File): Use fieldMapper.mapToFrontmatter(taskInfo) when saving. This converts internal keys back into the user's preferred YAML keys.

    Developer Best Practices

    • Central Point of Interaction: Any service reading or writing frontmatter (MinimalNativeCache, TaskService) must use the FieldMapper.
    • Stable Internal API: Always interact with standardized TaskInfo properties (e.g., task.due, task.priority) within the plugin code.
    • Avoid Hard-coding: Never access frontmatter properties directly (e.g., frontmatter.due). Always use the mapper.
    • Extensibility: To add a new persistent property, you must update:
      1. FieldMapping type in types.ts
      2. DEFAULT_FIELD_MAPPING in settings.ts
      3. Mapping logic in FieldMapper.ts

  9. Use Accessibility features

    main

    TaskNotes includes built-in support for accessibility:

    Screen Reader Utilities

    • .tn-sr-only: Hide visually but keep accessible to screen readers
    • .tn-not-sr-only: Make visible again

    Reduced Motion Support All transition and animation utilities automatically respect prefers-reduced-motion: reduce.

    High Contrast Support Border and focus utilities automatically increase in high contrast mode.

  10. How recurring tasks work in TaskNotes

    main

    Recurring tasks in TaskNotes are built on a dual-layer model that separates long-term planning from immediate execution:

    1. Recurring Pattern: The long-term schedule defined by an RFC 5545 RRule string. This determines when pattern instances should appear.
    2. Next Occurrence (scheduled field): The specific date/time you actually plan to work on the next instance. This is the primary field for day-to-day scheduling and can be moved independently of the pattern.
    3. Materialized Occurrence Notes: Optional child task notes created for specific dates when an occurrence requires its own unique content (e.g., a separate checklist, time tracking, or body text).

    This separation allows you to reschedule a single instance (via the scheduled field) without breaking or altering the underlying recurrence rule.

    # Example of the dual-layer state
recurrence: "DTSTART:20250804T090000Z;FREQ=DAILY"
scheduled: "2025-08-04T09:00"
complete_instances: []

  11. Manage tasks with structured properties

    main

    TaskNotes uses Obsidian frontmatter to store task properties, ensuring data remains portable and readable. Each task can include:

    • status
    • priority
    • due and scheduled dates
    • tags
    • contexts
    • estimates (optional)

    Because these values are stored in frontmatter, they can be used for advanced filtering and grouping within Obsidian Bases. You can also set up relative reminders (e.g., "3 days before due") or absolute reminders.

  12. Understand mobile differences in TaskNotes

    main

    TaskNotes behaves differently on mobile compared to desktop in several key areas:

    • HTTP API and MCP server: These are desktop-only features. The HTTP API settings section is hidden on mobile.
    • Calendar integrations: These are available, but you can choose to disable them on mobile if they impact startup time or provider behavior.
    • Settings layout: Uses the same six tabs as desktop, but desktop-only controls are omitted.
    • Keyboard commands: Commands are available via the command palette, but desktop-specific key bindings may not exist on mobile.
    • Wide views: Components like Calendar, Kanban, and large tables may require horizontal scrolling or a narrower Base configuration due to screen size.