Getting Started - Tasks User Guide

# Getting Started ## Finding tasks in your vault 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: ```text - [ ] take out the trash ``` Now Tasks tracks that you need to take out the trash! > [!Info] > You can write tasks using any of the following list styles: > > ```text > - [ ] task starting with a hyphen > > * [ ] task starting with an asterisk > > + [ ] task starting with a plus sign > > 1. [ ] a task in a numbered list with a `.` character > > 2) [ ] a task in a numbered list with a `)` character > ``` > [!released] > > - Support for tasks with `+` was introduced in Tasks 4.5.0. > - Support for numbered lists with `)` was introduced in Tasks 7.18.5. To list all open tasks in a markdown file, simply add a [[About Queries|query]] as a tasks code block like so: ````markdown ```tasks not done ``` ```` ## Adding data to your tasks (optionally) Now you have a list of all open tasks! This is enough to get started with tasks. You can _optionally_ start using one or more of the other features that Tasks offers. Like, for example, [[Priority|priorities]] or [[Dates#Start date|dates]]. This Tasks User Guide almost entirely uses Emoji to add data to your tasks. However, if you prefer to use text instead of Emoji, see [[About Task Formats]] for other options. ## Easy editing of tasks 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. You can find out more in [[Create or edit Task|‘Create or edit Task’ Modal]]. See other pages in 'Getting Started' for more details on due dates and recurrence, and many other features. You cannot toggle a task (un)done in the modal. For that, do one of the following. ## Completing tasks There are two ways to mark a task done: 1. In preview mode, click the checkbox at the beginning of the task to toggle the status between "todo" and "done". 2. 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 the 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. ## Limitations and warnings ### Restart after updating Tasks plugin > [!warning] > Whenever Tasks behaves in an unexpected way, **please try restarting Obsidian**. ### Multi-line checklist items > [!warning] > Tasks only supports **single-line checklist items**. The task list rendered through this plugin **and** the checklist items from which the task list is built render only the first line of the item. Text after the first line in a multi-line checklist item is ignored (but is unaffected in the stored `.md` file). This works: ```markdown - [ ] This is a task - This is a sub-item - Another sub-item - [ ] And a sub task - Even more details ``` The following _does not work:_ ```markdown - [ ] This task starts on this line and then its description continues on the next line ``` We are tracking this in [issue #2061](https://github.com/obsidian-tasks-group/obsidian-tasks/issues/2061). ### Tasks in Numbered lists Tasks can read tasks that are in **numbered lists**. > [!released] > > - Reading tasks inside numbered lists was introduced in Tasks 1.20.0. > - Reading tasks inside numbered lists with `)` was introduced in Tasks 7.18.5. For example: ```markdown 1. [ ] Do first step 2. [ ] Do next step 3. [ ] Do following step ``` or: ```markdown 1) [ ] Do first step 2) [ ] Do next step 3) [ ] Do following step ``` Editing and toggling tasks in numbered lists works fine: the original number is preserved. > [!warning] > However, when these tasks are displayed in tasks blocks they are displayed as ordinary bullet list items. > > This is because they will usually be displayed in a completely different order than in the original list, often mixed in with tasks from bullet lists. The original numbers in this case just don't make sense. ### Tasks in Blockquotes and Callouts  > [!Warning] Warning: Obsidian bug in versions 1.6.0 to 1.6.3 has caused some tasks not to be found > See [[Missing tasks in callouts with some Obsidian 1.6.x versions]] for how to ==make Obsidian 1.6.5 fix its metadata cache==, in case it was broken by earlier 1.6.x versions.  Tasks can read tasks that are inside [blockquotes](https://www.markdownguide.org/basic-syntax/#blockquotes-1) or [Obsidian's built-in callouts](https://help.obsidian.md/How+to/Use+callouts). > [!released] Reading tasks inside callouts and blockquotes was introduced in Tasks 1.11.1 > [!warning] > However, under the following very specific circumstance, Tasks cannot add or remove completion dates or make the next copy of a recurring task: > > - Obsidian is in **Live Preview** editor mode (pencil icon in lower right corner), > - AND the task's markdown is in a **callout**, > - AND the user **clicked on the task's checkbox** to complete or re-open the task. If you toggle a task's status in this situation, you will see a warning. Use the command `Tasks: Toggle Done`, or switch to Reading View (book icon in lower right corner) to click the checkbox. Since Tasks X.Y.X, it is possible to disable this warning message. Completing a task by clicking its checkbox from a `tasks` query block _will_ work in any editor mode, even if the query is inside a callout. We are tracking this in [issue #1768](https://github.com/obsidian-tasks-group/obsidian-tasks/issues/1768), but note that the cause is that Obsidian does not provide the line number to indicate which task was clicked on. So this could only be fixed if Obsidian's handling of events in callouts in Live Preview was ever improved. > [!warning] > When tasks are in callouts, any preceding heading in the callout is not read by Tasks, so `group by heading` uses the previous heading outside the callout - or `(No Heading)` if none. We are tracking this in [issue #1989](https://github.com/obsidian-tasks-group/obsidian-tasks/issues/1989). ### Tasks in Canvas > [!warning] > Tasks cannot read tasks that are in **Obsidian Canvas cards**. We are tracking this in [issue #2100](https://github.com/obsidian-tasks-group/obsidian-tasks/issues/2100). ### Tasks in Code Blocks > [!warning] > Tasks cannot read tasks that are **inside code blocks**, such as the ones used by the **Admonitions plugin**. Use Obsidian's built-in callouts instead. ### Tasks in Comments Obsidian supports two styles of **comments**: - `` - `%% I am text in a comment %%` > [!warning] > By design, Tasks does **not** read any tasks that are inside these comments, because Obsidian does not read them. ### Tasks with Footnotes > [!warning] > Tasks can only render **inline footnotes**. Regular footnotes are not supported. ```markdown - [ ] This is a task^[with a working inline footnote] - [ ] This footnote _will not work_[^notworking] ``` See also [[About Queries#Footnotes are not displayed in query results]]. ### Tasks with Blockquotes > [!warning] > Tasks' support for **blockquotes inside tasks** is limited. It renders correctly, but since Tasks only supports a single line, the meta-data of the task will be inside the blockquote. ### Rendering tasks in 'loose' lists > [!warning] > Tasks won't render **spaces around list items** if you have a list with empty lines (typically known as ['loose' lists](https://spec.commonmark.org/0.30/#loose)). ```markdown - [ ] First task before the empty line - [ ] Another task. The empty line above will _not_ result in the tasks being more spaced out. ``` ### Order of metadata/emojis > [!warning] > Tasks reads task lines **backwards from the end of the line**, looking for metadata emojis with values, tags and block links. As soon as it finds a value that it does not recognise, it stops reading. This means that you can only put **block links** (`^link-name`) and **tags** after metadata such as dates, priorities, recurrence rules. Anything else will break the parsing of dates, priorities and recurrence rules. ```markdown - [ ] Task with priority placed before tag _priority will be recognized_ 🔼 #tag - [ ] Task with date placed before tag _date will be recognized_ 📅 2021-04-09 #tag - [ ] Task with date placed before other text _date will be not recognized_ 📅 2021-04-09 other text - [ ] Task with block link _works_ 📅 2021-04-09 ^e5bebf ``` We are tracking this in [issue #1505](https://github.com/obsidian-tasks-group/obsidian-tasks/issues/1505). If you are concerned that some values in a task are not being parsed as you intended, perhaps because a task is not being found by Tasks searches, you can: - view an individual task in the [[Create or edit Task|‘Create or edit Task’ Modal]] - search for all possible problems: see [[Find tasks with invalid data#Finding unread emojis|Finding unread emojis]]. If there are any **Tasks emojis visible in the Description field**, close the modal and delete or move to the left any unrecognised text. ![Create or Edit Modal](../images/modal-showing-unparsed-emoji.png) <br>The `Tasks: Create or edit` modal showing a due date that was not parsed, due to trailing `other text`. ### Supported file names > [!warning] > Tasks only supports checklist items in markdown files with the file extension `.md`.