org-rs: a faithful Org Mode parser translated from Emacs lisp to Rust

The problem: Org files are only parseable by Emacs

Org is a plain text organisational system, and the README lists the range of uses it claims: authoring, publishing, technical documentation, literate programming, task and time tracking, journalling, blogging, agendas and wikis. The obstacle the project names is not the format but its implementation. The standard implementation is the one written in Emacs lisp, and Org has a limited presence outside GNU Emacs.

Emacs is widely available and widely used as a lisp interpreter, so the argument is not that Emacs is unavailable. The argument is that there are applications in which using Emacs to properly handle and parse an Org file would be problematic. A web application reading Org documents, or a static site generator whose source is an Org file, cannot reasonably shell out to an editor for every request.

That is the problem org-rs sets out to solve: decoupling the use of Org from Emacs. The stated intention is to replicate the exact behaviour of Org as implemented in Emacs lisp, so that the same file produces the same result whether it is opened in Emacs or parsed by a Rust program.

The audience is therefore narrow and technical: people who maintain Org content for systems that are not Emacs. For an author who only ever works inside Emacs, this project solves nothing, and the README is candid about that limit.

Why a parser is hard: context sensitive syntax and no formal spec

The README gives an unusually clear account of why there are so few Org parsers, and this is the part worth reading before judging the project.

Org's syntax is not trivial, and most of it is context-sensitive, with only a few context-free elements. That raises the complexity of any implementation and makes testing awkward, because unit testing small chunks of Org code does not guarantee correct parsing of the Org file as a whole. A parser can pass every local test and still fail on a file where the same construct appears in a different context.

The second problem is that Org has no formal specification. The README explains that more ambitious projects try to cover all features, but since there is no formal spec they rely on observed Org behaviour in Emacs or on the author's intuition, and as a result they rarely get finished. Some attempts were made to formalize the syntax, and this project uses them as supplementary sources, with the contribution guide holding the details.

Both observations explain the design. A parser that guesses is cheap to start and hard to trust. A parser that mirrors a known implementation can be checked against that implementation, which is why the project chose translation over invention.

The strategy: translate the lisp rather than design a standard

The README states the aim plainly: a faithful one-to-one recreation of the Emacs lisp code translated into Rust. The stated benefit is that this approach sidesteps the problems of writing an ad-hoc parser and allows for easy adaptation if the official Org specification, meaning the behaviour of the reference parser, changes.

Four principles are listed as the guide for the work.

- Be a faithful recreation of the original implementation, not a competing standard or implementation. - Be standalone, embeddable and reusable. - Adapt to the users' needs, rather than impose adherence to specific ecosystems. - Be fast.

The first and third of those pull against each other in an interesting way. Fidelity to the lisp fixes the semantics, while the refusal to impose a specific ecosystem keeps the library usable from any host language or framework rather than tying it to one publishing pipeline. The second principle is what makes this a library rather than an application.

On prior art, the README names pandoc as the most faithful implementation not written in a lisp, and notes that org-ruby and pandoc chose to focus on a restricted subset of Org's syntax. The similar projects list also includes vim-orgmode, orgajs for nodejs, orgnode for python and org-ruby for ruby, with a link to a longer list of Org tools.

That comparison is the clearest statement of the difference in approach: other implementations narrow the syntax to something tractable, org-rs tries to cover it all by copying a reference implementation.

Why Rust, and what that buys a C-facing consumer

The design decisions section gives the reasons for the language choice. Rust is fast, memory safe, and has a healthy package ecosystem. It can also be linked both statically and dynamically against C code.

That last point matters more than it first appears. Org has no formal specification, and its de facto specification is the behaviour of the Emacs lisp code. The most direct way to check a Rust port against that reference is to run both over the same corpus of Org files and compare the results, and doing that comparison in one program is far easier when the port can be linked into a host alongside the original.

Two further decisions are about structure rather than tooling. The implementation adheres to the original Emacs lisp implementation in terms of structure and organisation, and adheres to idiomatic Rust everywhere else. The stated result is a clear scope and clear completion criteria, plus behaviour that is easily verifiable against the original.

The last of those is the important one for an adopter. A Rust parser that invented its own semantics would have no reference to be checked against. This one does, and the contribution guide in doc/CONTRIBUTING.org, along with the verification section the README points at, exist to support that checking.

One crate, two tasks: element parses and serialises

The roadmap is candid about scope. The element crate, in the rust/element directory, is described as currently the main and only focus, and it should perform just two tasks: generate a concrete syntax tree, and serialize it back to canonical Org representation.

Two tasks, and one is the mirror image of the other. Producing the tree is the parsing half. Serialising the tree back to canonical Org is what makes the library round-trippable, so a program can read an Org file, modify the tree, and write a file that Emacs will read back the same way. For an editor integration or a publishing tool, that round trip is the property that matters.

Everything else is described as not fully fleshed out. The README gives a few ideas for what a feature-complete parser would open up: parse tree manipulation tools such as exporting to other formats, a language server as a way to solve the matrix problem so other editors could have their own org-mode, and CLI tools with an ambition of integrating with TaskWarrior and using Org as its DOM.

None of that is built yet, and reading the roadmap as a feature list would be a mistake. The current deliverable is a parser library with a faithful serialiser, and the features above are directions rather than commitments.

The repository layout matches that narrowness. The top level holds doc, rust, a .travis.yml, an AUTHORSHIP.md file, a CLAUDE.md file and the LICENSE, with no packaging or release infrastructure beyond it.

What a user does today: the FAQ wiki and the contribution guide

There is no installation section in the README, and no command to copy. The project's own guidance for people who want to know more is to check out the FAQ on the wiki, and the README invites issues and discussions there.

Contributors are pointed at doc/CONTRIBUTING.org, and the contribution guide is also where the details of the supplementary syntax formalisations are kept. The README lists the kinds of contribution the project wants, and code is only one of them: documentation, verification, spreading the word, and using the project in your own project in an interesting way.

That list is a hint about how the project expects to make progress. Since the reference behaviour lives in Emacs lisp, the useful contributions from outside are the ones that check the port against it: corpus files, comparison results, documentation of differences. A contributor who reports a divergence between the Rust output and the Emacs output is doing the work the whole design depends on.

The realistic entry point for an adopter is therefore the rust/element directory and the wiki FAQ rather than a published package. The repository has no GitHub releases, so there is no tagged artifact to fetch and no version to pin.

Licence, activity level and the honest case for and against

org-rs is licensed under GPL-3.0, with the LICENSE file at the repository root. That matters for adoption in a way that is easy to skim past: a GPL library linked into your application carries obligations with it, and the README notes that the Rust code can be linked both statically and dynamically against C, which is a statement about the mechanics of linking rather than about the licence boundary. Whether that affects your product is a question for whoever handles licensing, not something the README answers.

On activity, the repository is not archived and the last push was on 2026-08-21. There are no GitHub releases at all, so the project has no published version history to point at and no upgrade notes. The CONTRIBUTING file, the FAQ wiki and the GitHub discussions are where change is communicated.

The case for the project is that a faithful port of a de facto standard format, validated against its reference implementation, is genuinely hard and genuinely useful for anyone who needs Org outside Emacs. The case against is that the surface area today is one crate with two tasks, the distribution story is a git checkout, and the absence of releases means every adoption carries its own integration risk.

If the alternative is to keep an Org-driven site tied to Emacs, org-rs is the option that removes that dependency. If the alternative is to live inside Emacs, there is nothing here to gain.

Editorial conclusion

Choose org-rs if you need to parse real Org files, with the full syntax rather than a convenient subset, from a system that is not Emacs, such as a content management system or a blogging backend, and if you can accept a library whose scope is one crate and which publishes no tagged releases. Do not choose it for Org export to other formats, for a language server, or for task tooling, since the README places those on a roadmap rather than in the code. Before adopting, read the FAQ wiki page, read doc/CONTRIBUTING.org for the verification expectations, and check the rust/element directory to see how far the parser currently reaches, because the project publishes no tagged releases against which to pin a dependency.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. org-rs/org-rs on GitHub
4. README