obsidian-plugin/callumalpass_tasknotes
1
0
Fork 0
mirror of https://github.com/callumalpass/tasknotes.git synced 2026-07-22 12:50:26 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Docs: Comprehensive v4.0.0 documentation update

Browse source 
Updates documentation to reflect version 4 changes:
- Bases core plugin integration and requirement
- OAuth calendar integration (Google, Microsoft)
- New Bases-based filtering with YAML expressions
- Removed v3 FilterBar UI references
- Added modal fields settings documentation
- Added 4.0.0 release notes
- Updated all feature guides with v4 functionality
This commit is contained in:
callumalpass 2025-11-18 12:57:46 +11:00
parent 48a5f871c8
commit a3621ca01f
22 changed files with 1351 additions and 628 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
docs/core-concepts.md
View file

@ -12,12 +12,12 @@ This approach does create many small files, which may not suit every organizatio
## YAML Frontmatter for Structured Data
Task metadata like due dates, priorities, and status live in YAML frontmatter. This widely adopted standard has broad tool support, letting you integrate task data with external systems and extend the data model with custom fields.
Task metadata like due dates, priorities, and status live in YAML frontmatter. This standard has tool support for integrating task data with external systems and extending the data model with custom fields.
TaskNotes uses Obsidian's native metadata cache for performance, even with large task counts. The YAML format works with other Obsidian plugins like Bases, and plain text files integrate naturally with version control systems like Git.
TaskNotes queries Obsidian's metadata cache directly. Version 4 requires the Bases core plugin to be enabled for main views. Plain text files work with version control systems like Git.
## Methodology-Agnostic Design
TaskNotes doesn't enforce any specific productivity methodology. The tools adapt to various approaches:
TaskNotes does not enforce a specific productivity methodology. The tools support various approaches:
Getting Things Done benefits from contexts, status workflows, and calendar integration. Time-based planning uses calendar integration and time tracking features. Project-centric workflows leverage the projects feature with tags, contexts, and linking. Kanban and Agile methodologies work with the Kanban view and customizable status systems.
Getting Things Done uses contexts, status workflows, and calendar integration. Time-based planning uses calendar integration and time tracking. Project-centric workflows use the projects feature with tags, contexts, and linking. Kanban and Agile methodologies use the Kanban view and customizable status systems.

38
docs/features.md
View file

@ -12,64 +12,64 @@ See [Task Management](features/task-management.md) for details.
## Filtering and Views
The FilterBar appears across multiple views, offering instant text search plus a hierarchical query builder for complex conditions using AND/OR logic. Saved views let you store frequently-used filter combinations, while sorting and grouping options organize tasks by tags, custom fields, or other properties.
TaskNotes v4 uses the Bases core plugin for filtering, sorting, and grouping tasks. Bases is an official Obsidian plugin built directly into the application. Views are defined through YAML-based `.base` files in your vault, which specify query conditions using AND/OR logic, sort orders, and grouping criteria by task properties such as tags, status, or custom fields.
Advanced hierarchical subgrouping allows two-level organization, where tasks are first grouped by one criterion (e.g., status) and then subdivided by another (e.g., priority), providing enhanced visual organization for complex task lists.
Saved views are stored as `.base` files rather than in plugin settings. This allows multiple task perspectives that can be switched between. Hierarchical subgrouping supports two-level organization, where tasks are first grouped by one criterion (e.g., status) and then subdivided by another (e.g., priority).
The Bases core plugin must be enabled for TaskNotes main views to function.
See [Filtering and Views](features/filtering-and-views.md) for details.
## Inline Task Integration
Task management happens directly within your notes through interactive widgets that overlay task links, showing information and allowing quick edits without leaving the editor. Convert existing checkbox tasks instantly, or create new tasks with the `create inline task` command.
Task management happens directly within notes through interactive widgets that overlay task links, showing information and allowing quick edits without leaving the editor. Convert existing checkbox tasks or create new tasks with the `create inline task` command.
Project notes can display collapsible widgets showing all linked subtasks. Natural language processing turns conversational text into structured tasks, automatically parsing dates, priorities, and other details across 12 languages.
Project notes display a Relationships widget showing all linked subtasks and dependencies in a collapsible interface. Natural language processing converts text into structured tasks, parsing dates, priorities, and other details across 12 languages. The NLP system includes customizable trigger phrases and a rich markdown editor for task creation.
See [Inline Task Integration](features/inline-tasks.md) for details.
## Time Management
Built-in time tracking records work sessions for individual tasks, while the integrated Pomodoro timer helps maintain focus during work periods. Analytics and statistics show patterns in your productivity over time. A dedicated Time Statistics view allows for aggregating task time estimates over various periods.
Time tracking records work sessions for individual tasks. The Pomodoro timer provides timed work intervals. Analytics and statistics display productivity patterns over time. A Time Statistics view aggregates task time estimates over various periods.
See [Time Management](features/time-management.md) for details.
## Calendar Integration
External ICS feeds from Google Calendar, Outlook, and similar services sync into TaskNotes, while ICS export lets other systems access your task data with automatic updates.
TaskNotes supports OAuth-based calendar integration and ICS subscriptions. OAuth integration with Google Calendar and Microsoft Outlook provides bidirectional synchronization. Drag events to reschedule them, with changes syncing back to the calendar provider. OAuth calendars sync every 15 minutes and on local changes. ICS subscriptions from external calendar services provide read-only access to calendar events.
The advanced calendar view supports multiple formats (month, week, day, year, plus configurable custom day ranges) with drag-and-drop task scheduling. Time-blocking creates focused work periods that link directly to specific tasks.
ICS export allows other systems to access task data with automatic updates. The calendar view supports multiple formats (month, week, day, year, plus configurable custom day ranges) with drag-and-drop task scheduling. Time-blocking creates work periods that link to specific tasks.
See [Calendar Integration](features/calendar-integration.md) for details.
## User Fields
Custom fields extend task structure with any data you need. These fields work in filtering, sorting, and templates, letting you adapt TaskNotes to specialized workflows without losing functionality.
Custom fields extend task structure with additional data. These fields work in filtering, sorting, and templates.
See [User Fields](features/user-fields.md) for details.
## Integrations
Deep integration with the Bases plugin lets TaskNotes tasks function as data sources within Bases databases, combining structured task management with Bases' analysis capabilities.
TaskNotes v4 requires the Bases core plugin to be enabled for main task views to function. Bases is an official Obsidian plugin built directly into the application, not a community plugin. This integration allows TaskNotes tasks to function as data sources within Bases databases.
See [Integrations](features/integrations.md) for details.
See [Integrations](settings/integrations.md) for details.
## REST API
External applications can interact with TaskNotes through its REST API, enabling automation, reporting, and integration with other tools in your workflow.
External applications can interact with TaskNotes through its REST API for automation, reporting, and integration with other tools.
See [HTTP API](HTTP_API.md) for details.
See [HTTP API](../HTTP_API.md) for details.
## View Types
Different views suit different work styles:
[Task List View](../views/task-list.md) handles filtering, sorting, and grouping. [Kanban View](../views/kanban-view.md) organizes tasks as cards across status columns.
[Task List View](views/task-list.md) handles filtering, sorting, and grouping. [Agenda View](views/agenda-view.md) focuses on daily and weekly planning. [Kanban View](views/kanban-view.md) organizes tasks as cards across status columns.
[Calendar Views](views/calendar-views.md) provide visual scheduling with time-blocking. [Notes View](views/notes-view.md) browses content by date. [Pomodoro View](views/pomodoro-view.md) integrates focus timing with task tracking.
[Calendar Views](../views/calendar-views.md) provide visual scheduling with time-blocking. The [Agenda View](../views/agenda-view.md) command opens the calendar's list mode for daily and weekly planning.
## Settings
Configuration adapts TaskNotes to your workflow:
[General](../settings/general.md) controls task identification, file storage, and click behavior. [Features](../settings/features.md) manages inline tasks, natural language processing, and the Pomodoro timer. [Defaults & Templates](../settings/defaults.md) sets default properties and templates.
[Task Defaults](settings/task-defaults.md) sets default properties and templates. [Inline Task Settings](settings/inline-task-settings.md) controls editor integration. [Calendar Settings](settings/calendar-settings.md) handles appearance and behavior.
[Appearance & UI](../settings/appearance.md) controls visual elements. [Task Properties](../settings/task-properties.md) defines custom statuses, priorities, and user fields. [Modal Fields](../settings/modal-fields.md) configures field visibility in task modals.
[Advanced Settings](settings/advanced-settings.md) covers field mapping and customization. [Misc Settings](settings/misc-settings.md) contains additional plugin features.
[Calendar Settings](../settings/calendar-settings.md) handles calendar appearance and behavior. [Integrations](../settings/integrations.md) manages OAuth calendars, ICS subscriptions, and the HTTP API. [Advanced Settings](../settings/advanced-settings.md) covers field mapping. [Misc Settings](../settings/misc-settings.md) contains additional options.

102
docs/features/calendar-integration.md
View file

@ -1,18 +1,98 @@
# Calendar Integration
TaskNotes provides calendar integration features, which allow you to visualize your tasks and schedule your work. This is done through two calendar views and the ability to subscribe to external calendar feeds.
[← Back to Features](../features.md)
TaskNotes provides calendar integration through OAuth-connected calendar services, two Bases-powered calendar views, and read-only ICS calendar subscriptions.
## OAuth Calendar Integration
TaskNotes supports bidirectional synchronization with Google Calendar and Microsoft Outlook using OAuth authentication. This integration allows you to view external calendar events alongside your tasks and sync changes back to the calendar provider.
### Supported Providers
- **Google Calendar** - OAuth 2.0 authentication with access to all calendars in your Google account
- **Microsoft Outlook** - OAuth 2.0 authentication with access to calendars in your Microsoft 365 or Outlook.com account
### Setup Requirements
OAuth calendar integration requires creating an OAuth application with your calendar provider. This process takes approximately 15 minutes per provider. You will need to:
1. Create an OAuth application in Google Cloud Console or Microsoft Azure Portal
2. Configure redirect URIs and scopes
3. Obtain client ID and client secret
4. Enter credentials in TaskNotes settings (**Settings → TaskNotes → Integrations → OAuth Calendar Integration**)
### Synchronization Behavior
- Events are fetched automatically every 15 minutes
- Events are also fetched when local changes occur (task creation, updates, rescheduling)
- Dragging calendar events to new dates/times updates the event in the calendar provider
- Per-calendar visibility toggles allow selective display of calendars
- Access tokens are automatically refreshed when expired
### Token Management
TaskNotes stores OAuth access tokens and refresh tokens locally. Tokens are refreshed automatically before expiration. You can revoke access at any time through the integrations settings.
## Calendar Views
TaskNotes has two calendar views for visualizing and managing tasks: the **Mini Calendar** and the **Advanced Calendar**.
TaskNotes provides two calendar views implemented as Bases views. Both views require the **Bases core plugin** to be enabled in Obsidian.
The **Mini Calendar** is a compact, month-based view that provides an overview of which days have tasks. It is designed for navigation and for understanding task distribution.
### Calendar View
The **Advanced Calendar** is a calendar with multiple view modes (month, week, day, year, and custom days), drag-and-drop scheduling, and time-blocking capabilities. You can create new tasks by clicking on dates or time slots, and you can reschedule tasks by dragging them to a new date or time. The custom days view allows you to display 2-10 days at once, providing flexible screen space utilization.
The Calendar View offers multiple display modes—month, week, day, year, and custom days (2-10 days)—and supports:
- Drag-and-drop task scheduling and rescheduling
- Click dates or time slots to create new tasks
- Display of scheduled tasks, due tasks, recurring tasks, time entries, and time blocks
- OAuth calendar events from Google and Microsoft
- Read-only ICS subscription events
- Custom day view for flexible screen space utilization
Calendar views are configured through `.base` files in your vault, which define the data source, filters, and view-specific options.
### Mini Calendar
The Mini Calendar is a month-based Bases view that displays notes and tasks organized by date. Features include:
- Heatmap styling to visualize note/task density per day
- Fuzzy selector modal when clicking on days (allows quick selection from multiple notes)
- Keyboard navigation for date selection
- Configurable date property (supports `file.ctime`, `file.mtime`, or any custom date property)
- Configurable title property for displaying note names
The Mini Calendar operates as a Bases view and is configured through a `.base` file that specifies the date property and display options.
## Time Entry Editor
TaskNotes includes a time entry editor for tracking time spent on tasks. Time entries are created and managed through the Calendar View.
### Creating Time Entries
To create a time entry on the Calendar View:
1. Click and drag on a time slot in the calendar to select a time range
2. When the selection menu appears, choose **Create time entry** (timeblock appears only if the feature is enabled)
3. The time entry editor opens with start/end times pre-filled for the selected range
Time entries are associated with tasks and stored in the task's frontmatter. Multiple time entries can exist for a single task.
### Managing Time Entries
The time entry editor modal provides functions to:
- View all time entries for a task
- Edit the start time, end time, and duration of time entries
- Delete time entries
- See the total time tracked across all entries for a task
Access the time entry editor by clicking on an existing time entry in the calendar or through the task's context menu.
## ICS Calendar Subscriptions
TaskNotes can subscribe to external calendar feeds using the iCalendar (ICS) format. This allows you to display events from services like Google Calendar and Outlook alongside your tasks. Add and manage subscriptions from **Settings → TaskNotes → Integrations → Calendar subscriptions**.
TaskNotes can subscribe to external calendar feeds using the iCalendar (ICS) format. This provides read-only access to events from calendar services. ICS subscriptions differ from OAuth calendar integration in that they are read-only—dragging ICS events to new dates does not update the source calendar.
Add and manage ICS subscriptions from **Settings → TaskNotes → Integrations → Calendar subscriptions**.
### Creating Content from Calendar Events
@ -49,6 +129,14 @@ The event information modal displays details about calendar events and provides
Related notes and tasks are automatically identified by their ICS event ID field. Tasks are distinguished from notes based on the presence of the configured task tag in their frontmatter.
## Time-blocking
## Time Blocking
The Advanced Calendar supports time-blocking, which is a time management method that involves scheduling out parts of your day. Enable the feature under **Settings → TaskNotes → Appearance & UI → Timeblocking**. Once enabled, create time blocks by holding the Shift key while selecting a time range in the calendar. Time blocks are stored in the frontmatter of your daily notes and can be linked to specific tasks.
The Calendar View supports time blocking for scheduling dedicated work periods. To create a time block:
1. Click and drag on a time slot in the calendar to select a time range
2. A context menu will appear with available options
3. Select "Create timeblock" from the menu (this option only appears if timeblocking is enabled in settings)
Time blocks are stored in the frontmatter of daily notes and can be linked to specific tasks. This differs from time entries, which track actual time spent and are stored in task frontmatter rather than daily notes.
Enable time blocking under **Settings → TaskNotes → Features → Timeblocking**.

837
docs/features/filtering-and-views.md
View file

@ -1,406 +1,555 @@
# Filtering and Views
TaskNotes provides filtering capabilities through the FilterBar, available in the Task List, Agenda, Kanban, and Advanced Calendar views. The FilterBar uses a hierarchical query builder to create complex filter conditions and supports saved views for quick access to common filter configurations.
[← Back to Features](../features.md)
## FilterBar Overview
TaskNotes v4 uses the Bases core plugin for filtering, sorting, and grouping tasks. Filtering is configured through YAML frontmatter in `.base` files using Bases expression syntax. This approach replaces the v3 FilterBar UI component, which has been removed.
The FilterBar is located at the top of supported views and provides three main sections:
## Bases Core Plugin
1. **Quick Search**: Immediate text-based filtering
2. **Query Builder**: Hierarchical filter construction
3. **Display Options**: Sorting, grouping, and view-specific settings
4. **Saved Views**: Named filter configurations
Bases is an official Obsidian core plugin built directly into the application, not a community plugin. It provides data querying and visualization capabilities that TaskNotes uses for its main views.
## Quick Search
**To enable Bases:**
1. Open Settings → Core Plugins
2. Enable "Bases"
3. Restart Obsidian
The search input provides instant filtering by task title:
- Type to search task titles in real-time
- Uses case-insensitive substring matching
- Updates with 800ms debouncing for performance
- Search terms appear as filter conditions in the query builder
All TaskNotes views (Task List, Kanban, Calendar) are implemented as Bases views and stored as `.base` files in the `TaskNotes/Views/` directory.
### Search and Existing Filters
## Filter Configuration
The search functionality intelligently preserves your existing filters:
Filters are defined in the YAML frontmatter of `.base` files using Bases expression syntax. Each view file can specify its own filtering criteria.
**When you apply search to existing filters:**
1. All existing filters are automatically grouped together
2. The search condition is added as a separate filter
3. Search and existing filters are connected with "AND" logic
### Basic Filter Structure
**When you clear search:**
- The search condition is removed
- Original filter structure is restored exactly as it was
Filters use object notation with `and` and `or` operators to combine conditions:
**Example:**
If you have filters: `Priority = High OR Status = In Progress`
With search "urgent":
```
Search: title contains "urgent"
AND
Group: (Priority = High OR Status = In Progress)
```yaml
filters:
and:
- note.status == "todo"
- note.priority == "high"
```
This ensures search never interferes with your carefully crafted filter logic while providing powerful search capabilities on top of existing filters.
### Multiple Conditions with OR Logic
## Query Builder
```yaml
filters:
or:
- note.status == "in-progress"
- note.status == "todo"
```
The query builder allows construction of complex filter hierarchies using groups and conditions.
### Nested Logic
### Filter Groups
Combine `and` and `or` operators for complex queries:
Filter groups are logical containers that can hold conditions or other groups:
- **Conjunction**: Choose AND or OR logic for combining contents
- **Nesting**: Groups can contain other groups for complex logic
- **Visual Hierarchy**: Indentation shows the structure
### Filter Conditions
Each condition consists of three parts:
1. **Property**: The task attribute to filter on
2. **Operator**: How to evaluate the property
3. **Value**: What to compare against (when applicable)
### Adding Filters
- **Add Filter**: Creates a new condition with default property and operator
- **Add Filter Group**: Creates a nested group with AND conjunction
- **Delete**: Remove individual conditions or entire groups
### Incomplete Conditions
The filter builder allows incomplete conditions during construction:
- Conditions missing values are ignored during evaluation
- This allows building complex filters step by step
- Only complete conditions affect the displayed tasks
```yaml
filters:
and:
- note.priority == "high"
- or:
- note.status == "todo"
- note.status == "in-progress"
```
## Available Properties
### Text Properties
TaskNotes tasks expose properties that can be used in Bases filter expressions. Property names depend on your field mapping configuration in TaskNotes settings.
- `title` - Task title/name
### Default Property Names
### Selection Properties
These are the default property names used in Bases expressions (assuming standard field mapping):
- `path` - Task file path/folder location
**Task Properties:**
- `note.status` - Task status
- `note.priority` - Priority level
- `note.due` - Due date
- `note.scheduled` - Scheduled date
- `note.contexts` - Task contexts (array)
- `note.projects` - Task projects (array)
- `note.time-estimate` - Time estimate in minutes
- `note.recurrence` - Recurrence pattern
- `note.completed-date` - Date when task was completed
- `note.complete-instances` - Array of completed dates for recurring tasks
- `note.blocked-by` - Tasks blocking this task (array)
- `status` - Task status (uses your configured statuses)
- `priority` - Priority level (uses your configured priorities)
- `tags` - Task tags
- `contexts` - Task contexts
- `projects` - Task projects (supports `[[wiki-link]]` format)
### Date Properties
- `due` - Due date
- `scheduled` - Scheduled date
- `completedDate` - Date when task was completed
**File Properties:**
- `file.name` - Task title (filename without extension)
- `file.basename` - Task title (filename without extension)
- `file.path` - Full file path
- `file.parent` - Parent folder path
- `file.tags` - File tags (array)
- `file.ctime` - File creation date
- `file.mtime` - File modification date
**Natural Language Date Support**: Date properties support both ISO date formats (`2024-12-25`, `2024-12-25T14:30:00`) and natural language patterns for dynamic filtering:
**Custom User Fields:**
Any custom fields configured in Settings → TaskNotes → Task Properties → Custom User Fields can be accessed as `note.<field-key>`.
- **Basic dates**: `today`, `tomorrow`, `yesterday`
- **Week patterns**: `next week`, `last week`
- **Relative patterns**: `in 3 days`, `2 days ago`, `in 1 week`, `2 weeks ago`
### Property Mapping
Natural language dates are resolved dynamically when filters are evaluated, making saved views with dates like "today" stay current over time.
If you have customized field mapping in TaskNotes settings, use the configured property names instead of the defaults. For example, if you mapped the status field to `task-status`, use `note.task-status` in filters.
## Filter Operators and Expressions
Bases uses expression syntax for filtering. Common patterns include:
### Equality
```yaml
# Exact match
- note.status == "todo"
# Not equal
- note.status != "done"
```
### Comparison
```yaml
# Greater than
- note.time-estimate > 60
# Less than
- note.time-estimate < 30
# Greater than or equal
- note.priority >= "medium"
# Less than or equal
- note.due <= "2024-12-31"
```
### Date Comparisons
```yaml
# Before a date
- note.due < "2024-12-31"
# After a date
- note.scheduled > "2024-01-01"
# Date range
- and:
- note.due >= "2024-01-01"
- note.due <= "2024-01-31"
```
### Contains (for arrays and strings)
```yaml
# Array contains value
- note.contexts.contains("work")
- file.tags.contains("important")
# String contains substring (case-insensitive)
- file.name.lower().contains("meeting")
# Projects (handles wiki links)
- note.projects.contains("[[Project Name]]")
```
### Existence Checks
```yaml
# Property exists and is not empty
- note.due && note.due != "" && note.due != null
# Property is empty or null
- !note.due || note.due == "" || note.due == null
# Array has items
- note.contexts && note.contexts.length > 0
```
### Boolean Properties
- `archived` - Whether task is archived
- `status.isCompleted` - Whether the task's status indicates completion
```yaml
# Check completed status (based on configured status values)
# This checks both status field and recurring task instances
- (note.status == "done") || (note.complete-instances && note.complete-instances.map(date(value).format("YYYY-MM-DD")).contains(today().format("YYYY-MM-DD")))
### Numeric Properties
# Negation
- note.status != "done"
```
- `timeEstimate` - Time estimate in minutes
### Natural Language Dates
### User-Defined Properties
Bases supports dynamic date expressions:
TaskNotes supports custom user fields that you define in **Settings → TaskNotes → Task Properties → Custom User Fields**. These fields appear as filter options based on their configured type:
```yaml
# Relative to today
- note.due == today()
- note.scheduled < tomorrow()
- **Text fields**: Filter by string content with text operators
- **Number fields**: Filter by numeric values with comparison operators
- **Date fields**: Filter by dates with date operators and natural language support
- **Boolean fields**: Filter by true/false values with checkbox operators
- **List fields**: Filter comma-separated values with intelligent splitting that preserves wikilinks and quoted text
### Special Properties
- `recurrence` - Recurrence pattern (checks if pattern exists)
## Filter Operators
### Text Operators
- `contains` - Text contains substring (case-insensitive)
- `does-not-contain` - Text does not contain substring
### Comparison Operators
- `is` - Exact equality
- `is-not` - Exact inequality
- `is-greater-than` - Numeric greater than
- `is-less-than` - Numeric less than
- `is-greater-than-or-equal` - Numeric greater than or equal (≥)
- `is-less-than-or-equal` - Numeric less than or equal (≤)
### Date Operators
- `is-before` - Date is before specified date
- `is-after` - Date is after specified date
- `is-on-or-before` - Date is on or before specified date
- `is-on-or-after` - Date is on or after specified date
### Existence Operators
- `is-empty` - Property is null, undefined, or empty
- `is-not-empty` - Property has a value
- `is-checked` - Boolean property is true
- `is-not-checked` - Boolean property is false
## Value Inputs
The value input changes based on the selected property and operator:
**Text Input**: For text properties and custom values
**Dropdown Selection**: For status, priority, tags, contexts, projects, and path (folder locations)
**Date Input**: For date properties - supports both ISO dates and natural language
**Number Input**: For numeric properties
**No Input**: For existence operators that don't require values
### Date Input
Date inputs provide real-time validation with visual feedback:
- **Valid input**: Green border indicates recognized date format
- **Invalid input**: Red border indicates unrecognized format
- **Help tooltip**: Click the `?` button to see available natural language patterns
- **Smart filtering**: Only applies filters when input is valid or empty
Examples of valid date inputs:
- ISO formats: `2024-12-25`, `2024-12-25T14:30:00Z`
- Natural language: `today`, `next week`, `in 3 days`, `2 weeks ago`
## Saved Views
Saved views store complete filter configurations and view-specific options for quick access. This includes not only filters, sorting, and grouping, but also view-specific display preferences.
### What Gets Saved
When you save a view, the following state is preserved:
- **Filter Configuration**: All filter conditions, groups, and logic
- **Sorting**: Selected sort criteria and direction
- **Grouping**: Chosen grouping method
- **View Options**: View-specific display preferences such as:
- **Agenda View**: "Show overdue on today" and "Show notes" toggles
- **Advanced Calendar**: Display options for scheduled tasks, due dates, timeblocks, recurring tasks, ICS events, and time entries
### Saving Views
1. Configure your desired filters, sorting, and grouping
2. Set any view-specific options (toggles, display preferences)
3. Click the "Save View" button
4. Enter a name for the view
5. The complete view state is saved and appears in the dropdown
### Loading Views
1. Click the saved views dropdown
2. Select a view name
3. The complete configuration is applied, including:
- Filter conditions and structure
- Sorting and grouping settings
- View-specific display options
### Managing Views
- **Load**: Apply a saved view configuration
- **Delete**: Remove a saved view (requires confirmation)
- **Reorder**: Drag and drop saved views to reorder them
- Saved views are stored in the plugin's data file, so they persist across vault restarts and device restarts
### Views Button Alignment
You can choose where the `Views` button (which opens saved views) appears in the FilterBar:
- Right (default): Filter → Search → Views
- Left: Views → Filter → Search
This is configured via **Settings → TaskNotes → Misc → Views button alignment**.
Right position (default):
![Saved Views button on the right](assets/saved_views_button_collapse_all.gif)
Left position:
![Saved Views button on the left](assets/saved_views_button_no_expand_collapse_all.gif)
## Sorting
Available sort options:
- `due` - Due date (earliest first)
- `scheduled` - Scheduled date (earliest first)
- `priority` - Priority level (by configured weight)
- `title` - Alphabetical (A-Z)
- `createdDate` - Date created (newest first)
- User-defined fields (from **Settings → TaskNotes → Task Properties → Custom User Fields**). Sorting is type‑aware (number/date/boolean/list). For list fields, empty or missing values sort last.
When Group by matches the selected Sort user field, group header order follows the sort direction (asc/desc).
![Sort by custom user fields](../assets/sort-by-custom-user-fields.gif)
**Fallback Sorting**: When the primary sort criteria are equal, tasks are sorted by: scheduled → due → priority → title
## Grouping
Available grouping options:
- `none` - No grouping (flat list)
- `status` - Group by task status
- `priority` - Group by priority level
- `context` - Group by first context (tasks without contexts appear in "No Context")
- `project` - Group by project (tasks can appear in multiple groups)
- `due` - Group by due date ranges (Today, Tomorrow, This Week, etc.)
- `scheduled` - Group by scheduled date ranges
**Project Grouping**: Tasks with multiple projects appear in each project group.
### Hierarchical Subgrouping
TaskNotes supports two-level hierarchical grouping, where tasks are first grouped by a primary criterion, then further organized into subgroups within each primary group.
![Subgrouping demonstration](../assets/subgroups.gif)
**How to Enable Subgrouping:**
1. Set a primary grouping option (e.g., "Status")
2. Access the sort/group context menu (three-dot button in FilterBar)
3. Select a subgroup option from the "SUBGROUP" section
4. Tasks will be organized with primary groups containing subgroups
**Available Subgroup Options:**
- Any grouping option except the current primary group
- User-defined custom fields (when configured)
- "None" to disable subgrouping
**Subgroup Behavior:**
- Subgroups are sorted consistently with the current sort direction
- "No [field]" subgroups (e.g., "No Priority") are positioned based on sort order
- Subgroup state (expanded/collapsed) is preserved per view
- Both TaskListView and AgendaView support hierarchical subgrouping
## Performance Considerations
The FilterBar includes several performance optimizations:
- **Debounced Input**: Search (800ms) and filter changes (300ms) are debounced
- **Batch Loading**: Tasks are loaded in batches of 50
- **Smart Updates**: Only affected UI components re-render when filters change
- **Efficient Evaluation**: Empty groups and incomplete conditions are handled efficiently
## Filter Evaluation Logic
Understanding how filters are evaluated:
1. **Empty Groups**: Groups with no conditions return true (no filtering)
2. **Incomplete Conditions**: Conditions missing required values are ignored
3. **Array Properties**: For properties with multiple values (tags, contexts), any matching value satisfies the condition
4. **Wiki Links**: Project values in `[[link]]` format are automatically resolved
5. **Case Sensitivity**: Text matching is case-insensitive
6. **Date Precision**: Date comparisons account for time components
# Dynamic date filters
- note.due >= today()
- note.due <= today() + 7d
```
## Example Filter Scenarios
### Simple Text Search
- Property: `title`
- Operator: `contains`
- Value: `meeting`
### Dynamic Date Filters
Using natural language dates for filters that stay current:
- Property: `due`
- Operator: `is-on-or-after`
- Value: `today`
### Complex Date Range
Group with AND conjunction:
- Condition 1: `due` `is-on-or-after` `2024-01-01`
- Condition 2: `due` `is-on-or-before` `2024-01-31`
### This Week's Tasks
Using natural language for relative time periods:
- Property: `due`
- Operator: `is-on-or-after`
- Value: `next week`
### High Priority Incomplete Tasks
Group with AND conjunction:
- Condition 1: `priority` `is` `high`
- Condition 2: `status.isCompleted` `is-not-checked`
```yaml
filters:
and:
- note.priority == "high"
- note.status != "done"
```
### Multiple Projects or Contexts
### Tasks Due This Week
Group with OR conjunction:
```yaml
filters:
and:
- note.due >= today()
- note.due <= today() + 7d
```
- Condition 1: `projects` `contains` `[[Work Project]]`
- Condition 2: `contexts` `is` `work`
### Tasks in Specific Project
### Folder-Based Filtering
```yaml
filters:
and:
- note.projects.contains("[[Work Project]]")
```
Filter tasks by their location in your vault:
### Tasks with Multiple Criteria
**Tasks in a specific folder:**
- Property: `path`
- Operator: `contains`
- Value: `Work/Projects` (shows tasks in the Work/Projects folder)
```yaml
filters:
and:
- or:
- note.status == "todo"
- note.status == "in-progress"
- note.priority == "high"
- note.contexts.contains("work")
- note.due >= today()
```
**Tasks in vault root:**
- Property: `path`
- Operator: `contains`
- Value: `(Root)` (shows tasks in the vault root directory)
### Tasks in Specific Folder
**Exclude tasks from specific folders:**
- Property: `path`
- Operator: `does-not-contain`
- Value: `Archive` (hides tasks in Archive folders)
```yaml
filters:
and:
- file.path.contains("Work/Projects")
```
**Tasks without folder structure:**
- Property: `path`
- Operator: `is-empty` (shows tasks with no folder path)
### Tasks Without Due Date
The path dropdown automatically populates with all unique folder paths found in your vault, making it easy to select existing locations.
```yaml
filters:
and:
- !note.due || note.due == "" || note.due == null
```
### Recurring Tasks
```yaml
filters:
and:
- note.recurrence && note.recurrence != "" && note.recurrence != null
```
### Custom User Field Examples
**Filtering by Effort Level (Number field):**
- Property: `Effort Level` (user field)
- Operator: `is greater than or equal`
- Value: `3`
Assuming you have a custom number field "effort-level":
This filters tasks where effort is 3 or higher, useful for finding substantial work items.
```yaml
filters:
and:
- note.effort-level >= 3
```
**Filtering by Team Members (List field):**
- Property: `Assigned To` (user field)
- Operator: `contains`
- Value: `John Smith`
Assuming you have a custom list field "assigned-to":
This finds tasks assigned to John Smith, even when multiple people are assigned.
```yaml
filters:
and:
- note.assigned-to.contains("John Smith")
```
**Mixed Priority Filtering (Number field with text):**
- Property: `Priority Level` (user field)
- Operator: `is greater than`
- Value: `1`
## Sorting
With values like "1-Low", "2-Medium", "3-High", if the custom property is defined as "Number" in the plugin settings, this shows Medium and High priority tasks by evaluating the numeric prefix.
Sorting is configured in the `sort` section of the view definition:
This filtering system provides the flexibility to create simple quick filters or complex multi-criteria queries while maintaining good performance and user experience.
```yaml
views:
- type: tasknotesTaskList
name: "My Tasks"
sort:
- column: due
direction: ASC
```
### Available Sort Columns
- `due` - Due date
- `scheduled` - Scheduled date
- `priority` - Priority level
- `status` - Task status
- `file.name` - Task title
- `file.ctime` - Creation date
- `file.mtime` - Modification date
- `completed-date` - Completion date
- `time-estimate` - Time estimate
- Custom user field keys
### Sort Direction
- `ASC` - Ascending (earliest first for dates, A-Z for text)
- `DESC` - Descending (latest first for dates, Z-A for text)
### Multiple Sort Criteria
```yaml
sort:
- column: priority
direction: DESC
- column: due
direction: ASC
```
## Grouping
Grouping is configured in the `groupBy` section of the view definition:
```yaml
views:
- type: tasknotesTaskList
name: "My Tasks"
groupBy:
property: status
direction: ASC
```
### Available Grouping Properties
- `status` - Group by task status
- `priority` - Group by priority level
- `contexts` - Group by first context
- `projects` - Group by project (tasks can appear in multiple groups)
- `due` - Group by due date ranges
- `scheduled` - Group by scheduled date ranges
- Custom user field keys
### Hierarchical Subgrouping
Bases supports two-level grouping where tasks are first grouped by a primary criterion, then subdivided within each group:
```yaml
views:
- type: tasknotesTaskList
name: "My Tasks"
groupBy:
property: status
direction: ASC
subgroupBy:
property: priority
direction: DESC
```
This creates groups by status, with subgroups by priority within each status group.
## Saved Views
In TaskNotes v4, saved views are `.base` files stored in your vault rather than in plugin settings. Each `.base` file represents a complete view configuration including filters, sorting, grouping, and view-specific options.
### Creating a Saved View
1. Create a new `.base` file in your vault (recommended location: `TaskNotes/Views/`)
2. Add YAML frontmatter with your filter configuration
3. Define the view type and options
Example `.base` file:
```yaml
# High Priority Tasks
filters:
and:
- note.priority == "high"
- note.status != "done"
views:
- type: tasknotesTaskList
name: "High Priority"
sort:
- column: due
direction: ASC
groupBy:
property: status
direction: ASC
```
### View Types
- `tasknotesTaskList` - List view
- `tasknotesKanban` - Kanban board view
- `tasknotesCalendar` - Calendar view
- `tasknotesMiniCalendar` - Mini calendar view
### View-Specific Options
Different view types support different options:
**Kanban View:**
```yaml
views:
- type: tasknotesKanban
name: "Kanban Board"
groupBy:
property: status
options:
columnWidth: 280
hideEmptyColumns: false
```
**Calendar View:**
```yaml
views:
- type: tasknotesCalendar
name: "Calendar"
options:
showScheduled: true
showDue: true
showRecurring: true
showTimeEntries: true
showTimeblocks: true
showPropertyBasedEvents: true
calendarView: "timeGridWeek"
firstDay: 0
slotMinTime: "06:00:00"
slotMaxTime: "22:00:00"
slotDuration: "00:30:00"
```
### Managing Saved Views
- **Create**: Add a new `.base` file in your vault
- **Edit**: Modify the YAML frontmatter in the `.base` file
- **Delete**: Delete the `.base` file
- **Share**: Share the `.base` file with others or commit to version control
## Migration from v3
TaskNotes v3 used a FilterBar UI component with saved views stored in plugin settings. Version 4 replaces this with Bases-based filtering configured through YAML in `.base` files.
### What Changed
- **UI Removal**: The FilterBar component with its visual query builder has been removed
- **Configuration Method**: Filters are now defined in YAML rather than through UI interactions
- **Storage Location**: Saved views are now `.base` files in your vault rather than in plugin data
- **Syntax**: Filter expressions use Bases syntax instead of FilterBar condition objects
### Converting v3 Saved Views
TaskNotes v4 includes a conversion tool to help migrate v3 saved views to `.base` files:
1. Open Settings → TaskNotes → General
2. In the **View Commands** section, click **Export All Saved Views to Bases**
3. Confirm the file path to generate a `.base` file containing your saved views
The exporter creates a single `.base` file (default: `TaskNotes/Views/all-saved-views.base`) with each saved view represented as a separate TaskNotes view inside the file.
### Manual Conversion
To manually convert a v3 saved view to a `.base` file:
1. Review your v3 filter conditions
2. Create a new `.base` file
3. Translate each condition to Bases expression syntax
4. Use the examples in this document as reference
**v3 Filter Example:**
- Property: `priority`, Operator: `is`, Value: `high`
- Property: `status.isCompleted`, Operator: `is-not-checked`
**v4 Equivalent:**
```yaml
filters:
and:
- note.priority == "high"
- note.status != "done"
```
## Property Order and Visibility
The `order` array in the view configuration controls which properties are displayed on task cards:
```yaml
views:
- type: tasknotesTaskList
name: "My Tasks"
order:
- file.name
- note.status
- note.priority
- note.due
- note.scheduled
- note.projects
- note.contexts
- file.tags
```
Properties not listed in the `order` array are hidden from task cards but still available for filtering and sorting.
## Bases Expression Reference
Bases is a core plugin maintained by Obsidian. Refer to Obsidian's documentation for complete details on expression syntax, functions, and capabilities.
### Common Functions
- `today()` - Current date
- `tomorrow()` - Tomorrow's date
- `date(value)` - Parse date value
- `list(value)` - Convert to list/array
- `.contains(value)` - Check if array contains value
- `.map(expression)` - Transform array values
- `.filter(expression)` - Filter array values
- `.length` - Array length
- `.lower()` - Lowercase string
- `.upper()` - Uppercase string
- `.format(pattern)` - Format date/value
### Logical Operators
- `&&` - Logical AND
- `||` - Logical OR
- `!` - Logical NOT
- `==` - Equality
- `!=` - Inequality
- `<` - Less than
- `>` - Greater than
- `<=` - Less than or equal
- `>=` - Greater than or equal
## Performance Considerations
Bases handles query execution and optimization. Filter performance depends on:
- **Filter Complexity**: Simpler filters execute faster
- **Vault Size**: Larger vaults take longer to query
- **Property Access**: File properties are generally faster than computed properties
- **Array Operations**: Operations on large arrays may be slower
For best performance:
- Use specific filters rather than broad ones
- Avoid nested array operations when possible
- Limit the number of view-specific options that require computation
## Filter Evaluation
Bases evaluates filters against the Obsidian metadata cache. Understanding evaluation behavior:
- **Empty Values**: Properties that are null, undefined, or empty strings require explicit checks
- **Array Properties**: For multi-value properties (tags, contexts, projects), use `.contains()` to check membership
- **Type Coercion**: Bases performs automatic type conversion in comparisons
- **Date Precision**: Date comparisons include time components
- **Case Sensitivity**: String comparisons are case-sensitive unless using `.lower()` or `.upper()`
## Additional Resources
- **View Types**: See [Views](../views.md) for details on each view type
- **Properties**: See [Task Management](task-management.md) for complete property reference
- **Settings**: See [General Settings](../settings/general.md) for field mapping configuration

111
docs/features/inline-tasks.md
View file

@ -1,5 +1,7 @@
# Inline Task Integration
[← Back to Features](../features.md)
TaskNotes integrates with the Obsidian editor to allow task management directly within notes. This is achieved through interactive widgets, a conversion feature for checkboxes, and natural language processing.
## Task Link Overlays
@ -127,43 +129,60 @@ Failed conversions typically occur due to:
- Insufficient disk permissions
- Very long task titles (over 200 characters)
## Project Subtasks Widget
## Relationships Widget
The **Project Subtasks Widget** displays tasks that reference the current note as a project. When viewing a project note, the widget automatically appears and shows all tasks that link to that project, providing a consolidated view of project-related work.
**New in v4**: The Relationships Widget consolidates what were previously three separate widgets (project subtasks, task dependencies, and blocking tasks) into a single dynamic interface.
The widget includes:
The widget appears in task notes and automatically displays up to four tabs based on available relationship data:
- **Collapsible Interface**: Click the widget title to expand or collapse the task list. The state is remembered between sessions.
- **FilterBar Integration**: Full filtering, sorting, and grouping capabilities with real-time filtering and count display.
- **Collapsible Groups**: When tasks are grouped, each group can be individually collapsed/expanded with persistent state. Includes expand/collapse all controls.
- **Saved Views System**: Access to saved filter configurations for consistent task organization.
- **Task Details**: Each task shows its status, priority, due date, and other properties.
- **Real-time Updates**: The widget updates automatically when tasks are added, modified, or deleted.
- **Smart Positioning**: The widget appears after frontmatter and properties but before the main note content.
- **Subtasks Tab (Kanban)**: Shows tasks that reference the current note as a project. Uses Kanban layout for visual task management.
- **Projects Tab (List)**: Shows projects that the current task belongs to. Uses list layout.
- **Blocked By Tab (List)**: Shows tasks that are blocking the current task. Uses list layout.
- **Blocking Tab (Kanban)**: Shows tasks that the current task is blocking. Uses Kanban layout.
The widget can be enabled or disabled in the plugin settings in the Misc tab under "Show project subtasks widget".
### Automatic Tab Management
Tabs automatically show or hide based on the presence of relationship data. If a task has no subtasks, the Subtasks tab does not appear. If there are no blocking relationships, those tabs remain hidden. This keeps the interface focused on relevant information.
### Features
The widget embeds the `TaskNotes/Views/relationships.base` view directly in the editor. Every filter, grouping rule, or property shown in that `.base` file is exactly what appears inside the widget, so you can customize the experience by editing the file just like any other Bases view.
Additional behavior:
- **Collapsible Interface**: Click the widget title to expand or collapse. The state is remembered between sessions.
- **Persistent Grouping**: Any grouping defined in the `.base` file is honoured, and collapsed groups retain their state per note.
- **Task Details**: Each task shows its status, priority, due date, and other configured properties.
- **Real-time Updates**: The widget updates automatically when tasks are added, modified, or deleted via Bases views.
### Configuration
Enable or disable the widget in **Settings → TaskNotes → Misc Settings → Show Relationships Widget**.
Position the widget at the top (after frontmatter) or bottom of the note using the **Relationships Position** setting.
### Expandable Subtasks Chevron
Project tasks can display an expand/collapse chevron that toggles the visibility of subtasks.
Tasks with subtasks can display an expand/collapse chevron that toggles subtask visibility.
- The chevron can be positioned on the Right (default, hover to show) or on the Left (always visible, matches group chevrons).
- Configure this in Settings → Misc → Subtask chevron position.
- Configure this in Settings → TaskNotes → Misc Settings → Subtask chevron position.
![Left subtask chevron](../assets/left-task-subtask-chevron.gif)
### Collapsible Groups
### Migration from v3
When tasks are grouped by status, priority, or other criteria, each group displays with a collapsible header. Click the chevron or group header to expand/collapse individual groups, with state persisted per note.
In v3, TaskNotes provided three separate widgets controlled by individual settings:
![Subtask widget collapsible groups](../assets/subtask-widget-collapsible-groups.gif)
- `showProjectSubtasks` and `projectSubtasksPosition`
- `showTaskDependencies` and `taskDependenciesPosition`
- `showBlockingTasks` and `blockingTasksPosition`
These settings are replaced in v4 by:
### Saved view heading and counts in Subtasks Widget
- `showRelationships` and `relationshipsPosition`
The Project Subtasks widget shows the saved view name and completion counts just like the Task List heading.
![Subtask widget saved view and counts](../assets/subtask_view_nam+count+task_count.png)
If you had project subtasks enabled in v3, the relationships widget will be enabled automatically after upgrading to v4. The underlying Bases file changed from `TaskNotes/Views/project-subtasks.base` to `TaskNotes/Views/relationships.base`. Run the **Create Default Files** command in Settings → General to create the new relationships.base file.
## Natural Language Processing
@ -171,14 +190,56 @@ TaskNotes includes a **Natural Language Processor (NLP)** that parses task descr
The NLP engine supports multiple languages, including English, Spanish, French, German, Italian, Japanese, Dutch, Portuguese, Russian, Swedish, Chinese, and Ukrainian.
The NLP engine supports syntax for:
### Supported Syntax
- **Tags and Contexts**: `#tag` and `@context` syntax.
The NLP engine recognizes:
- **Tags and Contexts**: `#tag` and `@context` syntax (triggers are customizable).
- **Projects**: `+project` for simple projects or `+[[Project Name]]` for projects with spaces.
- **Priority Levels**: Keywords like "high," "normal," and "low".
- **Status Assignment**: Keywords like "open," "in-progress," and "done".
- **Priority Levels**: Keywords like "high," "normal," and "low". Also supports a trigger character (default: `!`).
- **Status Assignment**: Keywords like "open," "in-progress," and "done". Also supports a trigger character (default: `*`).
- **Dates and Times**: Phrases like "tomorrow," "next Friday," and "January 15th at 3pm".
- **Time Estimates**: Formats like "2h," "30min," and "1h30m".
- **Recurrence Patterns**: Phrases like "daily," "weekly," and "every Monday".
- **User-Defined Fields**: Custom fields can be assigned using configured triggers (e.g., `effort: high`). Supports quoted values for multi-word entries.
The NLP engine is integrated with the task creation modal. Typing a natural language description there will populate the corresponding fields.
### Rich Markdown Editor
**New in v4**: The task creation modal uses a rich CodeMirror markdown editor instead of a plain textarea.
Features include:
- **Live Preview**: Rendered markdown preview as you type.
- **Syntax Highlighting**: Code blocks, links, and formatting are highlighted.
- **Wikilink Support**: Create links to other notes using `[[Note Name]]` syntax.
- **Keyboard Shortcuts**:
- `Ctrl/Cmd+Enter` saves the task
- `Esc` or `Tab` to navigate out of the editor
- **Placeholder Text**: Shows an example task (e.g., "Buy groceries tomorrow at 3pm @home #errands") when the editor is empty.
### Customizable Triggers
**New in v4**: Triggers for NLP properties can be customized in **Settings → Features → NLP Triggers**.
You can configure trigger characters or strings for:
- **Tags** (default: `#`) - When set to `#`, Obsidian's native tag suggester is used
- **Contexts** (default: `@`)
- **Projects** (default: `+`)
- **Status** (default: `*`)
- **Priority** (default: `!`, disabled by default)
- **User-Defined Fields** (default: `fieldname:`) - Each custom field can have its own trigger
Triggers support up to 10 characters and can include trailing spaces (e.g., `"def: "` for a custom field).
### Autocomplete
**New in v4**: When typing a trigger in the NLP editor, an autocomplete menu appears with available values.
- Navigate suggestions with arrow keys
- Select with `Enter` or `Tab`
- Autocomplete works for tags, contexts, projects, status, priority, and user-defined fields
- Tag autocomplete uses Obsidian's native tag suggester when using the `#` trigger
- For user fields with multi-word values, wrap the value in quotes (e.g., `effort: "very high"`)
The NLP engine is integrated with the task creation modal and bulk conversion features. Typing a natural language description populates the corresponding task fields automatically.

24
docs/features/task-management.md
View file

@ -1,6 +1,8 @@
# Task Management
TaskNotes provides a system for managing tasks, which is built on the principle of "one note per task." This approach allows you to create, edit, and organize your tasks with a set of properties, while maintaining the portability and extensibility of plain text files.
[← Back to Features](../features.md)
TaskNotes provides a system for managing tasks based on the principle of "one note per task." This approach allows you to create, edit, and organize tasks with a set of properties while maintaining the portability and extensibility of plain text files.
## Creating and Editing Tasks
@ -117,7 +119,7 @@ Projects are stored as wikilinks in the task's frontmatter (e.g., `projects: ["[
### Organization and Filtering
Tasks can be filtered and grouped by their associated projects in all task views. The FilterBar includes project-specific filters, and tasks can be grouped by project in the Task List and Kanban views. Tasks assigned to multiple projects will appear in each relevant project group, providing flexibility in project-based organization.
Tasks can be filtered and grouped by their associated projects in all Bases-driven task views. Use the Bases filter editor to add `note.projects` conditions, and configure the grouping menu to organize Task List or Kanban boards by project. Tasks assigned to multiple projects will appear in each relevant project group, providing flexibility in project-based organization.
### Project Indicators
@ -171,7 +173,7 @@ TaskNotes also supports **Templates** for both the YAML frontmatter and the body
## Recurring Tasks
TaskNotes provides sophisticated recurring task management using the RFC 5545 RRule standard with enhanced DTSTART support and dynamic scheduled dates. The system separates recurring pattern behavior from individual occurrence scheduling, giving you complete control over both aspects.
TaskNotes provides recurring task management using the RFC 5545 RRule standard with DTSTART support and dynamic scheduled dates. The system separates recurring pattern behavior from individual occurrence scheduling.
### Core Concepts
@ -189,8 +191,8 @@ This separation allows for flexible scheduling where you can reschedule individu
You can create recurring tasks through:
1. **Recurrence Context Menu**: Right-click the recurrence field in any task modal to access preset patterns or custom recurrence options
2. **Preset Options**: Quick selections like "Daily," "Weekly on [current day]," "Monthly on the [current date]"
3. **Custom Recurrence Modal**: Advanced editor with date picker, time picker, and full RRule configuration
2. **Preset Options**: Selections like "Daily," "Weekly on [current day]," "Monthly on the [current date]"
3. **Custom Recurrence Modal**: Editor with date picker, time picker, and RRule configuration
#### Required Components
@ -222,7 +224,7 @@ To enable this feature, go to the TaskNotes settings and select the "Features" t
### Recurrence Pattern Examples
TaskNotes supports the full RFC 5545 RRule standard with DTSTART:
TaskNotes supports the RFC 5545 RRule standard with DTSTART:
```
DTSTART:20250804T090000Z;FREQ=DAILY
@ -240,7 +242,7 @@ DTSTART:20250801T100000Z;FREQ=MONTHLY;BYDAY=-1FR
### Visual Hierarchy in Calendar Views
The Advanced Calendar View displays recurring tasks with distinct visual styling:
The Calendar View displays recurring tasks with distinct visual styling:
#### Next Scheduled Occurrence
- **Solid border** with full opacity
@ -379,20 +381,20 @@ TaskNotes maintains full backward compatibility:
#### Custom Recurrence Modal
Access advanced options through the custom recurrence modal:
The custom recurrence modal provides:
- **Start date picker**: Set the DTSTART date
- **Start time picker**: Set the DTSTART time (optional)
- **Frequency options**: Daily, weekly, monthly, yearly
- **Advanced patterns**: Complex RRule configurations
- **RRule patterns**: RRule configurations
- **End conditions**: Until date, count limits, or never-ending
#### Time Independence
Pattern time (DTSTART) and next occurrence time (scheduled) are completely independent:
Pattern time (DTSTART) and next occurrence time (scheduled) are independent:
- Pattern instances can appear at 9 AM while next occurrence is at 2 PM
- Dragging pattern instances changes the pattern time for all future instances
- Dragging next occurrence only affects that specific instance
- Users have complete control over both timing aspects
- Both timing aspects can be controlled separately
## Task Reminders

8
docs/features/user-fields.md
View file

@ -107,10 +107,10 @@ Autosuggestion filters:
Once you have created a user field, it will be available in the following places:
- **Task Modals**: The user field will be displayed as a field in the task creation and edit modals.
- **Filtering**: You can filter your tasks by the user field in the FilterBar.
- **Sorting**: You can sort your tasks by the user field.
- **Grouping**: You can group your tasks by the user field.
- **Task Modals**: The user field will be displayed in the task creation and edit modals.
- **Bases Filters**: Add the field to Bases filter expressions (for example `note.effort == "high"`) to narrow task lists and Kanban boards.
- **Sorting**: Use the Bases sort menu to order tasks by the user field.
- **Grouping**: Use the Bases group menu to create swimlanes or list groupings based on the user field.
## Frontmatter

43
docs/index.md
View file

@ -4,47 +4,52 @@ TaskNotes is a task and note management plugin for Obsidian that follows the "on
## How It Works
The plugin treats each task as a separate note with structured metadata in the frontmatter. This approach aligns with Obsidian's "files over applications" philosophy - your tasks have structured data for organization while the note content remains completely flexible.
The plugin treats each task as a separate note with structured metadata in the frontmatter. Tasks have structured data for organization while the note content remains flexible.
TaskNotes builds on Obsidian's native metadata cache, which means it works well with other plugins and benefits from Obsidian's existing performance optimizations. Since task data lives in YAML frontmatter, you can add custom fields and modify property names to match your vault's existing structure.
TaskNotes uses Obsidian's metadata cache for compatibility with other plugins. Since task data lives in YAML frontmatter, you can add custom fields and modify property names to match your vault's existing structure.
The plugin doesn't lock you into any specific task management methodology. Whether you prefer Getting Things Done, timeboxing, or project-based organization, TaskNotes provides the tools without forcing a particular workflow.
The main views (Task List, Kanban, and Calendar) are built using the Bases core plugin and stored as `.base` files in the `TaskNotes/Views/` directory. Bases is an official Obsidian core plugin that must be enabled from Settings → Core Plugins. View configuration is managed through YAML, and filtering is handled directly within each view's configuration rather than through a separate FilterBar component.
The plugin does not enforce a specific task management methodology.
## Requirements
- **Obsidian**: Version 1.10.1 or later (TaskNotes v4 relies on the Bases public API introduced in 1.10.1)
- **Bases Core Plugin**: Must be enabled from Settings → Core Plugins (required for Task List, Kanban, Calendar, Agenda, and MiniCalendar views)
## Features
Each task supports standard properties like title, status, priority, due dates, contexts, and tags, plus time estimates, recurrence patterns, and reminders. Custom fields let you extend this structure however you need.
Each task supports properties including title, status, priority, due dates, contexts, tags, time estimates, recurrence patterns, and reminders. Custom fields extend this structure.
The built-in time tracking records work sessions directly in each task's frontmatter. For focused work, there's an integrated Pomodoro timer that automatically logs sessions to your tasks.
Time tracking records work sessions in each task's frontmatter. The Pomodoro timer logs timed work sessions to tasks.
You can view your tasks through eight different interfaces: traditional task lists, calendar views (both mini and advanced), Kanban boards, agenda views, notes browsers, and Pomodoro tracking. Each view offers different ways to organize and interact with your data.
The plugin provides multiple views. The Task List view handles filtering and organizing tasks. The Kanban board includes optional swimlane layouts for grouping. The Calendar view offers month, week, day, year, and list modes. The Agenda command opens the calendar in list mode for daily or weekly reviews. The MiniCalendar provides fuzzy search and keyboard navigation. The Task List, Kanban, Calendar, Agenda, and MiniCalendar views are implemented as Bases views. The Pomodoro timer is a standalone component.
The plugin integrates directly into Obsidian's editor with inline task widgets that show task information right in your notes. Convert existing checkbox tasks instantly, or use natural language processing to create structured tasks from plain text.
Inline task widgets display task information in the editor. Convert existing checkbox tasks or create tasks using natural language processing that parses plain text into structured tasks. Task modal fields are configurable.
Calendar integration works with external ICS feeds from Google Calendar, Outlook, and similar services. The advanced calendar view supports time-blocking and lets you drag tasks to reschedule them visually.
Calendar integration supports ICS feeds and OAuth authentication for Google Calendar and Microsoft Outlook. The Calendar view supports time-blocking and drag-to-reschedule.
## Why One Note Per Task?
Individual task notes give you more than just basic task management. Each task can contain meeting notes, research, brainstorming, or any other content that makes sense alongside the task itself.
Each task can contain meeting notes, research, brainstorming, or other content alongside the task itself.
Since every task is a proper note, you get full access to Obsidian's linking system. Tasks can reference other notes, appear in your graph view, and show up in backlinks just like any other content in your vault.
Tasks can reference other notes, appear in graph view, and show up in backlinks.
This approach gives you structured metadata when you need it (for filtering and organizing) while keeping the actual note content completely flexible. You're not limited to predefined fields or rigid templates.
This approach provides structured metadata for filtering and organizing while keeping note content flexible.
## Plain Text Advantages
Your task data lives in standard Markdown files with YAML frontmatter. This means you can edit tasks with any text editor, process them with scripts, or migrate them to other systems without vendor lock-in.
Task data lives in standard Markdown files with YAML frontmatter. You can edit tasks with any text editor, process them with scripts, or migrate them to other systems.
YAML frontmatter is widely supported and human-readable, so other Obsidian plugins can work with your task data. You can extend the structure by adding new fields whenever you need them.
YAML frontmatter is human-readable. Other Obsidian plugins can work with your task data. You can extend the structure by adding fields.
Since everything is plain text, your tasks work naturally with version control systems like Git. The plugin leverages Obsidian's native metadata cache, so performance stays good even with thousands of tasks.
Tasks work with version control systems like Git. The plugin uses Obsidian's metadata cache.
## Getting Started
To begin using TaskNotes effectively:
1. **Install and Enable**: Install the plugin from the Obsidian Community Plugins directory
2. **Create Your First Task**: Use the "Create Task" command or convert an existing checkbox
3. **Explore Views**: Try the different view types to find what works for your workflow
4. **Configure Settings**: Customize task properties, views, and integrations as needed
3. **Explore Views**: Try the different view types
4. **Configure Settings**: Customize task properties, views, and integrations
The plugin includes default settings that can be customized to support various task management approaches. Use the navigation menu to explore features, configuration options, and advanced capabilities.
The plugin includes default settings that can be customized. Use the navigation menu to explore features, configuration options, and capabilities.

48
docs/releases/4.0.0.md Normal file
View file

@ -0,0 +1,48 @@
# TaskNotes 4.0.0
TaskNotes 4.0 is a stability-focused release that finishes the migration to Obsidian's Bases core plugin. Every task-facing view (Task List, Kanban, Calendar, Agenda, Mini Calendar, and the embedded Relationships widget) now runs on `.base` files. This refactor simplifies the plugin codebase, removes bespoke FilterBar UI logic, and lets workflows feel native to Obsidian—views are just files in your vault that you can version, share, and customize.
## Highlights
- **Bases-first architecture**
- Task views ship as `.base` files inside `TaskNotes/Views/`
- Commands and ribbon buttons now open files you control
- Filtering/grouping/sorting uses Bases YAML instead of TaskNotes-specific UI
- Agenda is a dedicated list-mode calendar `.base` file for fast daily/weekly reviews
- **Inline workflows stay in sync**
- Unified Relationships widget embeds a Bases view so project subtasks, dependencies, and blocking tasks stay in one place
- Task cards inside notes honor the same Bases filtering/grouping rules as standalone views
- **Configurable modals and NLP**
- New Modal Fields settings tab for dragging, hiding, or requiring fields in create/edit modals
- Rich markdown editor and customizable NLP triggers, including autocomplete for user fields
- **Calendar and time management**
- Calendar view modes, time entry creation, and timeblocking now run directly through Bases configuration
- OAuth calendar sync (Google/Microsoft) and ICS subscriptions surface alongside tasks without custom view code
## Why Bases?
Moving everything to Bases allowed us to delete thousands of lines of bespoke filtering logic, state management, and widget code. The plugin now leans on Obsidian's supported API, which:
- Reduces maintenance overhead and improves reliability
- Lets advanced users version-control and audit their view definitions
- Makes saved views portable between vaults and team members
- Keeps TaskNotes behavior consistent with other Obsidian-native workflows
## Upgrade Notes
- Obsidian **1.10.1 or later** is required (Bases public API with group-by support)
- Enable the **Bases** core plugin before opening TaskNotes views
- Run **Settings → TaskNotes → General → Create Default Files** if you need fresh `.base` files
- Use **Export All Saved Views to Bases** to convert any legacy FilterBar saved views into `.base` files
- The Relationships widget now uses `TaskNotes/Views/relationships.base`; adjust that file to change what appears inside notes
## Breaking Changes
- The old FilterBar UI has been removed—all filtering and saved views live in `.base` files
- Legacy widget settings (`showProjectSubtasks`, `showTaskDependencies`, etc.) were replaced with `showRelationships` and `relationshipsPosition`
- Task view commands now fail if their mapped `.base` file is missing; configure paths under **Settings → TaskNotes → General → View Commands**
## Known Issues
- Users upgrading from versions prior to 3.x should export saved views to Bases before deleting old plugin data
- Embedded Bases views still require the Bases plugin to remain enabled; disabling Bases will hide TaskNotes task views

16
docs/settings.md
View file

@ -6,15 +6,15 @@ TaskNotes provides a variety of settings to customize its behavior and appearanc
## General
These settings control the foundational aspects of the plugin, such as task identification, file storage, and click behavior.
These settings control task identification, file storage, and click behavior.
For more detailed information, see the [General Settings](settings/general.md) documentation.
For more information, see the [General Settings](settings/general.md) documentation.
## Features
These settings allow you to enable, disable, and configure the various features of the plugin, such as inline tasks, natural language processing, the Pomodoro timer, and notifications.
These settings control inline tasks, natural language processing, the Pomodoro timer, and notifications.
For more detailed information, see the [Features Settings](settings/features.md) documentation.
For more information, see the [Features Settings](settings/features.md) documentation.
## Defaults & Templates
@ -34,8 +34,14 @@ These settings allow you to define custom statuses, priorities, and user fields
For more detailed information, see the [Task Properties Settings](settings/task-properties.md) documentation.
## Modal Fields
These settings control which fields appear in task creation and edit modals. Configure field visibility, ordering, and grouping. Fields can be enabled or disabled individually, and reordered within their groups using drag-and-drop.
For more information, see the [Modal Fields Settings](settings/modal-fields.md) documentation.
## Integrations
These settings control the integration with other plugins and services, such as Bases and external calendars.
These settings control integration with external services and plugins. This includes OAuth calendar connections (Google Calendar and Microsoft Outlook), Bases plugin integration, calendar subscriptions from ICS/iCal sources, automatic ICS export, HTTP API configuration, and webhook management.
For more detailed information, see the [Integrations Settings](settings/integrations.md) documentation.

10
docs/settings/advanced-settings.md
View file

@ -44,7 +44,7 @@ These settings provide customization options, such as field mapping, custom stat
### Smart List Filtering
User fields of type **List** support intelligent comma splitting that preserves:
User fields of type **List** support comma splitting that preserves:
- **Wikilinks**: `[[Health, Fitness & Mindset]], [[Nutrition]]` correctly splits into two items
- **Quoted text**: `"Focus, Deep Work", Notes` treats quoted content as single items
- **Mixed content**: Handles combinations of wikilinks, quotes, and plain text
@ -64,11 +64,7 @@ This allows filtering like "Priority greater than 1" to match "2-Medium" and "3-
### Instant Availability
User fields become available in filter, sorting, and grouping menus immediately after configuration—no plugin reload required. The fields appear in all TaskNotes views (Task List, Agenda, Kanban, Advanced Calendar) as soon as you save the settings.
### Technical Implementation
For developers interested in the technical details of User Fields implementation, see [User Fields Technical Documentation](../development/USER_FIELDS_TECHNICAL.md).
User fields become available in the Bases filter/sort/group controls immediately after configuration—no plugin reload required. The fields appear in all TaskNotes views (Task List, Agenda, Kanban, Calendar View) as soon as you save the settings.
## Custom Status System
@ -94,4 +90,4 @@ The Field Mapping section includes two additional fields for ICS integration:
**ICS Event ID** - Frontmatter field name for storing calendar event identifiers. Default is `icsEventId`. This field maintains the connection between vault content and calendar events.
**ICS Event Tag** - Tag used to identify content created from ICS events. Default is `ics_event`. This tag is automatically added to notes and tasks generated from calendar events.
**ICS Event Tag** - Tag used to identify content created from ICS events. Default is `ics_event`. This tag is automatically added to notes and tasks generated from calendar events.

4
docs/settings/calendar-settings.md
View file

@ -4,7 +4,7 @@ These settings control the appearance and behavior of the calendar views, as wel
## Default Calendar View
You can set the **Default View** for the Advanced Calendar, choosing from month, week, day, year, or custom days. You can also configure the **Time Slot Duration** and the **Time Range** that is displayed in the week, day, and custom days views.
You can set the **Default View** for the Calendar View, choosing from month, week, day, year, or custom days. You can also configure the **Time Slot Duration** and the **Time Range** that is displayed in the week, day, and custom days views.
**Custom view day count** - When using the Custom Days view, this slider controls how many days (2-10) are displayed simultaneously. The default is 3 days, which provides optimal screen space utilization while maintaining detailed scheduling capabilities.
@ -20,7 +20,7 @@ You can control which types of events are shown by default in the calendar views
## Timeblocking Features
You can enable or disable the **Timeblocking** feature in the Features tab, which allows you to create and manage timeblocks in the calendar views. Usage: hold Shift + drag in the advanced calendar view to create timeblocks.
You can enable or disable the **Timeblocking** feature in the Features tab, which allows you to create and manage timeblocks in the calendar views. When enabled, dragging on a time slot in the calendar view will display a context menu that includes the "Create timeblock" option.
## External Calendar Integration

2
docs/settings/features.md
View file

@ -57,4 +57,4 @@ These settings allow you to enable, disable, and configure the various features
### Usage
In the advanced calendar view, hold Shift + drag to create timeblocks. Drag to move existing timeblocks. Resize edges to adjust duration.
In the calendar view, click and drag on a time slot to select a time range. A context menu will appear—select "Create timeblock" to create a timeblock (this option only appears if timeblocking is enabled in settings). Drag existing timeblocks to move them. Resize edges to adjust duration.

71
docs/settings/integrations.md
View file

@ -7,9 +7,76 @@ These settings control the integration with other plugins and services, such as
## Bases integration
- **Enable Bases integration**: Enable TaskNotes views to be used within Obsidian Bases plugin. Bases plugin must be enabled for this to work.
TaskNotes v4 requires the Bases core plugin for main task views (Calendar, Kanban, Tasks, Agenda) to function. Bases is an official Obsidian core plugin built directly into Obsidian, not a community plugin.
## Calendar subscriptions
**To enable Bases:**
1. Open Settings → Core Plugins
2. Enable "Bases"
3. Restart Obsidian
Once enabled, TaskNotes view commands and ribbon icons will open `.base` files from your vault. Default `.base` files are automatically created in the `TaskNotes/Views/` directory on first launch.
### View Commands Configuration
Configure which `.base` files are opened by TaskNotes view commands and ribbon icons. These settings allow you to customize which files open when you use familiar TaskNotes shortcuts.
Access these settings in **Settings → TaskNotes → General → View Commands**.
Available command mappings:
- **Open Mini Calendar View**: Default opens `TaskNotes/Views/mini-calendar-default.base`
- **Open Kanban View**: Default opens `TaskNotes/Views/kanban-default.base`
- **Open Tasks View**: Default opens `TaskNotes/Views/tasks-default.base`
- **Open Calendar View**: Default opens `TaskNotes/Views/calendar-default.base`
- **Open Agenda View**: Default opens `TaskNotes/Views/agenda-default.base`
- **Relationships Widget**: Default opens `TaskNotes/Views/relationships.base`
Each command allows you to specify a custom `.base` file path and includes a reset button to restore the default path.
**Create Default Files**: Button to generate all default `.base` files in the `TaskNotes/Views/` directory. Existing files are not overwritten.
## OAuth Calendar Integration
Connect Google Calendar or Microsoft Outlook to sync events bidirectionally with TaskNotes. Events automatically refresh every 15 minutes and sync when local changes are made (such as dragging events to reschedule).
### Setup Requirements
OAuth integration requires creating your own OAuth application with Google and/or Microsoft. Initial setup takes approximately 15 minutes per provider.
**Setup Guide**: See [Calendar Integration Setup](../calendar-setup.md) for detailed instructions on creating OAuth credentials with Google Cloud Console and Azure Portal.
### Google Calendar
- **Client ID**: OAuth 2.0 Client ID from Google Cloud Console
- **Client Secret**: OAuth 2.0 Client Secret from Google Cloud Console
- **Connect Google Calendar**: Button to authenticate via OAuth 2.0 loopback flow
- **Disconnect**: Revokes access and removes stored credentials
When connected, displays:
- Connected account email
- Connection time
- Last sync time
- Manual refresh button
### Microsoft Outlook Calendar
- **Client ID**: Application (client) ID from Azure Portal
- **Client Secret**: Client secret from Azure Portal
- **Connect Microsoft Calendar**: Button to authenticate via OAuth 2.0
- **Disconnect**: Revokes access and removes stored credentials
When connected, displays:
- Connected account email
- Connection time
- Last sync time
### Security
- OAuth credentials are stored locally in Obsidian's data folder
- Access tokens refresh automatically
- Calendar data syncs directly between Obsidian and the calendar provider (no intermediary servers)
- Disconnect at any time to revoke access
## Calendar subscriptions (ICS)
- **Default note template**: Path to template file for notes created from ICS events.
- **Default note folder**: Folder for notes created from ICS events. Supports template variables (e.g., `Daily/{{year}}/{{month}}/{{day}}`, `Events/{{icsEventTitle}}`). See ICS Integration documentation for full list of supported variables.

16
docs/settings/misc-settings.md
View file

@ -4,21 +4,21 @@ These settings control various plugin features and display options that don't fi
## Saved Views button position
Choose where the Saved Views button appears in the FilterBar of supported views (Task List, Agenda, Kanban, Advanced Calendar):
Choose where the Saved Views button appears in the view header for Task List, Agenda, Kanban, and Calendar Bases views:
- Right (default): Filter → Search → Saved Views
- Left: Saved Views → Filter → Search
- **Right (default)**: Saved Views sits after the other header controls
- **Left**: Saved Views is placed before the other controls
This setting affects layout only; functionality is the same. See examples in Filtering and Views.
This setting only changes alignment—the button still opens the same Saved Views picker.
## Status Bar
**Show tracked tasks in status bar** - Display currently tracked tasks (with active time tracking) in the status bar at the bottom of the app. This provides a quick visual indicator of which tasks are currently being tracked without needing to open the TaskNotes views.
## Project Subtasks Widget
## Relationships Widget
**Show project subtasks widget** - Display a collapsible widget showing all tasks that reference the current note as a project. This widget appears in the editor when viewing notes that have tasks referencing them as projects, providing quick access to related tasks.
**Show relationships widget** - Display the unified widget that surfaces subtasks, parent projects, and blocking relationships in the editor. Disable this if you prefer to open the `relationships.base` file in a separate pane instead of embedding it in notes.
## Task Display
@ -27,7 +27,7 @@ This setting affects layout only; functionality is the same. See examples in Fil
## Subtask Chevron Position
Configure where the expand/collapse chevron appears on project task cards and in the Project Subtasks Widget.
Configure where the expand/collapse chevron appears on project task cards and inside the Relationships widget.
- Right (default): The chevron appears on the right-hand side and shows on hover.
- Left (match group chevrons): The chevron appears on the left-hand side, always visible, matching group chevrons.
@ -40,4 +40,4 @@ Demo:
**Disable note indexing** - Disable indexing and caching of non-task notes to improve performance in large vaults. Note: This will disable the Notes view and notes display in the Agenda view. Requires plugin restart to take effect.
This setting is useful for large vaults where performance may be impacted by indexing many notes. When enabled, TaskNotes will only index and track task files, which can significantly improve performance but will disable some features that depend on note content.
This setting is useful for large vaults where performance may be impacted by indexing many notes. When enabled, TaskNotes will only index and track task files, which can significantly improve performance but will disable some features that depend on note content.

34
docs/settings/modal-fields.md Normal file
View file

@ -0,0 +1,34 @@
# Modal Fields Settings
The Modal Fields tab lets you decide exactly which fields appear in the task creation and edit modals. Open **Settings → TaskNotes → Modal Fields** to manage the configuration.
## Field Groups
Fields are organized into draggable groups:
- **Basic Information** – Title and Details
- **Metadata** – Contexts, Tags, Time Estimate
- **Organization** – Projects and Subtasks
- **Dependencies** – Blocked By and Blocking
- **Custom Fields** – Any user-defined fields that you add through Task Properties
Each group can be collapsed, and their order in the manager matches the order shown in the modal.
## Managing Fields
Every field entry includes:
- **Visibility toggles** for creation and edit modals
- **Enable/disable** checkbox
- **Drag handle** for ordering within its group
- **Required** toggle (where applicable, e.g., Title)
Changes are saved automatically. Use this to hide fields you never touch, ensure required metadata appears up front, or reorder fields to match your workflow.
## Syncing User Fields
The **Sync User Fields** button pulls the latest user-defined fields from the Task Properties tab into the Custom Fields group. New user fields are appended, renamed fields update in place, and removed fields drop out of the configuration. Re-run the sync whenever you add or rename custom fields.
## Resetting to Defaults
Select **Reset to Defaults** to restore the stock configuration (all built-in fields enabled plus empty custom slots). The reset keeps your existing user field definitions; it only reverts modal layout and visibility.

40
docs/views.md
View file

@ -1,31 +1,33 @@
# Views
TaskNotes offers a variety of views, each providing a different perspective on your tasks and notes.
TaskNotes provides multiple views for managing tasks and tracking productivity. All task-focused views operate as `.base` files located in the `TaskNotes/Views/` directory and require Obsidian's Bases core plugin to be enabled.
[← Back to Documentation](index.md)
## Bases Plugin Requirement
All task-focused views in TaskNotes v4 use Obsidian's **Bases core plugin**. This is an official Obsidian plugin built directly into the application, not a community plugin.
**To enable Bases:**
1. Open Settings → Core Plugins
2. Enable "Bases"
3. TaskNotes view commands and ribbon icons will open `.base` files from `TaskNotes/Views/`
Bases views use YAML configuration in `.base` files to define filtering, sorting, and grouping behavior. View configurations from TaskNotes v3 must be manually converted to `.base` file format.
## Task-Focused Views
These views are for managing your tasks and tracking your progress.
All task-focused views are implemented as Bases views using `.base` files.
- **[Task List View](views/task-list.md)**: A list-based view of all your tasks, with filtering, sorting, and grouping capabilities.
- **[Agenda View](views/agenda-view.md)**: A chronological view of your upcoming tasks and notes, for daily and weekly planning.
- **[Kanban View](views/kanban-view.md)**: A card-based view of your tasks, organized by status.
- **[Calendar Views](views/calendar-views.md)**: A set of calendar-based views for visualizing your tasks and scheduling your work.
### FilterBar Integration
The Task List, Agenda, Kanban, and Advanced Calendar views include a FilterBar that provides hierarchical query building, saved views, and real-time filtering capabilities. See the [Task List View](views/task-list.md) documentation for complete FilterBar functionality details.
## Note-Focused Views
This view is for browsing and reviewing your notes.
- **[Notes View](views/notes-view.md)**: A date-based view of your notes.
- **[Task List View](views/task-list.md)**: Displays tasks in a list format. Supports filtering, sorting, and grouping via YAML configuration in the `.base` file.
- **[Kanban View](views/kanban-view.md)**: Displays tasks as cards organized by status. Supports optional swimlane layout for additional organization.
- **[Calendar Views](views/calendar-views.md)**: Calendar-based task visualization with multiple view modes (month, week, day, year, list). Supports drag-and-drop scheduling, time-blocking, and OAuth calendars.
- **[Agenda View](views/agenda-view.md)**: A preconfigured calendar list view opened via its own command. It uses the same `.base` infrastructure as the calendar but defaults to `listWeek` mode for fast daily and weekly reviews.
- **[MiniCalendar View](views/calendar-views.md#mini-calendar-view)**: Month-based calendar showing which days have tasks. Includes fuzzy search and keyboard navigation for quick date navigation.
## Productivity-Focused Views
These views are for focus and productivity.
These views support time management and work tracking.
- **[Pomodoro View](views/pomodoro-view.md)**: A Pomodoro timer.
- **[Pomodoro Stats View](views/pomodoro-view.md#pomodoro-stats-view)**: Analytics and visualizations of your work habits.
- **[Pomodoro View](views/pomodoro-view.md)**: Pomodoro timer for focused work sessions.
- **[Pomodoro Stats View](views/pomodoro-view.md#pomodoro-stats-view)**: Displays analytics and visualizations of completed Pomodoro sessions and work patterns.

54
docs/views/agenda-view.md
View file

@ -1,35 +1,51 @@
# Agenda View
The Agenda View displays a chronological list of tasks and notes, sorted by their due and scheduled dates.
[← Back to Views](../views.md)
## FilterBar Integration
The Agenda view is a dedicated `.base` file that opens the calendar in list mode. It provides a scrollable agenda of upcoming tasks, notes, and external calendar events without needing to switch the primary calendar into list view manually.
The Agenda View includes the same FilterBar functionality as the Task List View, allowing you to filter, sort, and save views of your tasks. This includes support for hierarchical subgrouping, where tasks can be organized into primary groups and then further subdivided into subgroups.
## File Location
See the [Task List View](task-list.md) documentation for complete FilterBar functionality details, including subgrouping configuration.
- Default file: `TaskNotes/Views/agenda-default.base`
- Command: **Open Agenda View** (ribbon icon and command palette)
- Configure the file path in **Settings → TaskNotes → General → View Commands**
The file is created automatically the first time you run the command, and you can replace it with your own `.base` file if you maintain multiple agendas.
### Saved view heading, counts, and collapsible groups
## Default Configuration
- The Agenda heading shows the saved view name with a completion count (completed / total), consistent with the Task List.
- Date groups are collapsible, with “Expand All” and “Collapse All” buttons always visible in the FilterBar top controls.
- Collapsed state is remembered between sessions.
The stock agenda file renders the calendar in `listWeek` mode:
![Agenda saved view and collapsible groups](../assets/agenda-collapsible-group-and-item-count.gif)
```yaml
views:
- type: tasknotesCalendar
name: "Agenda"
calendarView: "listWeek"
listDayCount: 7
startDateProperty: file.ctime
titleProperty: file.basename
order:
- note.status
- note.priority
- note.due
- note.scheduled
```
## Content Organization
This configuration displays seven days at a time, derives entries from `file.ctime`/`file.basename`, and inherits the same display options (show scheduled/due/recurring/timeblocks/time entries/ICS events) as the primary calendar view.
The Agenda View groups tasks and notes by time. The default groups are "Overdue," "Today," "Tomorrow," "This Week," "Next Week," and "Later." Within each group, items are sorted by priority.
## Customization
## View Options
Edit the `.base` file to tailor the agenda:
The Agenda View provides several display options that can be configured:
- Change `calendarView` to `listDay` or `listMonth` for different spans
- Adjust `listDayCount` for shorter or longer agendas
- Add `filters` to focus on specific projects, tags, or statuses
- Modify `order` to control which task properties appear in the row layout
- **Show overdue on today**: When enabled, overdue tasks appear in the "Today" section alongside today's tasks
- **Show notes**: Controls whether daily notes are displayed alongside tasks in the agenda
Because the view runs inside Bases, any YAML changes are applied immediately after saving the file.
These options are preserved when you save a view, allowing you to create saved views with specific display preferences that persist across sessions.
## Usage Tips
## Focus Features
The view provides controls for the date range and for the display of completed tasks. It also uses visual styling to distinguish overdue and high-priority items.
- Use the calendar toolbar arrows (Previous/Next) to move the agenda window forward or backward, or simply scroll the list to review upcoming entries
- Saved views within Bases let you maintain multiple agenda variants (e.g., "Work Week" vs. "Personal")
- Calendar display options (show due, show scheduled, etc.) persist when you save the `.base` file, so you can maintain one agenda that includes external events and another that focuses strictly on TaskNotes tasks

83
docs/views/calendar-views.md
View file

@ -1,14 +1,48 @@
# Calendar Views
TaskNotes provides two calendar-based views for visualizing and managing your tasks: the **Mini Calendar** and the **Advanced Calendar**.
[← Back to Views](../views.md)
TaskNotes provides two calendar-based views: the **Mini Calendar** and the **Calendar View**. Both operate as Bases views (`.base` files) and require the Bases core plugin to be enabled in Obsidian.
## Bases View Architecture
Calendar views in TaskNotes v4 are implemented as Bases views, which means:
- Calendar views are created as `.base` files in your vault
- Configuration is controlled through YAML frontmatter in the base file
- The Bases plugin is an official Obsidian core plugin and must be enabled
- Views can be opened in tabs, pinned, and managed like other Obsidian views
## Mini Calendar View
The Mini Calendar is a month-based view that shows which days have tasks. It is designed for navigation and for providing an overview of your task distribution.
The Mini Calendar displays a month-based view that shows which days contain tasks or other dated notes. It provides navigation and an overview of your task distribution across time.
## Advanced Calendar View
### Features
The Advanced Calendar is a calendar with multiple view modes (month, week, day, year, and custom days), drag-and-drop scheduling, and time-blocking capabilities. You can create new tasks by clicking on dates or time slots, and you can reschedule tasks by dragging them to a new date or time.
- **Date Navigation**: Click any date to open a fuzzy selector modal showing all notes associated with that date
- **Keyboard Navigation**: Navigate the calendar using arrow keys and select dates with Enter
- **Heatmap Styling**: Visual indicators show the density of tasks or notes on each day
- **Configurable Date Property**: Set which date property to track (not limited to tasks - can display any dated notes based on configured property)
- **Month Navigation**: Browse forward and backward through months to view historical and future task distribution
## Calendar View
The Calendar View provides multiple view modes (month, week, day, year, list, and custom days) with drag-and-drop scheduling and time-blocking capabilities. Tasks can be created by clicking on dates or time slots, and rescheduled by dragging them to new dates or times.
### View Modes
The Calendar View supports the following view modes:
- **Month**: Month grid showing all-day and timed events
- **Week**: Week view with hourly time slots for detailed scheduling
- **Day**: Single day view with hourly breakdown
- **Year**: Annual overview showing event distribution across months
- **List**: Chronological list of events. TaskNotes also includes a dedicated Agenda command that opens this mode via its own `.base` file for quick reviews.
- **Custom Days**: Configurable multi-day view (2-10 days)
### Performance Improvements
The Calendar View uses virtual scrolling to maintain performance when displaying large numbers of events. This allows the calendar to handle extensive task lists and long time ranges without degradation in responsiveness.
### Custom Days View
@ -37,7 +71,7 @@ The Custom Days view is particularly useful for:
### Recurring Task Support
The Advanced Calendar provides sophisticated recurring task management with visual hierarchy and intelligent drag-and-drop behavior.
The Calendar View provides recurring task management with visual hierarchy and drag-and-drop behavior.
#### Visual Hierarchy
@ -76,7 +110,7 @@ This flexibility allows for complete control over both the recurring pattern and
### View Options
The Advanced Calendar provides several display options that control what types of events appear on the calendar:
The Calendar View provides several display options that control what types of events appear on the calendar:
- **Show scheduled**: Display tasks with scheduled dates
- **Show due**: Display tasks with due dates
@ -90,6 +124,39 @@ The **All-day slot** option is particularly useful when you have many all-day ta
These display options are preserved when you save a view, allowing you to create specialized calendar views that show only specific types of events and maintain those preferences across sessions.
### FilterBar Integration
### OAuth Calendar Integration
The Advanced Calendar View includes the same FilterBar functionality as the Task List View, allowing you to filter which tasks appear on the calendar and save views. See the [Task List View](task-list.md) documentation for complete FilterBar functionality details.
The Calendar View supports bidirectional synchronization with external calendar services through OAuth authentication:
- **Google Calendar**: Connect to Google Calendar accounts to display and sync events
- **Microsoft Outlook**: Connect to Microsoft Outlook accounts for calendar integration
#### Synchronization Behavior
- External calendar events appear alongside TaskNotes tasks in all calendar views
- Drag and drop events to reschedule them - changes sync back to the external calendar service
- Events from external calendars respect the same view options and display settings as native TaskNotes tasks
#### Configuration
OAuth calendar connections are configured through the TaskNotes settings panel. Authentication uses standard OAuth flows to securely connect to external services.
### Time Entry Editor Modal
The Calendar View includes a Time Entry Editor Modal for creating time tracking entries directly from the calendar interface.
#### Creating Time Entries
- Drag on the calendar to select a time range
- When the selection menu appears, choose **Create time entry**
- The modal opens with the start and end times pre-populated based on the selection, and the entry can be linked to a task or left standalone
#### Editing Time Entries
Time entries displayed on the calendar can be selected to open the Time Entry Editor Modal for modification. The modal provides fields for adjusting start time, end time, associated task, and other time entry metadata.
### Filtering and View Configuration
Calendar filtering is configured through the Bases YAML frontmatter in the `.base` file. This allows you to define which tasks and events appear in each calendar view. Filtering options include task properties, date ranges, tags, and other criteria supported by the Bases plugin.
Saved calendar views retain their filter configuration, display options, and view mode, allowing you to create specialized calendar views for different purposes.

104
docs/views/kanban-view.md
View file

@ -1,18 +1,110 @@
# Kanban View
The Kanban View displays tasks as cards in columns, where each column represents a different status. This provides a visual way to manage your workflow.
[← Back to Views](../views.md)
## FilterBar Integration
The Kanban View displays tasks as cards organized in columns, where each column represents a distinct value of a grouped property. This view operates within Obsidian's Bases core plugin.
The Kanban View includes the same FilterBar functionality as the Task List View, allowing you to filter, sort, and save views of your tasks. See the [Task List View](task-list.md) documentation for complete FilterBar functionality details.
## Bases Architecture
The Kanban view functions as a Bases view type. It reads data from `.base` files located in your vault's `TaskNotes/Views/` directory. These files contain YAML frontmatter that defines the view configuration, including data source, filtering, sorting, and Kanban-specific options.
Note: The Task List view includes “Collapse/Expand All” buttons for grouped lists. In Kanban, columns act as groups and are not collapsible yet, so these buttons are hidden in Kanban until they provide a function.
### Requirements
- Obsidian 1.10.1 or later
- Bases core plugin enabled
- A `groupBy` property configured in the view settings
The `groupBy` property determines the column structure. Each unique value of this property becomes a column in the Kanban board.
## Configuration
Kanban views are configured through the Bases interface. Open a `.base` file and access the view settings panel to configure options.
### Core Settings (Bases)
- **Data source**: Select which files or folders to include in the view
- **Filter**: Define criteria to include or exclude specific tasks
- **Sort**: Specify the order of tasks within each column
- **Group by**: Required. Defines the property that creates columns (e.g., status, priority)
### Kanban-Specific Options
Access these options through the Bases view settings panel:
- **Swim Lane**: Optional property for horizontal grouping. Creates a two-dimensional layout where tasks are organized by both column (groupBy) and row (swimLane)
- **Column Width**: Controls the width of columns in pixels. Range: 200-500px. Default: 280px
- **Hide Empty Columns**: When enabled, columns containing no tasks are hidden from the view
- **Column Order**: Managed automatically when dragging column headers. Stores custom column ordering
## Interface Layout
The Kanban View consists of a set of columns, each corresponding to a status in your configured workflow. Tasks are displayed as cards within the appropriate column. You can move tasks between columns by dragging and dropping them, which will automatically update the task's status.
### Standard Layout
In standard mode, the Kanban board displays a horizontal row of columns. Each column corresponds to a unique value of the `groupBy` property.
Each column includes:
- A header showing the property value and task count
- A scrollable area containing task cards
- Drag-and-drop functionality for reordering columns or moving tasks between columns
### Swimlane Layout
When a `swimLane` property is configured, the board displays a grid layout. The horizontal axis represents columns (groupBy values), and the vertical axis represents swimlanes.
Each swimlane row includes:
- A label cell showing the swimlane property value and total task count
- Multiple cells, each representing a column within that swimlane
- Scrollable cells containing task cards
## Task Cards
Each task card displays key information about the task, such as its title, priority, and due date. You can click on a card to open the task for editing, or you can use the context menu to perform a variety of actions.
Each task card displays information based on the visible properties configured in the Bases view. Standard task information includes title, priority, due date, and scheduled date.
Click a card to open the task file for editing. Right-click to access the context menu for task actions. Drag cards between columns or swimlane cells to update the task's properties.
## Column Operations
### Reordering Columns
Drag column headers to reorder columns. The new order persists across sessions and is stored in the `columnOrder` configuration.
### Drag-and-Drop Tasks
Drag task cards between columns to update the `groupBy` property value. In swimlane mode, dragging a task to a different cell updates both the `groupBy` and `swimLane` properties.
## Performance Optimization
The Kanban view implements virtual scrolling for columns or swimlane cells containing 30 or more tasks. This optimization reduces memory usage by approximately 85% and maintains 60fps scrolling performance for columns with 200+ tasks.
Virtual scrolling activates automatically based on task count. No configuration is required.
## Example Configuration
A typical Kanban view `.base` file includes:
```yaml
---
type: query
source: TaskNotes
view: TaskNotes Kanban
views:
- name: TaskNotes Kanban
type: tasknotesKanban
groupBy:
property: task.status
config:
swimLane: task.priority
columnWidth: 300
hideEmptyColumns: true
---
```
This configuration creates a Kanban board with:
- Columns based on task status
- Swimlanes based on task priority
- 300px column width
- Empty columns hidden
## Filtering and Sorting
Filtering and sorting are configured through the Bases view settings, not through a separate FilterBar component. Use the Bases filter editor to define conditions based on task properties. Use the Bases sort editor to specify the order of tasks within each column.

309
docs/views/task-list.md
View file

@ -1,165 +1,256 @@
# Task List View
The Task List View provides a list-based interface for viewing and managing your tasks. It displays your tasks in a scrollable list, with filtering, sorting, and grouping capabilities.
[← Back to Views](../views.md)
## FilterBar
The Task List View displays tasks in a scrollable list format with filtering, sorting, and grouping capabilities. In TaskNotes v4, this view operates as a Bases view configured through YAML.
The Task List View includes a FilterBar that provides comprehensive filtering capabilities through a hierarchical query builder interface.
## Bases Architecture
### Quick Search
Task List is implemented as a `.base` file located in `TaskNotes/Views/tasks-default.base` by default. It requires the Bases core plugin to be enabled.
The search input at the top of the FilterBar allows for quick text searches:
- Searches task titles for matching text
- Updates in real-time with 800ms debouncing
- Search terms are added as filter conditions in the query builder
### What is Bases?
### Query Builder
Bases is an official Obsidian core plugin built directly into Obsidian (not a community plugin). It provides a framework for creating database views of notes and tasks.
The FilterBar includes a hierarchical query builder that allows you to create complex filter conditions:
To enable Bases:
1. Open Settings → Core Plugins
2. Enable "Bases"
3. TaskNotes view commands will now open `.base` files from `TaskNotes/Views/`
**Filter Groups**: Logical containers that can use AND or OR conjunctions
### View File Location
- Groups can contain individual conditions or nested groups
- Visual nesting shows the hierarchy
- Each group can have its own conjunction (AND/OR)
When you use the "Open Tasks View" command or ribbon icon, TaskNotes opens the `.base` file configured under **Settings → TaskNotes → General → View Commands** (initially `TaskNotes/Views/tasks-default.base`). The default file is created automatically the first time you use the command, and you can point the command to any other `.base` file if you maintain multiple task-list layouts.
**Filter Conditions**: Individual filter rules with three parts:
## Configuration
- **Property**: What task attribute to filter on
- **Operator**: How to compare the property
- **Value**: What to compare against
Task List views are configured through YAML frontmatter in the `.base` file. The YAML defines which tasks to show, how to sort them, and how to group them.
### Available Properties
### Basic Structure
You can filter on these task properties:
```yaml
# All Tasks
**Text Properties**:
views:
- type: tasknotesTaskList
name: "All Tasks"
order:
- note.status
- note.priority
- note.due
- note.scheduled
- note.projects
- note.contexts
- file.tags
sort:
- column: due
direction: ASC
```
- `title` - Task title/name
### Configuration Options
**Select Properties**:
- `status` - Task status
- `priority` - Priority level
- `tags` - Task tags
- `contexts` - Task contexts
- `projects` - Task projects (supports wiki-link format)
**`type`**: Must be `tasknotesTaskList` for Task List views
**Date Properties**:
- `due` - Due date
- `scheduled` - Scheduled date
- `completedDate` - Completion date
- `file.ctime` - File creation date
- `file.mtime` - File modification date
**`name`**: Display name shown in the view header
**Boolean Properties**:
- `archived` - Whether task is archived
- `status.isCompleted` - Whether task status indicates completion
**`order`**: Array of property names that control which task properties are visible in the task cards. Properties are referenced using their Bases property paths (e.g., `note.status`, `note.priority`, `note.due`).
**Numeric Properties**:
- `timeEstimate` - Time estimate in minutes
**`sort`**: Array of sort criteria. Tasks are sorted by the first criterion, with ties broken by subsequent criteria.
- `column`: Property to sort by (e.g., `due`, `scheduled`, `priority`, `title`)
- `direction`: `ASC` (ascending) or `DESC` (descending)
**Special Properties**:
- `recurrence` - Recurrence pattern
**`groupBy`**: Optional grouping configuration
- `property`: Property to group by (e.g., `note.status`, `note.priority`)
- `direction`: Sort direction for group headers
### Available Operators
**`filters`**: Optional filter conditions using Bases query syntax
```yaml
filters:
and:
- note.status == "Open"
- note.priority == "High"
```
**Text Operators**:
- `contains` / `does-not-contain` - Substring matching (case-insensitive)
### Property Mapping
**Comparison Operators**:
- `is` / `is-not` - Exact equality/inequality
- `is-greater-than` / `is-less-than` - Numeric comparison
TaskNotes properties are accessed in Bases YAML using these paths:
**Date Operators**:
- `is-before` / `is-after` - Date comparison
- `is-on-or-before` / `is-on-or-after` - Inclusive date comparison
| TaskNotes Property | Bases Property Path | Description |
|-------------------|-------------------|-------------|
| Status | `note.status` | Task status value |
| Priority | `note.priority` | Priority level |
| Due date | `note.due` | Due date/time |
| Scheduled date | `note.scheduled` | Scheduled date/time |
| Projects | `note.projects` | Associated projects |
| Contexts | `note.contexts` | Task contexts |
| Tags | `file.tags` | File tags |
| Time estimate | `note.timeEstimate` | Estimated duration |
| Recurrence | `note.recurrence` | Recurrence pattern |
| Blocked by | `note.blockedBy` | Blocking dependencies |
| Title | `file.name` | Task title (file name) |
| Created | `file.ctime` | File creation date |
| Modified | `file.mtime` | File modification date |
**Existence Operators**:
- `is-empty` / `is-not-empty` - Checks for empty/null values
- `is-checked` / `is-not-checked` - Boolean true/false
The exact property names depend on your TaskNotes field mapping settings (Settings → Advanced → Field Mapping). The table above shows the default mappings.
### Saved Views
## Filtering and Sorting
The FilterBar supports saving and loading filter configurations:
- **Save**: Name and save current filter, sort, and group settings
- **Load**: Apply a previously saved view configuration
- **Delete**: Remove saved views
- Saved views include the complete filter hierarchy, sorting, and grouping preferences
### Adding Filters
Edit the `.base` file to add filter conditions using Bases query syntax:
### Heading display and completion count
```yaml
views:
- type: tasknotesTaskList
name: "High Priority Tasks"
filters:
and:
- note.priority == "High"
- note.status != "Completed"
order:
- note.status
- note.priority
- note.due
```
The Task List heading shows the active saved view name and the current task count (completed / total).
### Filter Operators
- No filter selected (shows “All”):
Bases supports standard comparison operators:
- `==` (equals), `!=` (not equals)
- `>`, `<`, `>=`, `<=` (comparison)
- `contains()` (substring/array membership)
- Boolean logic: `and`, `or`
![Saved view heading with count (no filter)](../assets/tasklist_filter_name+count_no_filter.png)
For detailed filter syntax, see the [Bases documentation](https://help.obsidian.md/Plugins/Bases).
- Saved view selected:
### Sorting Examples
![Saved view heading with count (with filter)](../assets/tasklist_filter_name+count_with_filter.png)
Single sort criterion:
```yaml
sort:
- column: due
direction: ASC
```
### Sorting Options
Multiple sort criteria:
```yaml
sort:
- column: priority
direction: DESC
- column: due
direction: ASC
- column: title
direction: ASC
```
Available sort criteria:
- `due` - Due date
- `scheduled` - Scheduled date
- `priority` - Priority level (by weight)
- `title` - Alphabetical
- User fields (from Settings → Advanced → User Fields), shown by their Display Name
## Grouping
When primary sort criteria are equal, tasks are sorted by: scheduled → due → priority → title
Groups organize tasks under collapsible headers based on a property value.
### Grouping Options
### Enable Grouping
Available grouping options:
- `none` - No grouping
- `status` - By task status
- `priority` - By priority level
- `context` - By first context
- `project` - By project (tasks can appear in multiple groups)
- `due` - By due date ranges (Today, Tomorrow, This week, etc.)
- `scheduled` - By scheduled date ranges
Add `groupBy` configuration to your view:
Note: When Group by equals the Sort user field, group headers follow the selected sort direction.
```yaml
views:
- type: tasknotesTaskList
name: "Tasks by Status"
groupBy:
property: note.status
direction: ASC
order:
- note.status
- note.priority
- note.due
```
#### Hierarchical Subgrouping
### Available Grouping Properties
The Task List View supports two-level hierarchical grouping for enhanced organization:
Common grouping properties:
- `note.status` - Group by task status
- `note.priority` - Group by priority level
- `note.contexts` - Group by first context
- `note.projects` - Group by project (tasks can appear in multiple groups)
1. **Enable Primary Grouping**: Choose any grouping option (e.g., "Status")
2. **Add Subgrouping**: Use the sort/group menu (⋯ button) to select a subgroup option
3. **View Structure**: Tasks appear under primary groups, then organized into subgroups
### Interactive Group Headers
**Example**: Group by "Status" with "Priority" subgroups creates:
- **Open** (primary group)
- High priority (subgroup)
- Medium priority (subgroup)
- Low priority (subgroup)
- **In Progress** (primary group)
- High priority (subgroup)
- etc.
Group headers support interaction:
- Click to expand/collapse the group
- Click on project links in headers to navigate to project notes
- Hover over project links with Ctrl to preview project notes
Subgroup state (expanded/collapsed) is preserved between sessions, and subgroups are sorted according to the current sort direction.
### Collapsed State Persistence
### Project Group Headers
Collapsed/expanded state for each group is preserved across sessions.
When grouping tasks by project, the project group headers are interactive:
- **Clickable Navigation**: Project headers that are wikilinks (e.g., `[[Project Name]]`) can be clicked to open the corresponding project note
- **Hover Previews**: Use Ctrl+hover on project headers to preview project notes without opening them
- **Error Handling**: Clicking on project headers for missing files shows appropriate error messages
## Creating Multiple Views
You can create multiple `.base` files for different task perspectives:
### Group Controls: Expand/Collapse All
1. Duplicate an existing `.base` file in `TaskNotes/Views/`
2. Rename it (e.g., `High Priority.base`)
3. Edit the YAML configuration for that view
4. Open the file to see the customized view
When grouping is enabled, the FilterBar shows top‑bar controls to collapse or expand all groups at once. This helps quickly condense or expand long lists.
### Example: Context-Specific View
- Collapse All: hides the contents of every group
- Expand All: reveals the contents of every group
- The collapsed state is remembered per grouping key for the current view
```yaml
# Work Tasks
![Expand/Collapse All demo](../assets/collapse-expand-all-buttons.gif)
views:
- type: tasknotesTaskList
name: "Work Context"
filters:
and:
- note.contexts.contains("work")
groupBy:
property: note.priority
direction: DESC
order:
- note.status
- note.priority
- note.due
```
## Migrating from v3 Saved Views
TaskNotes v3 stored filter configurations in plugin settings. These saved views are **not automatically migrated** to v4.
To recreate a v3 saved view:
1. Create a new `.base` file in `TaskNotes/Views/`
2. Translate your v3 filter conditions to Bases YAML syntax
3. Configure sorting and grouping through YAML
4. Save the file
The v3 FilterBar UI component no longer exists - all configuration is done through YAML editing.
## Task Actions
The Task List View provides a variety of ways to interact with your tasks. You can click on a task to open it for editing, or you can use the context menu to perform a variety of actions, such as marking the task as complete, changing its priority, or deleting it.
The Task List View provides interaction with tasks through clicking and context menus:
- **Click on a task**: Opens the task for editing or navigates to the task note (behavior configured in Settings → General → Click Actions)
- **Right-click on a task**: Opens a context menu with actions:
- Mark as complete
- Change priority
- Change status
- Edit dates
- Delete task
- And more
Context menu availability depends on your TaskNotes settings and task properties.
## Virtual Scrolling
The Task List View automatically enables virtual scrolling when displaying 100 or more items (tasks + group headers). Virtual scrolling provides:
- Approximately 90% memory reduction for large lists
- Elimination of UI lag when scrolling through hundreds of tasks
- Smooth performance with unlimited task counts
Virtual scrolling activates automatically and requires no configuration. When active, only visible tasks are rendered to the DOM, with off-screen tasks rendered on-demand as you scroll.
## Further Reading
- [Bases Plugin Documentation](https://help.obsidian.md/Plugins/Bases) - Official Obsidian documentation for Bases syntax and features
- [Kanban View](kanban-view.md) - Alternative board-based task visualization
- [Calendar Views](calendar-views.md) - Time-based task visualization
- [Views Overview](../views.md) - All available TaskNotes views

17
docs/workflows.md
View file

@ -98,7 +98,7 @@ Habit that recurs every 3 days, suitable for activities that don't require daily
#### Calendar Views
- **Advanced Calendar View**: Shows all habit instances as events across monthly/weekly/daily views
- **Calendar View**: Shows all habit instances as events across monthly/weekly/daily views
- **Agenda View**: Lists upcoming habit instances chronologically
- **Filter options**: Use the "Show Recurrent" filter to display only recurring tasks
@ -216,12 +216,12 @@ Tasks can be assigned to multiple projects:
#### Filtering by Projects
Use the FilterBar to show only tasks from specific projects:
Use the Bases filter editor (available in every Task List/Kanban `.base` view) to target a project:
1. Open the advanced filters panel
2. Select one or more projects from the checkbox list
3. Tasks are filtered in real-time to show only selected projects
4. Combine project filters with status, priority, and date filters
1. Open the Task List view and click the filter icon in the header
2. Add a condition such as `note.projects contains [[Project Name]]`
3. Combine the condition with status, priority, or date filters as needed
4. Save the configuration as a Bases saved view if you need to reuse it later
#### Grouping Tasks by Project
@ -266,9 +266,9 @@ Projects are included in search functionality:
1. **Filter by Current Project**:
- Use FilterBar to show only current project tasks
- Open the Bases filter editor and add a `note.projects contains` condition for the project you are working on
- Focus on specific project work without distractions
- Switch between projects using saved filter presets
- Switch between projects by toggling between Bases saved views or adjusting the filter
2. **Project Progress Tracking**:
@ -319,4 +319,3 @@ Use tags for cross-cutting themes that span multiple projects.
- Project filtering uses exact name matching (case-sensitive)
- Tasks with multiple projects appear in all relevant filtered views
- Project links in task displays open the referenced notes when clicked