<pclass="subtitle"role="doc-subtitle">An orgmode clone for neovim</p>
</header><p>
Timothy (<spanclass='acr'>TEC</span>) here. This month we have a guest post from a different part of the
Org ecosystem, to highlight one of the most promising efforts to provide a good
experience outside Emacs.
</p>
<p>
<divclass="link-preview"><ahref="https://github.com/nvim-orgmode/orgmode"><imgsrc="https://opengraph.githubassets.com/a9c7483d7e8b45a725f85fecc743be2e89b32477291ea94391e4fbede7ad09fe/nvim-orgmode/orgmode"/><small>github.com</small><p><b>GitHub - nvim-orgmode/orgmode: Orgmode clone written in Lua for Neovim 0.5+.</b></br>Orgmode clone written in Lua for Neovim 0.5+. Contribute to nvim-orgmode/orgmode development by creating an account on GitHub.</p></a></div>
</p>
<p>
“But I use Emacs, I don’t care” you may say. In that case, I’d like to point out
that wider spread and better Org support enriches the Org ecosystem as a whole.
It makes the format more approachable, and <i>useful</i> for other people. This is good
for everybody.
</p>
<p>
Without any further ado, here’s the guest post kindly written by Kristijan.
Enjoy!
</p>
<hr>
<p>
Like every beginner Vim user, at some point I ran into a usual editor war post:
Vim vs Emacs. At that time, I didn’t have an idea what “Emacs” was.
</p>
<p>
A simple Google search yielded something that seemed just like a very simple
editor with strange, but more familiar shortcuts. I didn’t bother too much to
figure out what it is, because I was already pulled in fairly deep into Vim and
One weekend, I was browsing through Vim subreddit, as I usually do at least once
a day. There was a post about an “Orgmode like task logging” plugin called
<ahref="https://github.com/dhruvasagar/vim-dotoo">vim-dotoo</a>. I opened it up, and I didn’t see much at that point. I wasn’t too
excited. I went through readme, and noticed that author (<ahref="https://github.com/dhruvasagar">dhruvasagar</a>) put a
fairly big emphasis on the “Agenda view”. I had no idea what “Agenda view” is.
Thankfully, the author also made a <ahref="https://www.youtube.com/watch?v=nsv33iOnH34">screencast</a>, which is rather long (1.5h), but
I had some time, so I went through it.
</p>
<p>
At that point, I was first met with “Capturing” and “Refiling”. <b>My mind was
blown!</b> What a simple, yet extremely powerful idea! How had that never crossed my
mind? From that point on, this plugin had my full attention.
</p>
<p>
I’m always emphasizing that <ahref="https://github.com/dhruvasagar">dhruvasagar</a> and his <ahref="https://github.com/dhruvasagar/vim-dotoo">vim-dotoo</a> plugin are most
deserving for having inspired <ahref="https://github.com/nvim-orgmode/orgmode">https://github.com/nvim-orgmode/orgmode</a>, and I
For some time, I was using <ahref="https://github.com/dhruvasagar/vim-dotoo">vim-dotoo</a>. I moved all of my Vimwiki notes to it. It
was a breath of fresh air. Alongside that, I started getting more interest in
the original Emacs Orgmode. I started noticing the differences, and some of the
missing features that were now looking quite attractive. I made <ahref="https://github.com/dhruvasagar/vim-dotoo/pulls?q=is%3Apr+sort%3Aupdated-desc+author%3Akristijanhusak+is%3Aclosed">few
contributions</a> to vim-dotoo. As time passed, and my notes started to grow, things
began being slow. I did some profiling, and figured out that it’s just a usual
Vim problem, Vimscript performance. It was just too slow for certain things that
Orgmode provides, and it would hardly get any better as more things are added.
</p>
<p>
Separately from Vim and Vimscript, <ahref="https://github.com/neovim/neovim">Neovim</a> was on a stable <kbd>v0.4</kbd> release, and <kbd>v0.5</kbd>
was still being developed. I was using Neovim from version 0.3, and was
carefully following the progress on it. Lua was introduced as a first class
citizen. A Bunch of new plugins arise from it. All the benchmarks showed that
Lua outperforms Vimscript in almost everything. Besides the performance, Lua is
a “normal” programming language, which means that support for it is much better.
</p>
<p>
At that point, I became curious: Could Lua be the path to the faster Orgmode? I
spent several days thinking about it. I wanted to give it a try. My biggest
concern was that I had absolutely zero experience writing parsers. I had never
written anything more complicated than an averagely complicated regex for
purposes of parsing. I noticed that vim-dotoo also used regex to do the parsing,
so that eased my mind a bit.
</p>
<p>
One weekend, I started working on it. It was really interesting and challenging.
I spent a lot of my free time on it. At certain points, it seemed like hacking,
since it was not a proper parsing. I tried to learn how to write a proper
parser, but it was just too time consuming and complicated. I proceeded with the
regex parsing to see how far I can go.
</p>
<p>
Besides parsing, I had a few more challenges to overcome:
<h3id="understanding-orgmode-syntax">Understanding the OrgMode syntax and all the functionality<aaria-hidden="true"href="#understanding-orgmode-syntax">#</a></h3>
<h3id="keeping-configuration-simple">Keeping configuration simple and familiar to Emacs OrgMode<aaria-hidden="true"href="#keeping-configuration-simple">#</a></h3>
<spanclass="org-string">"* %?\nEntered on %U\n %a"</span><spanclass="org-rainbow-delimiters-depth-3">)</span><spanclass="org-rainbow-delimiters-depth-2">)</span><spanclass="org-rainbow-delimiters-depth-1">)</span>
<h2id="first-release-orgmodenvim">First release of orgmode.nvim and introduction of tree-sitter parser<aaria-hidden="true"href="#first-release-orgmodenvim">#</a></h2>
After ~1.5 months I <ahref="https://www.reddit.com/r/neovim/comments/o8zp0k/orgmodenvim_orgmode_clone_written_in_lua_for/">published the initial version</a>. The focus was on Agenda and
capturing (<spanclass='acr'>GTD</span>), since those are the things I mostly used. It got some traction,
and people started testing it and reporting bugs.
</p>
<p>
One of the common questions was: <i>“Any plans to introduce tree-sitter parser?”</i>.
</p>
<p>
I knew about <ahref="https://github.com/tree-sitter/tree-sitter">tree-sitter</a> and used it in my day-to-day job for a few programming
languages, but I had absolutely no idea how it worked, and especially how to
write a tree-sitter parser. I put it aside, and continued working on what I
had.
</p>
<p>
One day, Emilia (<ahref="https://github.com/milisims">milisims</a>) contacted me via email to ask me if I would be
willing to try the tree-sitter parser she’s been working on for some time. I
gladly accepted. She gave me access to the repository, and I started tinkering
with it in a separate branch. No one was aware at that point that tree-sitter
support would happen some time soon.
</p>
<p>
After some time, I set up a “beta” branch called “tree-sitter” and <ahref="https://www.reddit.com/r/neovim/comments/ph2xqc/orgmodenvim_treesitter_support/">announced it
for testing</a>. Once the reported bugs slowed to a trickle, I merged it into the
“master” branch.
</p>
<p>
I believe that tree-sitter grammar for Org could help out other editors to
implement their version of Orgmode plugin, but I don’t think it would ever be
helpful for Emacs. Emacs parser is the one and only that has it all implemented.
Also, as much as tree-sitter is powerful, its main purpose is to parse
programming languages, which mostly has “static” patterns to match. Orgmode is
by its nature dynamic, which causes a variety of issues for a parser that’s not
(Neo)Vim is a great editor, but it still cannot compare to Emacs in certain
things. Manipulating the “View” part of the editor is tricky or impossible for
certain things.
</p>
<p>
I even <ahref="https://github.com/nvim-orgmode/orgmode/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aneovim-dependency">made a label</a> for reported issues where Neovim support for certain things
is a blocker. I’m hoping that at least some of these will be available in future
I will not go into too many details about the available features, since those
can be viewed in <ahref="https://github.com/nvim-orgmode/orgmode#features-detailed-breakdown">repository readme</a>, but I want to mention one feature that does
not exist as a built/-in feature in the Emacs Orgmode: <ahref="https://github.com/nvim-orgmode/orgmode/blob/master/DOCS.md#notifications-experimental">Notifications</a>.
</p>
<p>
This allows getting a “desktop notification” for tasks that are within
the specified threshold for schedule/deadline time. It requires some
configuration to set up a cron job, but it’s been working great for me
The current state of the project is very usable for me. I’m not lacking any of
the major features, mostly because I’m not used to using them. Nevertheless,
there are plans to add more things, and I’m getting a lot of help from the
community. I want to specifically mention <ahref="https://github.com/levouh">levouh</a> and <ahref="https://github.com/lukas-reineke">lukas-reineke</a>, since they
added a lot of value to the project, and I want to thank them and everyone else
who contributed. Their help is much appreciated.
</p>
<p>
There are few high priority tasks that I’m hoping to flush out first:
</p>
<ulclass="org-ul">
<li>Implementing <ahref="https://github.com/milisims/tree-sitter-org/issues/13">v1.0.0</a> release of the tree-sitter parser. This should allow for
faster and less error-prone parsing.</li>
<li><ahref="https://github.com/nvim-orgmode/orgmode/issues/26">Infrastructure for plugin developers</a>, to allow other people to build plugins
on top of nvim-orgmode.</li>
</ul>
<p>
And a long term goal for these:
</p>
<ulclass="org-ul">
<li>Tables support (and at least basic formulas)</li>
<li><ahref="https://github.com/nvim-orgmode/orgmode/issues/190">Org Babel like code block evaluation</a> (and hopefully basic support for literate
programming)</li>
<li><ahref="https://github.com/nvim-orgmode/orgmode/issues/195">Diary format dates</a></li>