PlainTasks

PlainTasks

An opinionated todo-list plugin for Sublime Text (2 & 3) editor

Installation

To install this plugin, you have two options:

1. If you have Package Control installed, simply search for PlainTasks to install.

2. Clone source code to Sublime Text packages folder.

Start a new todo-list

Bring up the command palette (it’s ⌘ + shift + p in OS X and ctrl + shift + p in Windows) and type task and select Tasks: New document command.

NOTE: Save your todo files with todo, todolist, tasks or taskpaper file extensions or just name them TODO with no extension. For more portability you can use todolist.txt either as a filename or as suffix for any arbitrary filename.

Usage

NOTE: In Windows or Linux use ctrl instead of ⌘

☐ ⌘ + enter or ⌘ + i: new task

☐ ⌘ + d: toggle task as completed.

☐ ctrl + c: toggle task as cancelled on Mac. alt + c on Windows/Linux.

☐ ⌘ + shift + a will archive the done tasks, by removing them from your list and appending them to the bottom of the file under Archive project

☐ ⌘ + shift + o will archive in Org-Mode style, removing the entire subtree after cursor and appending it to new file next to original one, e.g. if original is filename.TODO then new would be filename_archive.TODO

☐ ⌘ + shift + u will open the url under the cursor in your default browser, other than http(s) schemes must be enclosed within <>, e.g. <skype:nickname>

☐ Anything with colon at the end of the line is a project title, you can also nest projects by indenting them.

☐ You can write plain text as notes or descriptions wherever you want. Use _ or * for italic and bold just like in Markdown.

☐ You can add tags using @ sign
You can place cursors on tags, click right mouse button and Filter by tags under cursors: pending tasks with selected tags will remain visible (and their notes and projects they belong to), but everything else will be hidden/folded; to unfold all press ⌘+k, ⌘+j or ⌘+k, ⌘+0

☐ You can navigate tags in current document via ⌘+shift+r.

☐ PlainTasks comes with a simple snippet for creating separators, if you feel that your task list is becoming too long you can split it into several sections (and fold some of them) using this snippet:

-- and then tab will give you this: --- ✄ -----------------------

☐ Completion rules (ctrl+space or alt+/ to see list of them):

• type t, press tab — it’ll become @today — this one is highlighted differently than other tags;

• c, tab — @critical;

• h, tab — @high;

• l, tab — @low;

• s, tab — @started — press tab again and current date will be inserted, when you’ll complete or cancel a task with such tag, you’ll know how many time has passed since start; if you have to change done/cancelled/started time, then you can recalculate the time spent on task by pressing tab while cursor is placed on a tag;

• tg, tab, tab work in the same manner as s, but inserts @toggle(current date) — so you can pause and resume to get more correct result when done/cancel; each toggle tag is either pause or resume depending on its place in sequence;

• cr, tab, tab — @created(current date) (⌘ + shift + enter creates a new task with this tag);

• d, tab — @due( )
  If you press tab again, it’ll insert current date, same for @due( 0).
  You can type short date (similar to OrgMode’s date prompt, but not the same) and then press tab to expand it into default format.
  Short date should be @due(year-month-day hour:minute)
  Dot can be used instead of hyphen, but should be consistent year.month.day

  • year, month, minute, hour can be omitted:

  • relative period of time starts with a plus sign or two
    +[+][number][DdWw][h:m] — number is optional as well as letter d for days or letter w for weeks.

☐ You can create a link to a file within your project by prefixing the file name with a dot and (back)slash like: .\filename\ or ./another filename/.
The line and column can be specified by colons: .\filename:11:8.
In SublimeText 3 you can specify a symbol inside that file by using > character like: .\filename>symbol.
In SublimeText 2 you can specify a text inside that file by using inch characters like: .\filename"any text".
Pressing ctrl + o (alt + o on Windows/Linux) will open the file in Sublime and scroll to specific position if any.
Also in SublimeText 3 link may point to directory, open such link will add the directory to current project (sidebar).
In addition, Markdown and “wiki” (Org-Mode, NV, etc.) styles are supported as well, examples:

[](path)
[](path ":11:8")
[](path ">symbol")
[](path "any text")
[[path]]
[[path::11:8]]
[[path::*symbol]]
[[path::any text]]
[[path]] ":11:8"
[[path]] ">symbol"
[[path]] "any text"

☐ To convert current document to HTML, bring up the command palette ⌘ + shift + p and type Tasks: View as HTML — it will be opened in default webbrowser, so you can view and save it.
Tasks: Save as HTML… ask if you want to save and if yes, allow to choose directory and filename (but won’t open it in webbrowser).

Editor Useful Tools:

☐ Use ⌘ + control + up/down (ctrl + shift + up/down on Windows) to move tasks up and down.

☐ Use ⌘ + r to see a list of projects and quickly jump between them

★ See the Tutorial for more detailed information.

Settings

PlainTasks is an opinionated plugin, which means that it is highly configured to look in a specific way, but this does not mean that you can not customize it. If you feel that something does not look right and you want to change it, you can easily do it in your user settings file.

Go to Preferences → Package Settings → PlainTasks and open Settings - User, there you can override all the default settings, to get an idea you can take a look at Settings - Default.

Here is a list of PlainTasks’ specific settings:

Setting	Default	Options/Description
open_tasks_bullet	☐	- ❍ ❑ ■ □ ☐ ▪ ▫ – — ≡ → › [ ]
done_tasks_bullet	✔	✓ ☑ + [x]
cancelled_tasks_bullet	✘	x [-]
date_format	(%y-%m-%d %H:%M)	See strfti.me for quick reference; detailed documentation: ST2, ST3
done_tag	true	Determines whether done tasks should gain a @done tag or not
done_date	true	Determines whether done tasks should gain a date or not
before_tasks_bullet_margin	1	Determines the number of spaces (default indent) before the task bullet
project_tag	true	Postfix archived task with project tag, otherwise prefix
archive_name	Archive:	Make sure it is the unique project name within your todo files
new_on_top	true	How to sort archived tasks (done_tag=true and default date_format are required)
header_to_task	false	If true, a project title line will be converted to a task on the certain keystroke
decimal_minutes	false