I’ve written a Ruby library/command-line-interface for TaskPaper files. You can:
Create, open, inspect, edit, and save TaskPaper files
Export TaskPaper files as HTML and CSS
Automatically (if you have Less installed) convert your actual TaskPaper theme to CSS
Export as JSON
It’s free and open source. You can get the code on github. There are screenshots on that page of a sample theme (my own) and the resulting HTML output:
I hope you’ll find it useful. If you want to report bugs or submit feature requests, please do so at the repository’s issue tracker. I’ll accept praise and encouragement via any avenue, however…
(Addendum: I see that Jesse has just released a 3.1 Preview 185 of TaskPaper, with support for depth attributes in themes. I’ve updated the Ruby library accordingly.)
This is all great, but the automatic style conversion is most unexpected and cool!
Going forward I’ve got lots of code that could help a project like this, but I’m still not sure what the best way to distribute it is for both me and everyone else. For example right now in the scripting API there’s the ItemSeriailizer class. It support read/write of three formats:
BML - HTML subset.
OPML - Outline processing markup.
TEXT - This is how TaskPaper files are encoded.
I call TaskPaper’s underlying outline model “Birch”. BML is intended to be Birch’s native serialization. It’s not human readable like the TEXT serialization, but it is easier to parse and manipulate (since it’s HTML subset), preserves unique ids for each item, and displays in any web browser.
Right now this stuff is only accessible through TaskPaper’s scripting API which makes it fairly locked in and not suitable for a script like yours. But going forward it’s all written in Javascript and so it can run just about anywhere. Along with TaskPaper’s query language and all the rest of the API.
I’d like to release all this as an npm package so TaskPaper can spread more easily and in a standard form. The difficulty is that I’d like to somehow retain my right/avoid clones/keep eating! Any thoughts on this:
Make it fully open source. Mostly likely to spread TaskPaper, but then anyone can pretty easily clone TaskPaper.
Make it shared source. So source code is there, but to use it you must also have a TaskPaper license. I wouldn’t be able to enforce this (or really care too) at individual level, but it should keep clones from replacing TaskPaper.
Or some other setup?
Anyway would love to hear what anyone things. @mattgemmell if such as API were available do you think you would have used for this project. Or would you rather have just coded things up yourself for maximum freedom and flexibility?
(Aside: I’ve just hugely improved TaskPaperRuby’s HTML/CSS generation, supporting pretty much all of the current theme stuff, wherever possible.)
I wanted to create something entirely standalone, so I’d always have gone the route I did, but more integration is always a good thing. My feeling is that your value is in the app and the community around it. Shared source isn’t going to work, and frankly the TaskPaper format/workflow’s primary attraction is that it’s simple and open. Anyone can already clone TaskPaper; the value is in the polish of the existing app, and the things people have made for it.
I’d release your ancillary integration/API stuff as fully open source. Being the best and most attractive option always trumps trying to be the only option.
I think this is true if you think of TaskPaper the file format. It’s easy to write a highlighter or parser. But I don’t think it’s true if you think of TaskPaper’s runtime model:
Outline model
With query parser and evaluator.
Mapped to a text buffer supporting focusing, folding, and filtering.
At least it’s taken me 5 years to really get the design right. And if I release it open source it becomes easy for anyone to reproduce those core features and charge little or nothing.
It may very well be that open source would be the best result for everyone. But no strings attached is a pretty scary proposition from my perspective.
Anyway I’ll keep thinking. And listening to other ideas. Time to go back to fixing bugs for the moment
To clarify, I wasn’t suggesting open-sourcing the app itself; just potentially the stuff to integrate with its format, query, etc. I think there’d be value that would only increase interest in TP itself. But as you say, it’s easy enough for people to work with just the file format in their own way.
Just an aside: I ran a sample TaskPaper file through my HTML converter while using the Atom One Dark theme someone else posted. Makes a pretty good job of it.
First screenshot is TaskPaper, and the second is Safari.
A further update to TaskPaperRuby today: it now has a plugin system, to modify the HTML output. Three sample plugins are included:
Basic Markdown (italic-emphasis, bold-emphasis, and backticks code sequences)
Emoticons: a few essential smilies are replaced with corresponding emoji
Tag icons: some common tags and values are replaced with emoji icons
You can customise and/or enable/disable plugins as you wish. I’ve updated the README too. Below are before/after screenshots of a sample TaskPaper file, and its exported HTML version.
You can of course also create entirely new TaskPaper documents with TaskPaperRuby, and export them to whichever format you like. You can validate JSON output here.
Hi! I’ve been trying to find a way to get Jekyll to turn .taskpaper files into html includes and I’m wondering if this could be the way? Has anyone experimented with turning this into a Jekyll plugin?
I haven’t done this, but it certainly seems like it would be possible. The Jekyll site has this page about writing plunges: Your first plugin | Jekyll • Simple, blog-aware, static sites Seems like you would want to create a “Converter” style plugin… there are a number of examples that might serve as good starting points.
Hello,
I found this page in my search to find a way to output Taskpaper lists as HTML and I have had some success.
I can generate files but I get errors, so the styling is somewhat missing.
Being a few years old, I’m sure Taskpaper has moved on a little. Is there a way I can fix this?
Any pointers most welcome. The errors I am getting in terminal are below:
Couldn’t find file: /Applications/TaskPaper.app/Contents/Resources/base.less
Couldn’t find file: /Users/my_user_name/Library/Application Support/TaskPaper/theme.less
e[31mNameError: variable @text-color is undefinede[39me[31m in e[39m/tmp/taskpaperthemeconvertertemp.txte[90m on line 4, column 9:e[39m
e[90m3 li[data-type=task], li[data-type=note] {e[39m
4 color: e[7me[31me[1m@e[22mtext-color;e[39me[27m
e[90m5 }e[39me[0me[0m
Those errors appear mostly to do with just finding resources files. You may be able t fix by:
Make sure that TaskPaper is in /Applications folder
In the scripts replace base.less with base-stylesheet.less
Also make sure that /Users/my_user_name/Library/Application Support/TaskPaper/theme.less points to a valid file… seems like my_user_name is probably incorrect. Maybe need to provide a script parameter? I’m not sure.
Fixed and solved that one.
3.Yes, my_user_name was me obfuscating - I do have the path correct, but I don’t have that theme.less file - is this something I need to create or something which exists that I need to find.
Those are your custom themes in that folder, so the names might vary. I think the default one is called Default.less. To see what themes you have installed in that folder open TaskPaper and use the menu Window > StyleSheet to see a list.
