Org for Vim
  |   Source

Recently, I shifted back to Emacs from vim. Part of what made this possible was noticing that adding some lines to my init.el would ensure that Emacs always started in evil-mode. Another part was the recollection of Doom Emacs as a vim-oriented build with some convenient CLI functions.

In general, I don't like Emacs. I find it buggy and it gets buggier the more packages you pull down. The philosophy of maintaining reliable packages Linux users come to expect from distribution package repositories isn't altogether followed. From past experience I know that using Emacs as a daily driver, it's only a matter of times before I get one of these less well-maintained packages and the bugginess becomes a deal-breaker.

That said, Emacs does have one very key advantage that vim lacks: org-mode. Using Org to track progress on programming and writing projects, scheduling with Agenda, viewing all todos across multiple files. There's a lot that Org does that would help me a lot in my day to day. Vim doesn't really have anything comparable to Org, except possibly using something like vim-org to handle syntax highlighting and running Emacs headless to process data from the file.

I feel like we can do better.

Usage Profiles

Emacs users aren't the same as vim users. It's not just a difference in modality or a preference for keychords or terminal versus GUI.

Vim is a text editor. It's only really interested in text editing, though there are plugins that cover things you might need while you have the file open, like linting and snippets.

Emacs may have started out as a text editor, but it has grown into a text editing platform. There are a number of tasks related to text editing, but not in the immediate province of the editor. This frontier is where Emacs excells beyond all competitors, including vim.

This editor versus platform difference shows in the usage profiles. A vim user opens a text file, performs some edits, then saves and exits. If they need to do more than edit the file, they rely on other CLI tools to accomplish this task. The Emacs user turns on the editor and spends the rest of the day in the editor, using various internal tools to replace the external tooling of the vim user.

Nothing inherently wrong or right about either approach, just differing philosophies. But, in my opinion: vim still does the text editing better, which is the primary reason for using the tool in the first.

Replacing Org

A vim approach to Org would be an external tool (or, more reasonably, a set of external tools) that understood the format and could perform the relevant data operations on specified files.

Example tasks would include:

  • Todo management

  • Task management

  • Agenda

  • HTML and PDF generation

  • Reproting

  • Literate programming

The tools should also be able to differentiate between a local project and the global list of projects.

So for instance, I might come to this project on my file system, switch to the development branch and check for todos and progress. But, while in that same directory maybe I want to look at my overall workflow and list of things I have to do today. Then, I could pass a flag to indicate I want a global view. The program would check all configured projects and collate the data and print with the additional information.

Literate programming is another area I would like to explore. It's also an area that I think even Org could stand for some improvement. Like, a project that has multiple files and code blocks that the system tangles and weaves for you.


The main issue with this project is the format. I don't think the Org markup language is the best for this task. I also think Markdown falls a ways short. ReStructuredText shows a lot of promise, but the one parser that really works isn't up to the task.

This brings me back to an old project that I've tried in a few different langauges, which never quite worked out: a reimplemntation of Docutils. Written in C++, Rust, or some similar lower level language, built specifically for the task of extracting data from .rst files and built in a way that's less temperamental and much faster than Docutils.

I like reStructuredText as a general format. As a markup language it does a much better job of standardize how to extend the language through roles and directives. But, Docutils itself is slow. It is especially slow when you start throwing something on the scale of a book of several thousand pages at it, which with my usage is what this would grow into over time.


Spitballing on Org todos, you might get something like this:

.. _slug-for-title:

Title for Display
:todo: outline
:deadline: 2022-02-03

Text to explain the thing we need to do.

.. todo:: Intemediary task

.. todo:: Intermediary task with a longer explanation

   And some more information about what we need to do.

Running the CLI over the project would like Title for Display as a task, with its current status, and the number of steps remaining as set by the todo directive. Calling it again in verbose mode would list the individual steps for the task and the full text explanation.


First step to doing this is to build a reStructuredText parser. I would probably build it using C++ since I need much better performance than Python and that is a language that makes a lot of sense to me.

I'm going to attempt literate programming using Emacs org for this project on the notion that it is something that'll migrate to its own tooling at some later date when everything is in working order.