Task management for the Obsidian knowledge base.
Track tasks across your entire vault. Query them and mark them as done wherever you want. Supports due dates, recurring tasks (repetition), done dates, sub-set of checklist items, and filtering.
You can toggle the task status in any view or query and it will update the source file.
Please submit bugs here: https://github.com/schemar/obsidian-tasks/issues
Please submit ideas here: https://github.com/schemar/obsidian-tasks/discussions/categories/ideas
Please ask for help here: https://github.com/schemar/obsidian-tasks/discussions/categories/q-a
For changes in each release, please check the releases page: https://github.com/schemar/obsidian-tasks/releases
- All screenshots assume the global filter
#task
which is not set by default (see also installation). - The theme is Obsidian Atom.
The
Important Project
note also has some tasks.
The
Tasks
note gathers all tasks from the vault and displays them using queries.
The
Tasks: Create or edit
command helps you when editing a task.
Follow the steps below to install Tasks.
- Search for "Tasks" in Obsidian's community plugins browser
- Enable the plugin in your Obsidian settings (find "Tasks" under "Community plugins").
- Check the settings. It makes sense to set the global filter early on (if you want one).
- Replace the "Toggle checklist status" hotkey with "Tasks: Toggle Done".
- I recommend you remove the original toggle hotkey and set the "Tasks" toggle to
Ctrl + Enter
(orCmd + Enter
on a mac).
- I recommend you remove the original toggle hotkey and set the "Tasks" toggle to
Tasks tracks your checklist items from your vault.
The simplest way to create a new task is to create a new checklist item.
The markdown syntax for checklist items is a list item that starts with spaced brackets: - [ ] take out the trash
.
Now Tasks tracks that you need to take out the trash!
This works:
- [ ] This is a task
- This is a sub-item
- Another sub-item
- [ ] And a sub task
- Even more details
The following does not work:
- [ ] This task starts on this line
and then its description continues on the next line
.md
A more convenient way to create a task is by using the Tasks: Create or edit
command from the command palette.
You can also bind a hotkey to the command.
The command will parse what's on the current line in your editor and pre-populate a modal.
In the modal, you can change the task's description, its due date, and a recurrence rule to have a repeating task.
See below for more details on due dates and recurrence.
You cannot toggle a task (un)done in the modal.
For that, do one of the following.
There are two ways to mark a task done:
- In preview mode, click the checkbox at the beginning of the task to toggle the status between "todo" and "done".
- In edit mode, use the command
Tasks: Toggle Done
.- The command will only be available if the cursor is on a line with a checklist item.
- You can map he command to a hotkey in order to quickly toggle statuses in the editor view (I recommend to replace the original "Toggle checklist status" with it).
- If the checklist item is not a task (e.g. due to a global filter), the command will toggle it like a regular checklist item.
A "done" task will have the date it was done appended to the end of its line.
For example: ✅ 2021-04-09
means the task was done on the 9th of April, 2021.
ℹ You can set a global filter in the settings so that Tasks only matches specific checklist items.
For example, you could set it to #tasks
to only track checklist items as task if they include the string #tasks
.
It doesn't have to be a tag. It can be any string.
Leave it empty to regard all checklist items as tasks.
Example with global filter #tasks
:
- [ ] #tasks take out the trash
If you don't have a global filter set, all regular checklist items work:
- [ ] take out the trash
Tasks can have due dates.
In order to specify the due date of a task, you must append the "due date signifier 📅" followed by the date it is due to the end of the task.
The date must be in the format YYYY-MM-DD
, meaning Year-Month-Day
with leading zeros.
For example: 📅 2021-04-09
means the task is due on the 9th of April, 2021.
- [ ] take out the trash 📅 2021-04-09
Instead of adding the emoji and the date manually, you can use the Tasks: Create or edit
command when creating or editing a task.
When you use the command, you can also set a due date like "Monday", "tomorrow", or "next week" and Tasks will automatically save the date in the correct format.
You can only put block links (^link-name
) behind the due/done dates. Anything else will break the parsing of dates and recurrence rules.
Tasks can be recurring.
In order to specify a recurrence rule of a task, you must append the "recurrence signifier 🔁" followed by the recurrence rule.
For example: 🔁 every weekday
means the task will repeat every week on Monday through Friday.
Every recurrence rule has to start with the word every
.
When you toggle the status of a recurring task to anything but "todo" (i.e. "done"), the orginal task that you wanted to toggle will be marked as done and get the done date appended to it, like any other task. In addition, a new task will be put one line above the original task. The new task will have the due date of the next occurrence after the due date of the original task.
Take as an example the following task:
- [ ] take out the trash 🔁 every Sunday 📅 2021-04-25
If you mark the above task "done" on Saturday, the 24th of April, the file will now look like this:
- [ ] take out the trash 🔁 every Sunday 📅 2021-05-02
- [x] take out the trash 🔁 every Sunday 📅 2021-04-25 ✅ 2021-04-24
For best compatibility, a recurring task should have a due date and the recurrence rule should appear before the due date of a task.
In the editor there is no direct feedback to whether your recurrence rule is valid.
You can validate that tasks understands your rule by using the Tasks: Crete or edit
command when creating or editing a task.
Examples of possible recurrence rules (mix and match as desired; these should be considered inspirational):
🔁 every weekday
(meaning every Mon - Fri)🔁 every week on Sunday
🔁 every 2 weeks
🔁 every 3 weeks on Friday
🔁 every 2 months
🔁 every month on the 1st
🔁 every 6 months on the 1st Wednesday
🔁 every January on the 15th
🔁 every year
You can list tasks from your entire vault by querying them using a tasks
code block. You can edit the tasks from the query results by clicking on the little pencil icon next to them.
Tasks are sorted by status, due date, and then path.
The simplest way to query tasks is this:
```tasks
```
In preview mode, this will list all tasks from your vault, regardless of their properties like status. This is probably not what you want. Therefore, Tasks allows you to filter the tasks that you want to show.
The following filters exist:
done
not done
done (before|after|on) <date>
no due date
due (before|after|on) <date>
is recurring
is not recurring
path (includes|does not include) <path>
description (includes|does not include) <string>
- Matches case-insensitive (disregards capitalization).
heading (includes|does not include) <string>
- Whether or not the heading preceding the task includes the given string.
- Always tries to match the closest heading above the task, regardless of heading level.
- Will never match a task that does not have a preceding heading in its file.
- Matches case-insensitive (disregards capitalization).
exclude sub-items
- When this is set, the result list will only include tasks that are not indented in their file. It will only show tasks that are top level list items in their list.
limit to <number> tasks
- Only lists the first
<number>
tasks of the result. - Shorthand is
limit <number>
.
- Only lists the first
<date>
filters can be given in natural language or in formal notation.
The following are some examples of valid <date>
filters as inspiration:
2021-05-05
today
tomorrow
next monday
last friday
in two weeks
Note that if it is Wednesday and you write tuesday
, Tasks assumes you mean "yesterday", as that is the closest Tuesday.
Use next tuesday
instead if you mean "next tuesday".
When the day changes, relative dates like due today
are re-evaluated so that the list stays up-to-date.
All filters of a query have to match in order for a task to be listed. This means you cannot show tasks that have "GitHub in the path and have no due date or are due after 2021-04-04". Instead you would have two queries, one for each condition:
### Not due
```tasks
no due date
path includes GitHub
```
### Due after 2021-04-04
```tasks
due after 2021-04-04
path includes GitHub
```
You can hide certain elements of the rendered list with the "hide" option.
The following options exist:
edit button
backlink
done date
due date
recurrence rule
task count
Example:
```tasks
no due date
path includes GitHub
hide recurrence rule
hide task count
hide backlink
```
All open tasks that are due today:
```tasks
not done
due today
```
All open tasks that are due within the next two weeks, but are not overdue (due today or later):
```tasks
not done
due after yesterday
due before in two weeks
```
All done tasks that are anywhere in the vault under a tasks
heading (e.g. ## Tasks
):
```tasks
done
heading includes tasks
```
Show all tasks that aren't done, are due on the 9th of April 2021, and where the path includes GitHub
:
```tasks
not done
due on 2021-04-09
path includes GitHub
````
Show all open tasks that are due within two weeks and hide the due date and edit button:
```tasks
not done
due after 2021-04-30
due before 2021-05-15
hide due date
hide edit button
```
Show all tasks that were done before the 1st of December 2020:
```tasks
done before 2020-12-01
```
Show one task that is due on the 5th of May and includes #prio1
in its description:
```tasks
not done
due on 2021-05-05
description includes #prio1
limit to 1 tasks
````
If you use the calendar plugin,
you can use the following in your daily note template for an agenda. If you use this
template, you have to create the daily note from within the calendar in order for it to
work. If you don't create the daily note from the calendar, {{date+14d:YYYY-MM-DD}}
won't be set to the date correctly.
## Tasks
### Overdue
```tasks
not done
due before {{date:YYYY-MM-DD}}
```
### Due today
```tasks
not done
due on {{date:YYYY-MM-DD}}
```
### Due in the next two weeks
```tasks
not done
due after {{date:YYYY-MM-DD}}
due before {{date+14d:YYYY-MM-DD}}
```
### No due date
```tasks
not done
no due date
```
### Done today
```tasks
done on {{date:YYYY-MM-DD}}
```
Clone the repository, run yarn
to install the dependencies, and run yarn dev
to compile the plugin and watch file changes.
The plugin is completely free to use. If you love it very much and want to pay it forward, please consider donating to an organization of your choice. Two example organizations that you could consider donating to are the Wikimedia Foundation and the Electronic Frontiers Foundation: