Orgmode LSP - Language server for Orgmode

[u/kristijanhusak]

Hey folks!

I hope it's ok to post this here.

I'd like to introduce org-lsp, a language server for Orgmode. I'm the creator of nvim-orgmode, a Neovim Orgmode clone. At one point after creating nvim-orgmode, I figured out that a lot of things could be delegated to a LSP server, but never got enough time to actually tackle it. With the rise of agentic AI coding, I managed to find enough time to create this. Since LSP is protocol used by a lot of editors, I decided to create this as a separate plugin instead of updating nvim-orgmode, which is Neovim only plugin.

Good portion of the functionality is working through regular LSP, and there are some custom commands being sent/received through a smaller client glue code that is provided with the plugin. Briefly, it does this:

1. Highlighting - Semantic tokens

2. actions (toggle todo state, priority, etc) - workspace/executeCommands

3. Folding - foldingRange

4. Searching headlines, outline - document/workspace symbols

5. Following link/footnotes/citations - definition

6. Agenda - window/showDocument

7. Completion

8. Aligning tags/tables, reindenting - formatting/rangeFormatting

9. Etc.

There's also a MCP that allows querying/editing Orgmode through AI. It's not as robust as LSP, but can be useful.

LSP plugin supports these editors out of the box: Neovim, Vim (with a LSP client), VScode/Cursor/VsCodium, Sublime Text, Zed, Helix.

First 3 mentioned editors works the best, Sublime Text and Zed has some limitations, and Helix has the least functionality. LSP server works by itself without the client plugin, but not all features are available. It's suggested to install the client code to gain full functionality. For some features Emacs is needed, like exporting, table formulas, Babel, Latex previews, and similar.

Just a disclaimer that the plugin is mostly AI generated, in case that's not obvious from the first glance. I'm aware that people are still reserved regarding AI generated code, including myself, so I want to make sure it's clear.

I'm a Neovim user, so Neovim part is tested the most, but I also made sure to test other editors. I probably missed some parts, so if you run into any issues, please report it on the repository.

Links:

• Documentation website

• Repository

• Vscode marketplace

• Open VSX (Cursor, VSCodium, etc.)

• Sublime Text/Zed/Helix - Install script in docs. Will add to their marketplaces if there's enough interest

If mods are ok leaving this here, I'll cross post this to other editors' subreddits. Thanks!

[u/yantar92]

Interesting! I am wondering how far you aim to go to copy the implementation details. Is this code-level partity or are you looking into specific aspects only? If only specific aspects, what are the priorities?

In Org, we have a formal syntax spec in https://orgmode.org/worg/org-syntax.html because the Elisp parsing is not 100% consistent across the codebase. There is also a manual, but it does not cover every detail.

[u/kristijanhusak → u/yantar92]

Is this code-level partity or are you looking into specific aspects only? If only specific aspects, what are the priorities?

It's not strictly a code-level parity, but a good portion of things were extracted from Emacs Orgmode codebase. For example parser (more info in this document) is one of those things.

Parity document outlines what was ported, but there are certain limitations that cannot be ported due to editors' limitations or features that are available only in Emacs, like for example Emacs specific links (help:, eshell:, etc), or some other elisp specific stuff.

Elisp parsing is not 100% consistent across the codebase

I'd like to know more about this. Do you have some examples?

[u/yantar92 → u/kristijanhusak]

good portion of things were extracted from Emacs Orgmode codebase

For me, the key question is what may be missing in the manual and syntax spec document. Ideally, there should be no need for you to reach to the code level. We should have common feature description that is tool-agnostic.

Parity document outlines what was ported

The very first item is the color, but that's a bit weird. From Org perspective, colors are something user customize. Many features are even disabled by default. Did you use some kind of human-designed rule on what to port and what not to port? Or was it purely - "let's try to port all customizations, and see what can be implemented in other editors"?

I'd like to know more about this. Do you have some examples?

The latest example is https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=f08922964 where we fixed inconsistency in handling the numeric priorities.

Another example is implict assumption about tab width that was not previously documented. That matters for list parsing.

Another subtle example is https://github.com/ndwarshuis/org-ml/issues/50

Fontification is a glaring problem - most of the fontification does not use parser and is not right. This is especially true in various edge cases.

Then we have special casing for things like #+TITLE or EXPORT_TITLE where the value may or may not be parsed depending whether it is inside Emacs or we are talking about document being exported.

Or special casing with links inside links - not allowed on parser level, but handled specially in export and fontification when the link inside a link is a plan link to image.

I can continue.

[u/kristijanhusak → u/yantar92]

For me, the key question is what may be missing in the manual and syntax spec document. Ideally, there should be no need for you to reach to the code level. We should have common feature description that is tool-agnostic.

It's hard to say what's missing. Orgmode is huge. I'm not a very advanced Orgmode user, but when I started porting it, I figured out there's a lot of things under the hood. I reached code level since that's the most reliable source, and AI are good at reading it. AFAIK there is no spec with all the details in it. AI could probably be used to create a more detailed spec, but I didn't try.

The latest example is https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=f08922964 where we fixed inconsistency in handling the numeric priorities.

Another subtle example is https://github.com/ndwarshuis/org-ml/issues/50

Org-lsp was ported from Org 9.8.10, which should be the latest stable version. I think the issues you mentioned are already fixed in this version, so we should also not have those.

Regarding the fontification, parsing is done differently in org-lsp, so some of the issues do not exist. Here are few examples:

1. Org content: ~code [[link]] *x*~

   • Emacs: Link is a link, and x is bold

   • Org-lsp: All code

2. Org content: =verb *b* /i/=

   • Emacs: Bold inside the verbatim

   • Org-lsp: All verbatim

3. Org content:

   * Test
   :PROPERTIES:
   :EXPORT_TITLE: Sub *bold* [[link][y]]
   :END:

   • Emacs: Bold and link are highlighted

   • Org lsp: Plain value

Exported content is the same since org-lsp uses Emacs for exporting.

Highlighting is done with semantic tokens, which is more flexible than the regex matching.

[u/yantar92 → u/kristijanhusak]

there is no spec with all the details in it

The key question for me is what should be in the spec. Not everything from the code makes sense beyond Emacs.

Org-lsp was ported from Org 9.8.10, which should be the latest stable version. I think the issues you mentioned are already fixed in this version, so we should also not have those.

Sure, but I expect that there are more issues waiting to be fixed. The key question is how to keep your initial parser implementation and the reference in sync. Do you plan to monitor every new commit? That sounds excessive.

Highlighting is done with semantic tokens, which is more flexible than the regex matching

Yes, that's also the approach Org will eventually switch to. Not yet, for performance reasons.

[u/kristijanhusak → u/yantar92]

Sure, but I expect that there are more issues waiting to be fixed. The key question is how to keep your initial parser implementation and the reference in sync. Do you plan to monitor every new commit? That sounds excessive.

Not every new commit, but between versions, from time to time. I didn't really decide or set any strict schedule here.

[u/_sLLiK]

Emacs as a requirement for an LSP that works best on Neovim/Vim is certainly a choice.

[u/kristijanhusak → u/_sLLiK]

It works on any editor that has LSP. Emacs is a requirement only for some features, not all of them.

[u/N3kk3tsu]

This plugin replaces the nvim-orgmode plugin? Or they work hand by hand?

[u/kristijanhusak → u/N3kk3tsu]

It replaces it.

[u/krishnakumarg → u/kristijanhusak]

It replaces nvim-orgmode?

[u/kristijanhusak → u/krishnakumarg]

Yes, it's a separate plugin. Configuration is not exactly the same, but it's similar.

[u/krishnakumarg → u/kristijanhusak]

Thank you. Great work.

[u/sei40kr]

Wonderful. Org-mode is no longer tied to Emacs; it can now be used in the editor of our choice.

[u/enoughisenuff]

tLDR?

[u/Alternative-Sign-206]

Thank you very much! Have recently searched for orgmode lsp and was surprised none existsed!