Obsidian Tasks Documentation

Obsidian Tasks is a plugin for the Obsidian knowledge base that allows you to track tasks across your entire vault. It provides the ability to query tasks and mark them as done from any view or query, which automatically updates the original source file.

Key features include:

• Support for due dates and done dates.
• Recurring tasks (repetition).
• Filtering and querying capabilities.
• Support for a subset of checklist items.
• Ability to toggle task status directly within query results.

Once JavaScript is enabled, you can use JavaScript expressions within Tasks query blocks to extend the standard query language. The available scripting capabilities include:

• Custom Filters: Write short JavaScript expressions to create task search filters.
• Custom Sorting: Write short JavaScript expressions to sort tasks in query results.
• Custom Grouping: Write short JavaScript expressions to define task group names in query results.

Core statuses represent conventional markdown task syntax. They are natively supported in Tasks blocks and Live Preview without requiring custom CSS.

By default, the core statuses are:

• Todo: Represented by [ ] (a space after the bracket).
• Done: Represented by [x] (an x after the bracket).

These statuses can be used for filtering, sorting, and grouping in Tasks queries using status.name or status.type.

Obsidian Tasks recognizes several types of task statuses based on the character used in the markdown checkbox. These include standard Markdown statuses, core Tasks statuses, and custom statuses.

Standard Markdown statuses

• [ ]: Todo
• [x]: Done

Core Tasks statuses

• [ ]: Todo
• [x]: Done
• [/]: In Progress
• [-]: Cancelled

Custom Task statuses

You can use any character within the brackets to define custom statuses, such as:

• [X]: Checked
• [!]: Important
• [P]: Pro
• [C]: Con

The Getting Started documentation provides a roadmap for setting up and using the Obsidian Tasks plugin. Key areas covered include:

• Basics: Installation, initial setup, global filters, and plugin settings.
• Task Data: How to add dates, priorities, recurring rules, completion actions, custom statuses, and tags to your tasks.
• Advanced Features: Using task dependencies, querying Obsidian Properties, and searching based on note links.
• Editing: Techniques for easy task manipulation.

In Tasks, every task has a Status. A status is defined by the character (symbol) inside the brackets [] at the start of a task line and its associated configuration.

• Core Statuses: Standard markdown tasks using [ ] (not done) and [x] (done). These work out-of-the-box without extra styling.
• Custom Statuses: Non-standard characters (e.g., [-], [?], [/]). These require custom CSS or a theme to render correctly in Obsidian, but Tasks allows you to define their behavior (like what happens when they are toggled).
• Unknown Statuses: If Tasks encounters a symbol it doesn't recognize, it assigns it an Unknown status with a TODO type and sets the next status symbol to x.

Custom Statuses allow you to use non-standard markdown task characters between the brackets [ ]. This enables you to represent task states beyond simple completion (e.g., 'In Progress', 'Cancelled', or 'Question').

Examples of custom status syntax:

• - [X] Checked (Standard)
• - [-] A dropped/cancelled task
• - [?] A question
• - [/] A half done/in-progress task

Important: Custom statuses require custom CSS styling or a specific theme to display correctly in Tasks blocks or Obsidian's Live Preview. Without styling, they will appear as plain text characters within the brackets.

Tasks assembles a query by combining instructions from multiple sources in a specific order. Later instructions (like Layout) can override earlier ones. The assembly order is:

1. Global Query: Set in the plugin settings. This is discarded if ignore global query is present in any subsequent step.
2. Query File Defaults: Instructions defined in the note's frontmatter properties.
3. Query Source: The specific instructions written inside the tasks code block.

Note: Layout instructions applied at any stage can override previous settings.

Obsidian Tasks settings are organized by functional area. You can find detailed documentation for each setting category in the following sections:

• Task Formats: Selecting the task format.
• Global Filter: Settings for the Global Filter.
• Global Query: Settings for Global Queries.
• Status Settings: Overview of status configurations.
• Dates: Date-tracking settings.
• Use Filename as Default Date: Settings for using filenames as dates.
• Recurring Tasks: Recurrence settings.
• Auto-Suggest: Auto-suggest settings.
• Create or edit Task modal: Turning off keyboard shortcuts.
• Search results: Task count location settings.