Mdo-cli NPM | npm.io

MDo

MDo is a simple, straight forward todo system based on markdown files. It has support for:

multiline tasks
future tasks (including start times)
recurring tasks
markdown headers

And not much else. MDo's goal is to be as simple and intuitive as possible while helping you organize your tasks.

Project Status
Principles
How does it work
Future and recurring tasks
FAQ
The cli
1. Installation
2. Usage
Development info
1. Getting Started
2. Unit Tests

Project Status

Deprecated.

I started using MDo to manage my personal to-dos around October 2018. I was happy while working at my laptop, but not so much when I was on mobile.

That's why I'm rewriting MDo in order to support both cli and mobile clients.

That work will probably take a while, and will live inside the mdo-org.

In the meantime, this repo and the corresponding npm repo will be kept around, but will receive no updates.

Principles

Plain text is the most portable format, so your todo system should use plain text over a proprietary format.
Tasks usually contain a title and body, so your todo system should allow multiline tasks.
You should be able to hide tasks you can't work on, until you can. Your todo system should help you with future tasks and task recursion.
Priority is implicit in a text file (tasks at the top are higher priority), so there is no need for your todo system to manage priorities for you.
Context can be easily added through markdown headers, so there is no need for your todo system to manage context for you. It should merely respect headers.

How does it work

You have a single file with all your tasks.

The file is parsed into blocks:

Any line that starts with - [ ] marks the start of an incomplete task block.
Any line that starts with - [x] marks the start of a complete task block.

Any line that starts with # marks the start of a comment block.

Example:

# Home                                            | << Start of comment block
This content is considered part of the comment    |
block. Use it to keep any information you'd like  |
hanging around.                                   | >> End of comment block
                                                  | <> Padding block
- [ ] Task title                                  | << Start of incomplete task
  Any content below the task title is considered  |
  the body of the task.                           |
                                                  |
  Feel free to use newlines, indentations, or any |
  other format you prefer here.                   | >> End of incomplete task
- [x] Some other task                             | << Start of complete task
  This task is considered complete.               | >> End of complete task
                                                  | <> Padding block
# Work                                            | <> One-line comment block
- [ ] Do something                                | <> One-line task

Future and recurring tasks

MDo supports adding metadata to your tasks by using tags. The following tags are supported:

@start: date/time when the task should start showing up in your actionable section.
@repeat: indicates how often the task should repeat.
@postpone: postpone lets you hide a task until a future time, without modifying the @start value.
This is useful for those tasks that recur based on start date, but for some reason you can't work on at this moment.

Examples:

- [ ] Pay rent
    @start 2018-09-01
    @repeat every month from start
- [ ] Take out trash
    @start today at 8pm
    @repeat every day from complete
    @postpone until Monday

You can find more documentation about tags in the wiki.

FAQ

How can I sync todos across devices

Since everything is contained in a text file, you can use any sync tool like Dropbox, Box, rsync, etc.

How can I handle multiple projects with MDo?

You can either:

use separate files for each project
keep everything in a single file, but use markdown headers to split tasks from each project

I personally use the multiple files approach.

How can I configure my editor to run MDo on save?

I can't speak for other editors, but this is the config example for vim:

" Note: the Preserve function is not technically needed, but will make your
" experience a lot better.

" Preserve()
" Restore cursor position, window position, and last search after running a
" command.
function! Preserve(command)
  " Save the last search.
  let search = @/

  " Save the current cursor position.
  let cursor_position = getpos('.')

  " Save the current window position.
  normal! H
  let window_position = getpos('.')
  call setpos('.', cursor_position)

  " Execute the command.
  execute a:command

  " Restore the last search.
  let @/ = search

  " Restore the previous window position.
  call setpos('.', window_position)
  normal! zt

  " Restore the previous cursor position.
  call setpos('.', cursor_position)
endfunction

" on save, run MDo on any markdown file living inside a `todo/` folder
augroup mdo
  autocmd!
  autocmd BufWritePre *todo/*.md call Preserve('%!mdo')
augroup END

PS: If you know how to get the same working on other editors, do submit a PR with the example.

The cli

Installation

npm install -g mdo-cli

Usage

# if you want mdo to read/write to a file
mdo path/to/your/file.md

# if you want mdo to read/write from stdin/stdout
echo "- [ ] take out trash @start tomorrow" | mdo

Whenever you run mdo, the file you provide is updated:

tags are normalized
tasks that are not actionable are moved to a "Future" section
tasks that were previously unactionable, but are now actionable, are moved into an "Inbox" section

You can find more info about the cli in the wiki.