Home

Awesome

PlainTasks

Codacy Badge

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 <kbd>⌘ + shift + p</kbd> in OS X and <kbd>ctrl + shift + p</kbd> 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 <kbd>ctrl</kbd> instead of <kbd></kbd>

<kbd>⌘ + enter</kbd> or <kbd>⌘ + i</kbd>: new task

<kbd>⌘ + d</kbd>: toggle task as completed.

<kbd>ctrl + c</kbd>: toggle task as cancelled on Mac. <kbd>alt + c</kbd> on Windows/Linux.

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

<kbd>⌘ + shift + o</kbd> 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

<kbd>⌘ + shift + u</kbd> 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 <kbd>⌘+k</kbd>, <kbd>⌘+j</kbd> or <kbd>⌘+k</kbd>, <kbd>⌘+0</kbd>

☐ You can navigate tags in current document via <kbd>⌘+shift+r</kbd>.

☐ 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 <kbd>tab</kbd> will give you this: --- ✄ -----------------------

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

☐ 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 <kbd>ctrl + o</kbd> (<kbd>alt + o</kbd> 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 <kbd>⌘ + shift + p</kbd> 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 <kbd>⌘ + control + up/down</kbd> (<kbd>ctrl + shift + up/down</kbd> on Windows) to move tasks up and down.

☐ Use <kbd>⌘ + r</kbd> 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:

SettingDefaultOptions/Description
open_tasks_bullet- [ ]
done_tasks_bullet + [x]
cancelled_tasks_bulletx [-]
date_format(%y-%m-%d %H:%M)See strfti.me for quick reference; detailed documentation: ST2, ST3
done_tagtrueDetermines whether done tasks should gain a @done tag or not
done_datetrueDetermines whether done tasks should gain a date or not
before_tasks_bullet_margin1Determines the number of spaces (default indent) before the task bullet
project_tagtruePostfix archived task with project tag, otherwise prefix
archive_nameArchive:Make sure it is the unique project name within your todo files
new_on_toptrueHow to sort archived tasks (done_tag=true and default date_format are required)
header_to_taskfalseIf true, a project title line will be converted to a task on the certain keystroke
decimal_minutesfalseIf true, minutes in lasted/wasted tags will be percent of hour, e.g. 1.50 instead of 1:30
tasks_bullet_spacewhitespace or tabString to place after bullet, might be any character(s)
highlight_past_duetrueIf true, highlight past, soon, and invalid @due(something)
highlight_due_soon24Hours as int, threshold to define which @due will be soon
scope_past_duestring.other.tag.todo.criticalAny scope, define color for past @due
scope_due_soonstring.other.tag.todo.highAny scope, define color for @due will be soon
scope_misformattedstring.other.tag.todo.lowAny scope, define color for @due mismatch date_format
icon_past_due"circle"Gutter icon¹
icon_due_soon"dot"Gutter icon¹
icon_misformatted""Gutter icon¹
icon_critical""Gutter icon¹
icon_high""Gutter icon¹
icon_low""Gutter icon¹
icon_today""Gutter icon¹
show_remain_duefalseIn Sublime 3, show remain or overdue time under due tags
show_calendar_on_tagsfalseIn Sublime 3, if true, automatically show date picker when cursor is on tag (you can get date picker any time via context menu)
due_preview_offset0Place preview date outside of parens of @due(), 1 — within
due_remain_format"{time} remaining"{time} will be replaced with actual value
due_overdue_format"{time} overdue"{time} will be replaced with actual value

<b>¹</b> Icon value can be "dot", "circle", "bookmark", "cross", "", or custom relative path to existing png file, e.g. "Packages/User/my-icon.png".

Changing color scheme

If you don't like colors used in bundled schemes just copy any .hidden-tmTheme from PlainTasks to your User directory, change colors and paste the code below in your user settings file:

{ "color_scheme": "Path to your custom color scheme file. e.g. Packages/User/custom_plaintasks.hidden-tmTheme" }

N.B., sometimes you have to restart Sublime Text to apply changes made in tmTheme file.

N.B., scope_past_due, scope_due_soon, and scope_misformatted settings can assign any scopes defined in tmTheme file, e.g. you can set "scope_past_due": "my.own.super.expired.whatever" and then just add style definition in tmTheme for this scope.

Taskpaper Compatibility

If you need to keep your files compatible with Taskpaper, go to Preferences → Package Settings → PlainTasks and open Settings - User, then add these settings to the json file:

{
  "translate_tabs_to_spaces": false,
  "date_format": "(%y-%m-%d)",
  "taskpaper_compatible": true
}

Spell check

It is build-in feature of Sublime, you can toggle spell check with <kbd>F6</kbd>.
For convinience, you may add bullets in list of ignored words into Preferences → Settings - User, e.g.

{
  "ignored_words": [ "☐", "✔", "✘", "✄" ]
}

[BONUS] Custom todo icon

PlainTasks comes with a custom todo icon that you can find in the icons folder. You can assign it to your todo files to give them a better look and distinguish them from other plain text files. Google and find out how to assign a custom icon to a file type in your operating system.

[BONUS] Custom Statistics

Statistics of current file are represented in status-bar, based on stats_format, which is "$n/$a done ($percent%) $progress Last task @done $last" by default — as you can see it’s just a string containing special directives (see table bellow) and regular chars.

DirectiveDescription
$oAmount of pending tasks
$dAmount of completed tasks
$cAmount of cancelled tasks
$nSum of completed and cancelled tasks
$aSum of all tasks
$percentRatio of $n to $a
$progressPercent as pseudo graphics (absents if less than 10%)
$lastDate of lastly completed task
{{...}}Return pending/completed/cancelled tasks which matched by regex ...;<br> e.g. {{@tag}} — amounts of tasks with @tag; or `{{@a

So you can customise it as you like, by adding to Settings - User, e.g.

{
    "stats_format": "☐$o ✔$d ✘$c",

    // if you want the statistics do not include the archived tasks:
    "stats_ignore_archive": true
}

Copy statistics

Bring up the command palette and type Tasks: Copy Statistics.

Additional settings for progress bar

{
    "bar_full": "■",   // any char
    "bar_empty": "☐", // any char

    // if you want to avoid Unicode when copy stats — you can define replacements
    // e.g. to convert ■■■■■■☐☐☐☐ to [======    ]
    "replace_stats_chars": [[" ■", " [="], ["■", "="], ["☐ ", " ] "], ["☐", " "]]
}

Introduction to PlainTasks Screencast

PlainTasks for other editors

NOTE: These are separate projects, maintained by some awesome developers other than us.

Contributors

You can contribute on github

Inspiration

License

Copyright 2012-2013 Allen Bargi. Licensed under the MIT License