Hacker News new | past | comments | ask | show | jobs | submit login
Show HN: A plain-text file format for todos and check lists
452 points by jotaen on April 1, 2022 | hide | past | favorite | 164 comments
After having cycled through various CLI-based todo apps, I started to realise that I actually don’t need a tool at all for managing my todos. Most of the time, my use cases are quite simple, like viewing my todo items, checking them off, or adding a new one.

Rather than having to memorise CLI commands for these interactions (which I’m not super good at), I figured that it’s easier for me to use my text editor directly, and have an editor plugin help me with the visual structure and some convenience functionality. So, kind-of similar to Emacs Org Mode, but without having to use Emacs. I personally use Sublime Text, and even though I enjoy it a lot, I don’t like being bound to specific tools.

I think the best basis for staying independent is to have a data format that’s properly specified and meaningful on its own. This puts the data first, and it allows the tools to be built on top and shared (or interchanged) more easily.

This is what [x]it! is about, which is a plain-text file format for todos and check lists. I’m curious for thoughts and feedback. There is obviously not much tooling support (yet), but feel free to create something if the idea resonates with you.

Website with demo: https://xit.jotaen.net

File specification: https://github.com/jotaen/xit/blob/main/Specification.md




+1 for plain-text for all the points you mention, particularly "data-first with tools on top". But why reinvent the wheel when the org-mode format is well established and does everything you want, and more?

There are an increasing number of tools using org-mode as a plain-text data store, so you are more likely to be able to participate in a tool ecosystem. In addition to my own https://braintool.org see the list below. BrainTool (mainly a bookmark manager) has an elemental to-do system, I'd love to have my users be able to use your tool for todos.

NB see also Karl Voit's push for org markup awareness outside of Emacs via Orgdown: https://gitlab.com/publicvoit/orgdown.

------ ORG-MODE TOOLS OUTSIDE EMACS

https://plainorg.com

https://flathabits.com

https://beorg.app

https://braintool.org

https://easyorgmode.com

https://logseq.com

https://organice.200ok.ch

https://orgro.org

http://orgzly.com


Isn't org-mode tied to emacs? Also, does it have a specification? I searched for a specification and found this (https://orgmode.org/worg/dev/org-syntax.html) and couldn't understand whether it is a proper spec. Without a well-defined spec, it becomes very hard to create tooling around it. For example, Markdown was using Perl scripts initially and didn't have a spec for some time.


There's at least a parser using that as a spec at https://github.com/200ok-ch/org-parser


also this one: https://github.com/orgapp/orgajs


It parses, but it's not interactive at all. For example, it doesn't run code blocks, iirc


org-mode does not have a spec. Its Emacs implementation is the canonical implementation. But org-mode is still just plaintext, and you can read org-mode files using any plaintext editor.


Yeah but its difficult to look at and read as purely plain text, unlike markdown. And since the power-features of org arent available in your editor(s) (unless you use Emacs) it isn't tenable. I'm convinced Emacs users are blind to this given the seemless rendering done by Emacs. There's room for a new spec.


Obviously I'm biased since I built BrainTool because of my emacs/org use, but I also use markdowns and maintain the braintool.org blog on github in their markdown. I don't find it more readable. Maybe it's a familiarity thing, anything specific you dislike?

Anyway here's the definitive argument for org as markup of choice: https://karl-voit.at/2017/09/23/orgmode-as-markup-only/

It would for sure be nice to have a definitive spec to point to, independent of the emacs ecosystem.

BTW see below the first few lines of my dev-log.org file for yesterday. I think its pretty readable!

* <2022-03-30 Wed>

** DONE Today [83%]

   - [X] Call w alex

   - [X] Exercise

   - [X] instructions to Alex

   - [X] letter to Deignan

   - [X] taxes

   - [ ] styling for notes col
** DONE bug narrow edit card shows item under bullet which is confusing. :dev:099:

** DONE get rid of link in welcome topic, too confusing :dev:099:

** Instructions for running BrainTool locally:

   1) Make sure you have git installed. (https://git-scm.com/download/mac)

   2) Make a folder where you want to put the code


One of the clear problems I have with this format is that you have to write a dash in front of every todo. This may seem like a minor gripe, but when writing todos is by far the most common action, it really does increase the friction a lot.


That's still too many formatting bits for me.

My weekly todos look something like this:

It uses a simialr format:

YYYYMMDD

- Task to be done

  - Subtask

  * Note about task
/ Task started/half done

x Task completed

ie:

20220328

- finish baselining instances for ami creation

  x server 1

  / server 2

  - server 3

   * Make sure RH image is being used vs AWS provided AMI
/ verify routes exist for all subnets

x snapshot instance X before users are added

-- Dave


You can have YYMMDD too.. its just how he's input it.


IMHO: Workflow, Text input fields and File formats are like APIs; if there is a way to abuse, hidden or public, then someone will use that in their process (https://xkcd.com/1172/). So adhering to Org mode in your own parser will mean a lot of work anyway. There will always be some subtle point that make your format incompatible with a tool you want to use.


Is it really that much harder to read than Markdown?

- Headings: Markdown uses #, Org uses asterisks.

- Italic: Markdown uses asterisks or underscores, Org uses /

- Bold: Markdown uses double asteriskes, Org uses asterisks

- Inline Code: Markdown uses backticks, Org uses =

- List items: both use dashes

- Links: Markdown uses [description](url), Org uses [[url][description]]

- Code blocks: Markdown indents each line by four spaces, or some modern dialects use tripe backquotes, Org uses #+begin_src, #+end_src tags


Sibling comment already addressed the readability of the source, but I'd like to ask what rendering you mean exactly?

The "rendering" I see in an open org-mode file right now is a) coloring and b) collapsing. So apart from hiding and coloring things I think what emacs shows is exactly the source, at least in my configuration. Did I miss something?


When I last played with it (Emacs + Org) I had options enabled which hid much of the markup entirely (e.g. the **) and applied various styles to express the intended structure, and it was lovely, much more than just coloring. Nothing I'm saying is without love for Emacs and Org, more just sulky acceptance that tools can add additional mental overhead, even if they're cool, and this seems to be the opinion/philosophy of modern tools etc, VSCode/IDEs/Web-based IDEs etc.

So.... when I tried to use Org in VSCode, Vim, Notepad etc, it just sucked. Not even a comparison. In that case, Markdown was better. Maybe I'll look at it again. But like the OP (in the sense of making up my own thing) I have dabbled in creating my own clone of Org-mode based on a Markdown spec.


Hmm ok, I never have these options on. For no particular reasons other than that they don't seem to be the default (or something's wrong with my config), and I never missed any additional application of style.

So it's possible that I just got very much used to how org-mode "source" looks.


Yes, for task management and for any other applications, Emacs offers programmable views of Org files.

A popular view of Org files that comes already builtin in Emacs is the agenda view.

The agenda view lets you query all todos, incoming deadlines, scheduled appointments, etc. harvested from a list of Org files.

For example, I can quickly see all todos, incoming deadlines, scheduled appointments, holidays etc. for an arbitrary period of time, say week 40 of 2022.


Yeah, but this was about comparing markdown and org-mode (for readability and probably visual appeal), and rendering the "raw" buffer.


You can get quite far with it. I’ve used https://orgmode.org/worg/dev/org-syntax.html when implementing lots of https://plainorg.com and https://flathabits.com.


Last time I checked, there was an extension for org-mode in Visual Studio Code, but it felt a bit more like a glorified WSIWYG markdown editor with a few extra features - just a tiny, tiny fraction of org-mode's potential. But that tiny fraction alone covers a wide variety of use cases.


There are implementations for other editors, for example NeoVim[1].

[1] https://github.com/nvim-orgmode/orgmode


> org-mode format is well established

Is there a formal specification or documentation on the format? When I've previously read about integrating org-mode support in other threads, the lack of specification outside of "whatever org-mode does" was the biggest blocker.


https://orgmode.org/worg/dev/org-syntax.html


I’ve never used org-mode but have heard enough about it to be intrigued. If there’s no spec and it’s “whatever the emacs implementation is” then I think there is plenty of room for a plaintext alternative.


Is there anything that isn't Orgzly for Android? I found the app very finicky from my basic usage and very difficult to use.


Funny that all the phone versions have a hard coded UI. Isn't the point that org mode is just plain text so it's more free from? I currently use google keep. I'm not recommending it but to some extent I can use at as just a collection of synced text files.


<insert “porque no los dos?” meme here>

A mobile-friendly interface that enables jotting things down quickly while on the go… (coincidentally, fully typing “- [ ] remember the milk” is clunky on mobile, switching keyboard, etc).

Also powered by plain text, so you can drop down to the details whenever you want to (including your mobile) with all the portability associated with it.

disclosure: I wrote https://plainorg.com and https://flathabits.com because I wanted a frictionless mobile experience without giving up on org markup (plain text).


Thank you. Every time I come across some "plaintext" enthusiast who refuses to acknowledge that mobile devices are not conducive to free-form text editing of structured text files, I want to punch them in the face.

Mobile devices require context-aware, guided data entry/editing interfaces.


I beg to differ. I find google keep / apple notes to be much more useful in mobile precisely because they are free from. I can enter lists , notes, phone numbers , links, all in the same document and usually get far more info on the screen.

Conversely every fixed ux tool I've used for this fails miserably because too little data since it's wasted by ux and small non freeform fields in widget that have limited space.

Further, I can easily cut/copy/paste large sections across documents where as in most fixed ux apps I'd at best only be able to move one item at a time and at worst have to manually copy each field from each widget to each field in another widget


These look great! Pity that it is iOS only since I use a Pixel.

How did you create the videos at the top of the page? It's very well done


> How did you create the videos at the top of the page? It's very well done

Thanks. Unexpectedly, Keynote.

I followed a tutorial I bookmarked from HN ;)

https://news.ycombinator.com/item?id=18805222


Thanks! I had seen that post and promptly forgot about it :facepalm:


The only phone version I've used is beorg, but beorg lets you directly edit the plaintext if you want to. I usually don't because the hard coded UI is pretty convenient.


(Author of Orgro here)

Orgro displays the file as "rich" text, so it is not a "hard-coded" UI; it's much closer to viewing the file as you would in Emacs.

That said, it is definitely lacking compared to Emacs: it's a viewer only and mostly doesn't interpret the file contents; you can't execute code blocks, etc.


I am conflicted on this.

The spec is nice. I love the recognition that dates may be imprecise (e.g., 2022-05 -- although I would count that as the last day of the period, 23:59:59 on 2022-05-31, rather than the first day of the next period, 2022-06-01). I like the thought that went into it and the nice presentation.

On the other hand, I do not think this is necessary or even all that helpful in the real world. You don't need a standardized format if you are writing to do items manually in a text editor. You just write them. In the vast majority of cases no one is going to see them but you. Time spent conforming to a spec is time wasted.

A formal spec also doesn't help much for apps to use this format. There is not a huge need for portability between to do apps, and for most users to do items are ephemeral and not something that needs to be archived and revisited. Even if an app adopted this, being tied to a plain text format would likely hinder feature development, including the ability to sync across multiple devices. Beyond that, different to do apps use different systems of categorization and tagging, so really in practice I doubt this will become any kind of standardized format.

So, all told, it is a beautiful effort, nicely presented, but I think it is unnecessary.


> A formal spec also doesn't help much for apps to use this format. There is not a huge need for portability between to do apps, and for most users to do items are ephemeral and not something that needs to be archived and revisited. Even if an app adopted this, being tied to a plain text format would likely hinder feature development, including the ability to sync across multiple devices. Beyond that, different to do apps use different systems of categorization and tagging, so really in practice I doubt this will become any kind of standardized format.

I disagree. I maintain a rather popular plain-text-based app [1] and the formal spec makes this something very very easy to add support for. Infact the only thing that could make this even easier is if there was a way to verify my own implementation.

[1] https://gitjournal.io


Yes, you could add support for it. To what end? Do you think the usage will be high enough to justify the effort to implement and maintain it?

Even imagining the ideal world where every to-do app implements this, portability of to-do items between apps just isn't that big of a problem. There isn't a big need to move long lists of to-do items between apps.

And in the real world, this won't be implemented perfectly. You'll have the App A implementation, the App B implementation, and so on. Look at Markdown. You'll have headaches migrating your to-do items automatically and in the end, most likely, you'll just end up copy and pasting them. It's not that hard and old to-do items aren't that important to the vast majority of people.


This sounds a bit defeatist.

Yes, it won't be perfect at first, but there is always a chance of reducing the barrier to entry. The lower it is, the more % of users / developers / apps are going to use it.


It's not defeatist. As I said, I just don't think, even in the optimal scenario, that it is a goal worth achieving. Personally I'd rather software developers focus their time on more worthwhile features.


Not sure I agree. I didnt know about gitjournal until vHanda's post, but immediately saw how it could be a replacement for my use of Google Keep (which I use when I'm on the go vs at my laptop). And there was already an exporter for Google Keep. I'm guessing that exporter benefited from a spec being available.

Your point about "if you're the only one using it, just use it" does apply, but sometimes we do find ourselves being more successful than we originally expected and defining things via a spec is not a bad thing.


What is worthwhile can vary widely. Like the quote that people use only a slice of Word, yet often different slices.


yes

To add to this, many markdown apps do support TODOs, but they use their own format. e.g. Bear uses

    - [ ] Unchecked
    - [X] Checked
If there was a widely-accepted standardized markdown format for TODOs you could write them in one app and then they would display properly in others.


Foam Notes also uses that same markdown format for checklists. I think that Markdown is a pretty good format for notes and is already used by enough apps.


Microsoft Azure DevOps does too.


I'm a happy gitjournal user, and I want to +1 this. I'm already using it for checklists as plain markdown, and the format is pretty similar. I can see a lot of value to this as a semi-markdown compatible extension or second app sharing the codebase.


> A formal spec also doesn't help much for apps to use this format. There is not a huge need for portability between to do apps...

To add some counterpoint to this, I try a lot of apps. Partially because I'm always looking for the one that's better than what I use now - looking for the thing that fits me the best - but also because I just like trying things.

Portability means a greater chance that I'll fully dive in and use an app to its potential vs. some light use.

There have been a few times that I've found a new app/solution that was clearly better than what I was currently using, and this was both exciting and frustrating. Frustrating because it meant I'd either have to leave my history behind, or spend a ton of time trying to port it over somehow.

I realize I'm part of a niche group of people, but I feel like a spec like this was meant for a pretty niche group of people.

I for one do not agree that this is unnecessary, but I do acknowledge that it's probably not necessary for a lot of people.


> I feel like a spec like this was meant for a pretty niche group of people.

That’s spot on actually.


Portability and human readability in a normal text editor are huge plusses for me.

I mostly use paper notebooks, but when I need to keep track of todos over a long period of time for a specific thing, I like to have a text file located with that thing. With all of these cloud-based tools we now use, everything’s refactored to be organized based on tool, then project instead of project, then tool. I for one am starting to rethink this. Changing of tools or people, or simply passage of time inevitably loses information, or knowledge of where information was stored.

I could see myself using this format for simple tracking in a git repo where I don’t want to use GitHub or another similar tool. One use case would be getting things done in a JIRA/middle-management heavy organization.

Having the spec is then nice because anyone could use their preferred tool if they want to and one could easily check for open todos in a bunch of folders/repos.


I appreciate the criticism, thanks! I disagree, though, that adhering to standardised formats is not worth it. Currently, there are countless todo apps and editor plugins out there, which all do very similar things. However, each needs their own dedicated editor plugin for syntax highlighting, and you can’t easily switch the client apps without having to also switch the underlying data format.

What I agree with is that standards limit the creative freedom of tool creators. But that’s the same balancing act all over again, no matter where you look at.


I disagree, having the spec is the first step to building tooling around it. People can port plugins that support this format to vim, eMacs, VSC, etc.. and create functionality around it. For example: reorder into a date view


Still, why plain text? If the goal is “wrap it in UI” why a new white space, special characters.

Why not YAML or JSON and the vetted libraries to read and write the format?

As a user I don’t really have any concern with what underlying data format and structure it stores things in. I want to manage my todos!

This could be an SQLITE file for all I care.

Software engineering should be about more productive UX, not flexing one’s ability to parse arbitrary syntactic art.


> Software engineering should be about more productive UX, not flexing one’s ability to parse arbitrary syntactic art.

Tasks lists are generally useless without their context. It makes sense to have tasks along their context (be it plain-text, markdown, JS, python...) Also it's more maintainable and portable. YAML/JSON/SQlite will be a headache when the user decide to migrate to another tool. This approach only require a text editor, any text editor in any platform. You can plug in whatever you prefer for syncing and sugar.

For a very few cases I use YAML to store data that isn't parsed by any program (only by me). And I can write a comment like 'TODO: Do something.' or "FIXME: X isn't working.' On the terminal using a code searcher and a text editor I can easily find and jump on those.


UX creates context from the users perspective, not the back end data format. This format creates a headache in that nothing can parse or write it except the humans that learn it.

I can easily search an SQLITE file from a CLI (wrote me a tool a long time ago to fuzzy find). I doubt the YAML lib for Python is going to become obsolete soon. I can instantly work with that format on any machine with a common language. There’s already Taskwarrior.

It’s electrons in a machine, hundreds of different paths to porting it around, changing it, etc.

Look, don’t get me wrong; I’m not about to pour sugar down someone’s gas tank. I’m just walking through my inner monologue debating this format someone chose to put up for open review and discussion.


I write data that makes sense to have as normalized in YAML format even if I'm not parsing it in any program because I may do so in the future and YAML is ergonomic.

But for things that shouldn't be normalized I write then as plain-text notes using markdown notation. It isn't true that nothing can parse plain text. I wrote a tool to do that and it works as expected. Of course it's bad design if you look exclusively from the software engineering perspective but ergonomics also matter and parsing text isn't hard.

Don't get me wrong also. I'm just a guy with peculiar use cases and bad experiences migrating away from Evernote and later Joplin.


I think the viewpoints on that are wildly diverse. As far as I’m concerned, it’s the exact opposite. Hence, I think it’s great that there is a big variety of different approaches that everyone can pick from according to their own preferences.


Sure; I’m just expressing mine. The “glyphs and how to display or sort them wars” aren’t important enough to me to take real offense to alternatives. This is just idle discourse for me.

Lindy Effect type thoughts, why import another dependency; familiarity, existing portability, and habits with current formats; deep and wide tooling and language support… road built; let’s drive to shovel poetic drivel out the door.


I think the author is saying there is already a spec, just one abstraction layer above: Plain text. Anything that can read and write text can interact with the to-do list.

In some ways, it is more portable.


Agree. Todo lists are ephemeral. They're not meant to be stored and archived. Just write the list already, execute the items in the list and move on. Focus on getting things done rather than creating new formats for these ephemeral lists.


> Todo lists are ephemeral. They're not meant to be stored and archived.

I have many recurring items on my todo list. So those might be nice to be portable between apps.


I think that having a formal spec would help since a lot of the minutiae that is done to format and the like can be in the form of snippets in (nearly all) text editors used today.

So just having the autocompletion for people editing in text does wonders.

As for standardization, applications don't have to target it as their on-disk format for it to be useful. Instead of bespoke JSON/XML schemas or proprietary formats, having a plain text export format is a big win. Specially if it's human readable and human writeable.


I'm not sure this is the best tool for an import-export format, as it is unable to capture all of the data available in some to do apps.

I could see it being OK as a sort-of data backup format. But it's missing a lot of data that really ought to be tracked by an app, like creation, update, and completion times for each item. Many apps also track priority, sort order, hidden/unhidden status, attachments, and other things. This stores none of that.

Even then, the value is fairly small. In 20+ years of using to do apps, I can think of very few times that I've referred back to completed to do items.


I think it is nice when there is a well thought out spec for something. But in this particular case, I think it is not compatible enough with other tools.

In particular, Markdown has a todos (using the same `[ ]`) and just uses indentation for grouping. I find this more intuitive and it renders in markdown renderers.

For priorities, I have adopted the notation of OneNote which puts exclamation and Unicode star symbol next to the todo brackets.

I also use some other conventions:

[-] for obsolete rather than [~].

[>] for postponed until later

Implemented in my Todo manager TUI: https://github.com/coezbek/rodo


> In particular, Markdown has a todos (using the same `[ ]`) and just uses indentation for grouping.

Came here to mention the same thing. I use a plain text todo format that is quite similar (thought not nearly so thought out/complete) to the one OP is proposing, but I use indentation for grouping as it's a lot easier for me to visually identify related groups of tasks.


Might be right, but as an interchange format between todo-apps, might be worth it?


Where I think something like this is most useful is as a common interchange format. For example, if you are using TickTick as a todo app and decide you want to switch to using Notion or something. If there were an ecosystem of converters to this common format, that would make this trivial to do.


A spec makes it more easy to build tooling around it. I reckon the people that love emacs org-mode, do so not mainly because of its specification, but the power to manipulate those plain text files in the editor.


Agree, not everything needs a special format or spec. To me, it just obfuscates the core purpose of a to-do list for me, which is to record the bare essentials to remind me of things I need to do, then do them and forget about them. Anything else is just more overhead I don't need.


As an alternative, the todo.txt format [1][2] first defined in 2006 [3] is supported by a CLI client (desktop) and several GUI clients (desktop, mobile, web).

[1]: https://github.com/todotxt/todo.txt

[2]: http://todotxt.org/

[3]: https://web.archive.org/web/20060701121920/https://lifehacke...


I've been using todo.txt too, for personal tasks and appointments.

I have a few tweaks: https://www.neilvandyke.org/todotxt/


This is what I use. It's a little hobbled in terms of add-ons to the standard because the orginal standard isn't centralized or versioned, but it works really well for a lot of things.


Clickable links:

Website with demo: https://xit.jotaen.net

File specification: https://github.com/jotaen/xit/blob/main/Specification.md


Any todo list that doesn't account for dependency tasks is exclusively limited to short term planning (i.e. days not weeks). After skimming the spec, I don't think dependency tasks are accounted for?

For example, say this is my (out of order) to-do list:

- [ ] Mix ingredients

- [ ] Eat cake

- [ ] Bake a cake

- [ ] Find cake pan

These tasks need to be done in a specific order, but reading the list top to bottom doesn't make sense.

So let's denote dependencies with indentation:

- [ ] Eat cake

  - [ ] Bake a cake

    - [ ] Find cake pan

    - [ ] Mix ingredients
By specifying order through indentation, we've now created a DAG that orders and contextualizes tasks; with the most actionable tasks having the largest indentation. This is how I organize my plaintext to-do files, but afaict no todo list software is able to handle large task trees gracefully- with the exception of grit, which is more of an experiment (but the readme is incredibly well written and describes the DAG problem to a tee).

https://github.com/climech/grit

Does anyone know if org-mode handles complex task trees gracefully? All the examples I've found online were trivial (i.e. one task deep)


IMHO, you are mixing TODO lists and task management/planning software. No, I don't know a good task manager or business process manager for command line. Instead, I created a simpler TODO list manager, called `td`[0], which supports flat TODO lists only, and use directories and command-line generators to manage todo's. `td` prints top item only, by default, leaving little room for procrastination. I'm keeping one `TODO.md` file per project instead of one large TODO file for all todo's.

[0]: https://github.com/vlisivka/bash-modules/blob/master/bash-mo...


Looks interesting. It doesn’t have a formal specification, but there may be things from TaskPaper https://www.taskpaper.com/guide/getting-started/ that you may find interesting.

There are lots of things that support the basic TaskPaper format: https://support.hogbaysoftware.com/t/taskpaper-extensions-wi...


This is awesome! Super appreciate the effort on this.

One challenge I've had is the file-based concept. And it losing "shape" quickly. I taken a few whacks at something different and have settled on a CLI-based kanban-y thing: https://github.com/kitplummer/clikan

But this lacks things like tags - which I appreciate as long as they are searchable in some form.


nb might be worth a look (has tags) https://xwmx.github.io/nb/


I loved nb! Until I ran it from a top-level directory and it committed an update to every git repo within that top-level. :D. Definitely operator error, but I learned my lesson and am back to separating notes from todos.


Nice! I also have this pain of the file losing shape quickly. My take is to have a a CLI tool to "carry over" all todos which aren't solved into a new heading. This way the old/resolved items are moved to the back/lower in the file.

I call it Rodo (Todos in Ruby): https://github.com/coezbek/rodo

It uses Markdown for syntax.


Cool, that looks quite neat! I agree with you, at some point you have to structure things in one way or the other, in order to keep an overview. For me it works somewhat well to organise my data across different files and folders, which are setup in a certain structure. That either requires some manual labour and discipline, or you automate these workflows. That requires “standardised” data formats, however.


I like it.

I do something similar for my todo file but organize by date. Most recent date first. Every day I review unchecked items from the previous day and move them to today or mark them obsolete.

It has the added functionality of serving as a nice log of my work.

So it looks something like this:

    2022-04-01
    ==========
    
    [ ] do a thing
    
    2022-03-31
    ==========
    
    [x] foo the baz


Me too, although I use markdown todo lists, starting with a minus.

I also record the creation date and timestamped notes on the progression of the task. And I use @ to keep tabs on tasks that I've delegated.

    2022-04-02
    - [x] [2022-03-30] do a thing #tag1 #tag2
        - 2022-03-31 10:30 notes about work being done thing
        - 2022-03-02 14:00 completed thing by using X
    - [ ] [2022-03-28] @delegated_person: do another thing
        - 2022-03-29 09:00 delegated_person reported that Y


There is a todo format that I use daily called todotxt. It has even application support on most platforms or you just write manually in a txt file. Easy to overview by yourself. In combination with Syncthing I have a very seamless experience where ever I go.

http://todotxt.org/ https://syncthing.net/


I had a similar insight some years ago. I write my TODOs mixed with text in markdown notes and use a CLI to do nice things like exploration and journaling. It purposefully doesn't have any state besides the notes in itself.

https://github.com/danisztls/journal

Lately I'm rarely using it because most of the things that I really have to do (work) are on my email inbox or containerized in project dirs. And for the later I just run 'rg "TODO:"' in the project dir.


I didn't know about rg, how does it compare to ag?


https://blog.burntsushi.net/ripgrep/


AFAIK ripgrep is faster. Haven't used ag much so I can't compare features.


I have my own informal format that doesn't use the [], just single characters

    - this is an unstarted todo
    / this is a started todo
    x this is a finished todo
    ~ this is a todo I'm not going to do
It works well for me.


That resembles what I use in my daily paper agenda:

    / Unfinished task
    X Finished task
    % Canceled task
    ↗ Task moved to a later date
    ↙ Task moved to an earlier date
In effect, I can convert the ‘/’ sigil to any of the last four sigils and I can see at a glance what still needs to be done.


This is similar to my own format too, but opposite meanings for some of them, and a few have somewhat mnemonic character names:

    ~ todo (tilde)
    * started (star)
    - done (dash)

    x didn't or won't do
    # comment
    > design item
I use this mostly to write out and track steps in scripts and programs I'm writing. I will use one or two levels of indentation and blank lines within entries.

    example feature steps

        > the example feature will demonstrate such and such
          and make use of this and that

        - write stub version
        * fill in actual code

            - part A
            ~ part B

        x call xyz function
        # didn't do this because of ...

        ~ add extra features
I do this mostly in the header comment of a script (Python doc string), but sometimes pull it out into its own text file if it gets too big.

I wrote a script at one point to convert these kinds of notes into a web page with various background colors per status. It helps to visualize it sometimes but I don't actually use it that often.


Looks interesting. Might be worth looking at the Emacs Org Mode support for TODO lists[1]. Just as a reference for how someone else dealt with TODOs in a text format, but with a pretty complete feature set.

[1] https://orgmode.org/org.html#TODO-Extensions


Just my 2¢: I'm also using plain text files as a 'mind-dump'/exocortex/organsation system. After a while, the file tends to get rather big, and so I need some coarse hierarchical levels, like 'random cool stuff to look at when idle', 'high priority stuff/this week', 'medium priority stuff/this month', etc. A copious amount of unicode and especially ASCII art helps me a lot to find sections quickly. Behold my elite retro headers like

  ╗
  ║  TODAY
  ╚═════════════════════════════════════════════╗
and grab-box of symbols:

  ↗↙⋇⟡*═╔╗╚╝║∙◽◼▪→▶▷▸▹⇒⇨◉๏⦿⊙○●⭗⭘⭘
  ────── ∗ ⋅◈⋅ ∗ ──────
Markdown-style headers (with - or = underlines) also help a lot to organise within the top-level sections. In general I find it very helpful to re-use Markdown (or reStructuredText) syntax, even if it's not rendered.


This is really cool. I dig it.

I like that there's a Sublime Text package for it. Seeing my plain text todos with nice syntax highlighting is a perk.

I maintain a Zenburn color scheme[0] for Sublime Text. After playing with this, I added specialized support for [x]it! and I think it looks pretty good[1].

[0]: https://packagecontrol.io/packages/Zenburn%20Color%20Scheme

[1]: https://github.com/ryanolsonx/sublimetext-zenburn-theme/issu...


Looks like quite similar to my own document / task management grammar [1].

I wrote a small library to parse mine, and built many tools on top of it, including editor support, various CLIs for task management, calendar, activity tracking, content consumption, etc.

I invested a lot of time into learning Emacs, got into using Org, but Emacs is just too slow, and I got to a point where customizing the tool for what I want was harder than building a custom tool.

[1] https://i.imgur.com/Nm6e31W.png * sorry for ma english


This is very cool!

We're actually building an editor/IDE of sorts from scratch, but specifically for "todo.txt" (https://thymer.com if you're interested). I think a lot of parts of your spec would fit really well with the concepts we were thinking of (like the status in between [ ], due dates, #tags..). Maybe we should add compatibility for this spec as well (for things like autocomplete, and export/import).

Thanks for posting, really helpful for portability to have more standards like these!


I switched away from Workflowy to a plain text file format. Load times are quicker, navigation is quicker, can use keyboard only without a mouse, the UX can keep up with the pace of my thinking.

I prefer vimwiki for this purpose https://github.com/vimwiki/vimwiki

You can get plugins that sync it to a git repository. I love this.

There's also task warrior plugins, though I haven't figured out how that would for me, seems to get away from simple text files at that point.


Very cool! I made something very similar to this as a VS Code extension[1]. Inspired by the bullet journal method.

[1] https://marketplace.visualstudio.com/items?itemName=blt.blt


This is really neat. It's similar to the BuJo rapid-logging-inspired system I handspun for myself around Markdown a few years ago that I outlined here:

https://news.ycombinator.com/item?id=21580133

I'd quit using that one since because too many Markdown editors have forgotten tabs are legal whitespace after a UL bullet, and that there are three different UL bullet characters (and it really doesn't help that the CommonMark examples page only docs `-` and `*`, even though `+` is part of the CommonMark spec too). In particular, without the tab support being implemented, there's no fixed gutter for the BuJo-style sigil and queries get much harder.

But I do miss the idea of those simple bullets. I may have to check out your extension.


When I saw the OP's format, I immediately wanted a VS Code extension for it. This looks great, installing it as we speak.

In fact, I like your format slightly more, because when I complete tasks I usually just delete them -- no need for a checkbox.


This is really cool. I am endlessly fascinated by the proliferation of "productivity apps" when I find the same thing as you: that they are quite unnecessary.

My approach is similar. I already take notes via a Bash script. I configure a particular "label" for any todos and (essentially) just grep for them, excluding those that are crossed out (with Markdown tildes). This approach works great for me as a Staff Engineer in a large tech company. Reference: https://github.com/scottashipp/noted/blob/main/subcommands.m...

I also wanted to mention there are several related ideas / movements around the web. One of the biggest is todotxt. In case you hadn't heard of it: https://github.com/todotxt/todo.txt


I used todo.txt for a while, but in the end I stopped using the CLI tool and just worked with the files directly. For my use cases, the todo.txt file format has a few shortcomings and inconveniences, and there also is no dedicated specification.

That being said, I drew a great deal of inspiration from todo.txt, and I think it’s a well-made and powerful tool.


This is very cool, thanks for sharing! I'm a huge proponent of tool-less things, and a consistent todo list format readable in any text editor has been extremely helpful for me. I use my own markdown-inspired todo+notes format, but looking through xit and todo.txt has given me some ideas, specifically around my format's[1] inability to indicate priority when a line is taken out of context.

Question: why must the square brackets be used[2]? Could not the first and third chars be omitted, leaving only the status of the item as the first char on the line? I can see (and appreciate!) the desire to use brackets for readability, but if there's a functional benefit I'm not sure I see it at first glance.

I especially like your use of `!` and `#`, that's a nice way to make those items accessible through a grep.

[1]: Each day begins with a `\n# YYYY-MM-DD` section heading, then I use the ordering of my day's tasks in the list to indicate priority. `- ` prefixes an incomplete task, `* ` prefixes a completed task, `~ ` prefixes an obsolete task (similar to your xit), and a generic note doesn't have any predefined first char. One or more pair(s) of spaces indent subtasks or notes as appropriate.

[2]: https://github.com/jotaen/xit/blob/main/Specification.md


> Question: why must the square brackets be used[2]?

There is no technical benefit behind the square bracket notation. As you mentioned, it’s mostly for readability reasons. My take on pleasant plain-text formats is to make use of symbolic notation if ever possible, because that makes the format more intuitive to understand. The `[ ]` resemble a check box, and it should be immediately clear what that means. The drawback is that you need to type in 2 extra characters, of course, so it’s really a tradeoff in the end.


Like you and many others, i use my own similar format, and the brackets actually come in handy for those rare cases when there is a need to print out (yes, as in harccopy paper; oh the humanity)...because they resemble good ol' fashion checkboxes. ;-)


Only thing I would think of changing would be allowing for the use of colons in tags to provide tag namespaces. Then it's fairly trivial to implement things like created on date, completion date, and the like since it's just "#created-on:yyyy-mm-dd" or "#completed-on:yyyy-mm-dd".

It also allows users more generic organization options, with filtering based on the namespaced tags being something trivial, but ultimately up to the user or the app that is interfacing with the xit file.


I searched for todo management for years and I tested tons of apps. But as a developer this is the solution I use that works well for me:

Use YAML as a todo list, you can organise your things like:

Perso:

  - Take an appointment at ...

  - ...
Client1:

  - Do something

  - ...
Then put it in todo.yml in your Google Drive (for backup):

/Users/mishaker/Google Drive/My Drive/todo.yml

Then add an alias on your cli:

alias todo="subl /Volumes/GoogleDrive/My\ Drive/todo.yml"

Voilà, that's a simple solution which works for me.


That is very similar to the Taskpaper syntax if you end up wanting some additional tooling in the future.

https://www.taskpaper.com


This is great!

I wrote Margin[1] for similar reasons. But because I wanted to be able to incorporate notes as well as to-dos, absolutely anything can go between two square brackets in Margin:

[ ] denotes a to-do item

[x] denotes item marked as done

[anything] denotes an annotation of type "anything"

At first blush, it would appear Margin and [x]it! are compatible, with some very minor differences. Feel free to draw inspo from the Margin spec, and hit me up if you want to combine / collab.

[1] https://margin.love


Exactly this. I also use ( ) to denote things that others owe me.


A little note to other HNers: The demo on the web site is clickable.

To OP: Very cool. I've switched to it from Markdown for my monthly goal-setting. I like the Sublime Text plugin.


Have you also tried checking all the items?


Haha ;)


I’m seriously considering to make that mandatory via the spec. :D


> [an item] MUST start at the beginning of a line with a checkbox.

Why no subitem?

    [] large task
      [] subtask 1
      [] subtask2
I use this all the time.


I also thought about this, but I have postponed it for now, because there are some implications with this (see here: https://github.com/jotaen/xit/discussions/2). So I thought it’s better to properly think this through beforehand.


I use subitems pretty heavily in my todo_notes.md file as well; to work around the concern over conflict of state, I pay attention to only the checked status of the `large task`. If that parent is not checked off, I know there are still pending subtasks. So I won't really care if there are un-checked subtasks; as long as the parent task is checked I know I can ignore it and move on. Maybe that could be formalized a bit more strongly but since it's only my eyes which will see my todo 99% of the time, I'm fine with it and I know the convention.


Shameless plug. For those who use Orgmode, but think that Agenda is a bit too heavyweight to manage Todos, I created a Magit like interface to manage Todos (in an orgmode file): https://github.com/ChanderG/toodoo.el


Interesting idea, I like the premise that people might build fancy ways to interact with this such as VSCode addons with a 'real' UI, but there will always be a plaintext fallback.

I already manage my hobby software projects using plaintext files, using a made-up syntax that is not quite org-mode, not quite xit, but that I'm also not too strongly attached to.

The one thing that jumps out of me that would make it hard to switch to xit that the spec currently doesn't allow lines to start with whitespace, which I use for grouping things. I settled on 2 spaces, but could also see 4 maybe being a better choice because of how it makes things line up.

(presented here with additional spacing because hn doesn't parse single newlines)

UI

[ ] Buttons

  [ ] Front page call to action

    [ ] Make it red

    [ ] Make it really big

  [ ] General

    [ ] Increase padding

    [ ] Stronger drop shadow


I didn’t include nesting in the first edition of the draft, because there might be some implications with it and I was curious for feedback on this. https://github.com/jotaen/xit/discussions/2

But it seems like my potential concerns are not shared that much, so I think the nesting should be added to the [x]it! spec.


Nice, kind of weird like a bullet journal. Very ergonomic.

For bonus points you should provide an LSP server that lints and syntax checks your xit! files.

Why? Extracting data from notes is really useful. Even if it’s just to reformat them. To extract data they must first be parsed, and to be parsed they must be free of errors.


Good work! I might just try this out in my next attempt to GTD

I’d like to suggest thinking more deeply about dates. I love that you opted to use the yyyy-mm-dd format and I also think it’s great that you’re making things flexible because life is messy.

The problem I see is this; suppose I’m in a text editor and I want to see my todos ordered by due date. This will help me see what’s coming up.

The advantage of using a yyyy-mm-dd format is that it makes things really easy to sort in reverse lexicographic order. However, with dates coming in at any point in the todo, sorting might be tricky. The week-style date format would also be tricky to sort properly.

Granted, this is an option for tools to solve! But if the primary tool is a text editor, then this might be an area that could use refinement.

Again: love the work you put into this and I also love the ergonomics! Thanks for sharing!


You can have lexicographic ordering with [x]it!, as long as you stick to a specific structure, which is:

- Write due dates first

- Pad your priority with dots

- Don’t use line breaks within descriptions

- Don’t use titles

Then it will sort (in that order) by: item status, priority, due date.

    [ ] !!! -> 2022-05-01 Something
    [ ] ..! -> 2022-06-15 Something else
    [x] .!! -> 2022-01-04 More text


I made this which is suitable for my needs when mixed with Obsidian. https://github.com/navjack/ConsoleJournal/blob/main/journal....


I ended up reaching a similar conclusion after I went looking for a todo app that suited my needs. I had very few requirements and I was surprised nothing satisfied them. I wanted something (1) that allows me to attach dates to tasks; (2) that lists tasks by date in a calendar; (3) that is local-only — not a web app, no cloud sync or anything, and not too many extraneous features.

I couldn't find anything that met those criteria without also having a bunch of extra features and a subscription service tacked on, and eventually I just wrote a script for scraping a text file and printing out all the lines tagged with dates (e.g. @jun-10) in order. That's the only real functionality I needed that a text file can't satisfy on its own, and it's been working great so far.


Yeah, I agree – as great as a separate file spec is, it’s only half the story without tools that provide useful functionality on top of it.

For my current purposes, it’s syntax highlighting that makes a big difference.


I’ve naturally developed a similar syntax to this and recently dumped all my notes into NotePlan 3. It’s been one of the best task management/note taking solutions I’ve found yet (not an ad, just an enthusiastic user!) With a little bit of find-and-replace in your favorite editor, you get great UX across platforms and all the benefits of plaintext without too many additions/deviations from standard markdown.

The one big addition I’d make to this syntax is a time estimate. I use the syntax ~15m or ~2.5h etc. With the autotimebox plugin in Noteplan 3, I’m able to automatically fill in blank space on my calendar with these as events. If things come up and the day doesn’t go as planned, I just run autotimebox again and it finds a new time for them


Wow such a coincidence! I recently toyed on such a spec for my shell prompt task manager https://github.com/netgusto/tax (I display it in my prompt and my tmux session bar, it's nice to keep current work in focus)

I'm certainly going to look into implementing the spec.

Some questions/suggestions:

    * do you plan support for text unrelated to tasks ?
    * do you plan support for sections / nested sections?
    * idea suggestion: in tax (linked above) we use markdown bold to notify "focused" tasks and sections, ie the one(s) that should be front and center; ex:
        - [ ] **This is a focused task**


> do you plan support for text unrelated to tasks ?

I haven’t thought about that much yet. I’ve tracked it here for it to be discussed: https://github.com/jotaen/xit/discussions/10

> do you plan support for sections / nested sections?

I think that would be cool and useful, but I need to play around with that more. There is already a ticket for it: https://github.com/jotaen/xit/discussions/2

> idea suggestion: in tax (linked above) we use markdown bold to notify "focused" tasks and sections

I think that’s similar to the priorities:

    [ ] !!! Do this


Nice, but (like most tools) misses the crucial feature of start (or scheduled) dates.

I think of one the best plain text implementations of a todo system is the one that is a bit hidden in the task plugin that comes with Zim Wiki [0]. It has start and due dates, nested tasks, priority flags, keywords (which can function as GTD states for instance) and tags.

  [ ] An example task with a @tag
    [ ] A subtask with start AND due date >2022-04-02 <2022-04-09
    [x] A prioritized subtask !
    [x] An subtask with higher priority !!
  NEXT Another task defined by a keyword
[0] https://zim-wiki.org


I haven't checked the Sublime package because I'm not very familiar with Sublime (anymore), but I have some experience developing VSCode themes. Did you need to use "tokens / scopes" to hack the colors? E.g. the color theme of the IDE (whatever theme the user is using at the moment) will paint variables in a certain color, functions in another color, arguments in a third color, etc, so you use regex to parse the text file, identify things that you want to color, then set them to be variables, functions, arguments, etc, so the text editor will give them different colors?


That’s how it works in Sublime, yes. You have a regex-based parsing engine that you configure via a YAML file, and there you assign scopes to the tokens.[1]

As a default, the [x]it! Sublime Package uses the available default scopes. The user can choose to override the associated colours in their local settings.[2]

[1]: https://github.com/jotaen/xit-sublime/blob/main/xit.sublime-...

[2]: https://github.com/jotaen/xit-sublime#syntax-highlighting--c...


Thanks, just to confirm: if you want the users to see nice colors out of the box (no matter what theme they use) without needing to customizing anything in their settings, then you'd have to utilize common scopes like variables / functions / errors in a hacky way, correct?


Yes. What I did is try to choose default (common) scopes that have a high chance of being coloured the way I want, e.g. for the `[x]` token I use `markup.inserted` which is for markup diffs, so it should be green. Or `markup.underline` for the headlines. But the options are pretty limited.


Looks like a decent format for human readability, but I think the more important things once you get more than 20 or so items are (a) maintaining, (b) rearranging, and (c) querying. You have to be able to remove completed items and move open items into different places. You have to limit the tasks you are viewing to those relevant in the moment. Perhaps there is a way to use an existing system like Taskwarrior to do the querying and rearranging.


Plain text rocks. After trying dozens of "productivity apps", I've settled on using two simple sh aliases:

alias todos="emacs -nw ~/todo.txt;" alias today="head -n 7 ~/todo.txt"

and a homegrown binary "todo" command that preprends its arguments to ~/todo.txt (more precisely, while ignoring the first two lines of the existing file, which say "TODO" and "----", respectively).

Missing: version control.


I do something similar but I include informational notes as well (not just action items/todo's).

  * incomplete todo

  ~ completed todo

  - informational
Each day I create a new note, titled by date. Grep the folder for topics or incomplete action items. No tooling or overhead needed. I have never felt the need to syntax "ongoing" or "obsolete" items. It's either open or closed.


It looks great, I'd have to give it a try to be able to have an opinion on it though.

Did you try PlainTasks? You might be able to borrow a few ideas from it too.

Congrats!


I like it, is very close to what I've been using to keep my own to-do lists: Instead of "[ ]" I just use "-" or "x".

The only thing I do that this doesn't mention is nested lists:

  [ ] This task has subtasks
      [x] Post about it on HN
      [ ] See if someone else already did


Nesting is currently being worked on https://github.com/jotaen/xit/discussions/2, as there are some questions to be figured out first.

(Note that the [x]it! specification is a working draft right now, it’s not supposed to be final yet.)


Kinda sorta related, on macOS, if you choose to store your Notes in a plain old e-mail server, they are stored as text files very similar to this.

Or at least they were last time I checked a few years ago. It was very handy to be able to access my Notes and lists from a regular old webmail interface.


https://github.com/Vhyrro/neorg is a neovim format inspired by org-mode. It should be easier than learning the real org-mode. The real-org mode is not that hard to use though IMO.


You do you, and thanks for sharing, but it'd be pretty tough to convince me Markdown isn't the right underlying format for whatever client or functionality you might want to build. See eg Obsidian and its amazing plugins to see what I mean.


One other small thought I have is about the name. It's common to use "xit" in popular JavaScript test framework like Mocha and Jasmine to indicate an excluded test. Could cause some ambiguity or an unwanted association.


Nice work! I use a obsidian with reminder plugin and I end up writing something similar:

- [ ] work (@2022-04-04) - [X] not work

I like the priority features though, didn't think of that, but I haven't needed it much (I try to keep them in order of priority)


I have a couple scripts that manipulate a stupidly simple "every line is a todo" format ".ck" file anywhere up from the CWD, combined with logic in my PROMPT_COMMAND to print the top item.


Dont dwell on choosing todo apps. Pick any reasonable one and use it alot. Habit > software.

The main thing you need is for it to sync. Text file and dropbox is fine.

The Microsoft one is pretty advanced and easy to use. That is my go to.


interesting, I also happen to switched to vscode to manage my notes and todos. I use Todo+ https://marketplace.visualstudio.com/items?itemName=fabiospa... for managing my todo list, what I like about todo+ is that it has simple formatting and I'm able to track start and end time of the task, it also has this little counter at the the top of the list to track finish/total tasks.


It's bullet journal notation meets plain-text format and I dig it.

I use pure text files for a lot of things, too, and I already use a similar system, but it's definitely more free-form.

Cool idea!


I think you should discuss pro/cons wrt/ other (more established) formats like todo.txt that provide a wide variety of tools.


Looks great, I am quite happy with todo.txt and all apps and tools available. Have you ever looked into that? It seems quite similar...


I thought of something similar, so I just write it in a YAML + Markdown format and push it to github as private publishing.


This is so wonderful! I hope it becomes a standard, and we get calandering/reminder type tools to work with it.


Heh - just did the same thing over the last week to compile my task list into trello cards to share out =)


I also have cycled through many todo apps and tried to make my own. I ended up using pen and paper.


How do the "tags with values" work? What is the intended use case?


It’s basically one way of allowing to create an information hierarchy, e.g.

    [ ] Work on #ticket=283
    [x] Buy new computer. #done=2022-02-24
Then you could query for `#ticket`, or for specific values of it. (Well, that is, if you had a tool for querying, of course.)


I have come back to plain text and sublimetext too. Simple and just works.


This is great! This is the nearly the exact format I’ve been using myself.


Obsidian is pretty easy to use to maintain a to-do list as well.


Great work on this — love the website demo!


What you didn't liked with todo.txt?


A few (cosmetic) details, for example:

- They don’t support multiline item descriptions. They actually prohibit that for a specific reason, because you can’t sort the lines lexicographically anymore. In my opinion, that should be an optional feature, however, which it is in [x]it!

- Creation and completion date are featured prominently, but I actually think they are not that important, and I’m not sure they are really worth some dedicated syntax. What I do find important, though, are due dates, and these are not natively supported in todo.txt

- I don’t like the notation of just preceding `x ` to the line for a checked item. It’s simple on the one hand, but it doesn’t look very tidy in the file.


Already allin on noteplan.


vi TODO


Why reinvent the wheel, when Org-Mode exists?




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: