TaskPaper 3.0 Preview (162)

  • Added option to choose file extension when saving.

  • Increased maximum size of the toolbar search field.

  • Added View > Zoom In and View > Zoom Out commands.

  • When moving by line included child items if the line is folded.

  • Fix exception when selecting all items and then shifting them left or right.

  • New project/task/note commands now work at all times, not only when text view has focus.

  • Printing now prints the current view state (focused project and folds) instead of the entire document.

  • Delete at start of item will un-indent it (same as Shift-Tab) when item is indented. When no longer indented will join with previous item.

  • Removed checkboxes in favor of more generic dashes before each tasks. This is a work in progress. I’m still hoping to bring the checkboxes back, but as an option.

  • Fixed search syntax to recognize ‘tomorrow’ as date keyword instead of misspelled ‘tommorrow’.

Theme System

This is a first pass. It’s quite possible that I’ll make breaking changes before 3.0.

To edit the theme used in TaskPaper 3:

  1. File > Open Application Folder.

  2. Open the file user.less in a text editor… ideally a programmers text editor that syntax highlights Less syntax.

  3. Make very small changes. And save often, TaskPaper themes are applied immediately when you save to the theme file, so if you make small changes and save often you should make good progress.


The theme file uses Less syntax, but ONLY syntax. The underlying theme model is much more limited then full HTML/DOM theming. I’m using Less/CSS syntax because it’s known and convenient, but I’m targeting my own view objects, not a generic HTML DOM. I’ve provided examples of most things that you can do in the user.less file, so examine that to see what’s possible. And of course let me know when you have questions.

Download TaskPaper 3 Preview


Can you provide some tips for making themes? I see that data-today is a special item type. How would we colorize lines and tags with custom @ tags? Are there other special item/data types for TaskPaper? Forgive my ignorance of LESS. I don’t work with it.

EDIT: Ok, I think I figured out you just put your tag string prefixed with data- like so for a tag @waiting

item[data-waiting] {

Might be a bug. I see when tags are repeated with different attributes the formatting seems to fail. See this screenshot with the @person tag.

Have you tried using the embedded syntax rather than two instances of the same tag, as in @person(bill, john) instead of @person(bill) @person(john)? The formatting was failing even before this update, when including two separate instances of the same tag on a single line, but not an issue if you use the comma syntax.

Now if you did want different attributes to be colored differently using a custom theme, you’d still be in trouble…

Not that I am a pro by any means, not by the longest of shots. But I did encounter this one (avoidable) bug.

That does not work with TaskPaper search syntax for attribute values. A search of @person=bill or @person=john would fail to find either attribute for your example.

This is actually intentional. The attributes map to a key-value store in each item, so there’s only a place to store the first key, otherwise the second would just overwrite.

Less can get pretty complicated and I think TaskPaper themes will be much smaller/simpler then general CSS styling because the target elements and attributes are so much more limited. But with that said Less gives me two things that make creating themes much easier I think.

  1. Unlike CSS it allows you to define @ variables, so I can define a color in one place and use it to style lots of different items.

  2. It allows you to fix two color variables into a third color with the mix function. So for instance if you change the tint-color to red it updates lots of related colors. A feature that’s nice when creating a theme and would be a pain to do in just strait CSS.

I think that covers most of my Less usage.

Hi Jesse,
playing with the theming :smile:

I’am I right padding is not supported?

run[tag=data-now] {    
color: white;   
background-color: red;   
padding-left: 5px;
padding-right: 5px;   


Hold up. Are you saying this single attribute/tag key value design is new in TP3? I’ve used this for ages and I believe it still is support in Taskmator which is based on the original TP for iOS. I no longer have the older version of TaskPaper for Mac installed so I can’t check there any longer.

What’s the recommendation for assigning resources to a TP3 task now?

I need to document the API of course… but matching attributes from styles rules to items I first check item.getAttribute and if that’s empty I also look for a build in property item[attributename] on the item. I think I’ve given examples of most of the useful one for styling in the user.less file.

depth is a calculated property case. data-type is a built in property set by the syntax highlighter. And I think most other useful things would just be user specified tags.

Hum… good question. I actually thought TaskPaper 2 worked this way… but I just checked and it supported your case. I think I must have moved to this dictionary based implementation when starting work on FoldingText many years back now… thought it was how I always did things.

Anyway the new behavior is very deep in the code, and makes it strait forward to map to more XML and JSON based formats. So that core aspect won’t change, but I think we can find a good way to support what you are trying to do. Three thoughts:

  1. If you won’t have namespace problems you could just @bill @john.

  2. As an alternative you could break namespace problems with something like @p-bill @p-john

  3. A more robust solution would are to use @person(bill, john). But right now that won’t generate the search that you want when clicking the tag values. If you need to find all “bill” you’ll need to search for @person contains bill or the shorter form @person bill.

I think probably 3 is the best solution, but it would work a lot better with better syntax support.

Correct… there’s no padding. The closest option would be to increase the line-height-multiple.

Thanks for the detailed reply. I understand.

My primary request would be to avoid breaking backward compatibility since many tools have been developed based on the older format. I know that’s tough when moving into a new era for TP and I don’t want to be narrow minded. I’d be concerned that many other users have used this approach in other ways. Fortunately for me, I use it for only @waiting and @person. I have seen people that use multiple @project tags with attributes to define tasks that happen to overlap with multiple projects.

For me, I always liked the @person(name) approach because it provided more context for the attribute. Whereas @bill could simply be a task related to paying bills. Additionally, @waiting tells me something about the name and why I care. I’m waiting on someone to do something before proceeding. Obviously there are other more verbose ways to handle this use case.

BTW, I’m definitely not implying that this is a huge problem. It’s mostly an edge case that would be solved by solution #3 above. But that’s a new spec that would not be supported outside of the Mac application.

In long lists I prefer paragraph-spacing for better clarity. In FoldingText I manage this with “margin-bottom: 0.5rem” (between items). Will this be possible with Taskpaper?

I assume this would be where to report bugs on the preview version.

For some reason, in the latest taskpaper list that I created today, when I click on items below the Home level, to focus the list just the items under that Project, the list only displays the Project heading, without the tasks that were displayed when I had the whole list displayed with all projects visible.

I’ve quit and restarted Taskpaper 3 preview and I’ve closed and opened the file in which this is happening. I’m not having this issue with other Taskpaper files open at the same time.

1 Like

I am loving being able to make small tweaks. The theming is relatively straightforward for me, a non-coder, to figure out. Thanks!

Realizing this was user error! I needed to move my tasks in a level so they were under the project rather than at the same level as the project.

FWIW I have often found this confusing and I guess I got confused all over again with the new Taskpaper display styles.

Thanks for adding theme support.

Here’s the setup I like, for what it’s worth:

handle-color: mix(#333, @background-color, 15%); // not sure how this one will look on a black background though
guide-line-color: rgba(255,255,255,0); // no guide line
item[data-type="note"] { font-style: normal; color: #999; }

I am very happy with this update @jessegrosjean and I am thrilled that the theme system has reached its first pass.


  1. How do I color generic dashes?
  2. Can I color the sidebar? If so, how?