Why and How I use “Org Mode” for my writing and more (2022)
evalapply.org
evalapply.org
Of all the giant blog posts I've written (brevity is not my strong suit), this one must have sent me the most traffic... Clearly there is a persistent unmet demand for Org Mode explanations / experience reports. Please write!
For non-Emacs users:
I've listed a bunch of alternatives that offer useful sub-sets of the Emacs version. On my Android phone, I use orgzly. I don't sync back and forth, preferring to hand-transcribe anything that is worth my while (I type fast enough on my computer). However it's good to know that my notes are just plain text, therefore always accessible.
Recent-most epic win of using org-mode:
Trivially exported the live demo version [1] of my talk [2] (org-babel) to a single web page [3] (reveal.js deck). It was a remote presentation, so it was great to be able to share the deck with the attendees.
[1] clojure-web-app-workshop-functional-conf-2025.org here: https://github.com/adityaathalye/slideware/ (see raw source for export directives)
[2] Talk video in this playlist: https://youtu.be/YEHVEId-utY (the playlist has video of the example I described in my blog post.)
[3] All blog posts are just tiny websites :) https://www.evalapply.org/posts/why-and-how-i-use-org-mode/d...
---
Edit: Discussed previously here: https://news.ycombinator.com/item?id=34967802 (164 points, 159 comments)
The ability to get on with life with the absence of global organisation is my saviour. While any given org file may be well structured, my org files directory is a disaster zone.
I just use rgrep and text search to get around. It's great!
I love org-mode with all my heart. I used it to run a consulting company for a decade and organize my entire life (reminder to mail my mom a birthday card? Recurring org task. Task breakdown and schedule for clients? Org.) I used it to keep all of my implementation and debugging notes. I’ve used it like Jupyter notebooks with inline code blocks. I’ve written tons of LaTeX math in it.
For what I use it for, Org has a ton of magic sauce that Obsidian doesn’t have for me. But Obsidian has one feature that, sadly, dominates all of that magic: ease of use on iDevices, including offline use.
I can sit and work on Obsidian documents on my iPad+keyboard on an airplane without Internet access. I can reference my documents and update my todo lists from my iPhone without needing to SSH somewhere. The sync service is super smooth and the (much smaller) set of features is enough for most of my daily use.
I miss org-mode very much though and if I were to change jobs and spend less time work-travelling I would probably switch back to it.
One of the biggest reasons that I was comfortable using Obsidian specifically is because the disk format is mostly just Markdown (mod the infinite canvas stuff, which is documented JSON). Being locally-stored Markdown instead of a proprietary format, I feel like there’s a reasonable pathway for me to reimport all of my notes back into Org-mode in the future if I decide to go that way (eg Pandoc)
I’d really like to use Org but that same limitation kept me from it. If I could at least view Org docs on the run, and do minor editing to jot quick notes, I think I could make the leap.
I just mentioned this in another comment here, but I think you would be interested too. I sync Org mode from the desktop to the mobile, and read in orgzly. To record things on mobile, I use voice notes. I'm right now working on a desktop application to transcribe and make voice notes accessible by other means as well. If you're interested then my Gmail username is the same as my HN username.
The Obsidian Sync stuff just works flawlessly for me across all of those machines.
Also it is a git repo and I occasionally check everything in and push it to my git server so that it acts as a sort of backup.
There are a few decent Org apps for Android that work with it. I've used Orgzly which is useful for simple notes and todos/agenda stuff. I use it for shopping lists.
However now with Emacs 30.x releases it has a official Android port. I have no idea how good it is. Haven't tried it yet.
My needs are filled with a ultra portable laptop, though.
Just as some examples: outline-centric without plugins (this allows functions like narrowing/hoisting to a particular part of the outline that you can't do in Obsidian), substantially better export/document authoring, org-babel (think Jupyter style notebooks or literate programming) integrated into the core concept, functionality integrated into the core system rather than siloed into plugins (org-agenda is essentially a combo of the dataview plugin and the todo plugin in Obsidian, but built to work together, and completely integrated with things like timekeeping/clocking for those who bill hourly, which is still missing from Obsidian). Plus some of the keyboard-centric stuff in org-mode is just really nice, down to little niceties like how you can manipulate dates and times without clicking around. Then there's all the benefits of emacs on top of that.
To some extent a lot of this derives from org's 22 year history. It's a very mature system, with loads of functionality.
One strength of Obsidian though is canvas mode. There aren't great emacs solutions like that at the moment.
I sync Org mode from the desktop to the mobile, and read in orgzly. To record things on mobile, I use voice notes.
I'm right now working on a desktop application to transcribe and make voice notes accessible by other means as well. If you're interested then my Gmail username is the same as my HN username.
A couple of alternative options, none of which are perfect, are using Termux with installed Emacs or Logseq, which supports org-mode syntax for files.
The same month this article was written (4/22) I tried to make the case for org as an interchange format for productivity tools [1] and pointed to most of the same tools supporting org. (Disclosure, my browser extension, BrainTool[2] is listed in the article). I still love the idea of a local-first, plain text model for sharing personal data across productivity apps, but three years on its not clear to me that the momentum has been maintained. Are folks still building new things on top of org?
[1] https://braintool.org/2022/04/29/Tools4Thought-should-use-Or...
[2] https://chromewebstore.google.com/detail/braintool-go-beyond...
IMHO, the integration of org-mode into Emacs is a double-edged sword. Great for me, because I get batteries-included writing support. /However/ terrible for distribution. The source code of the canonical implementation is the specification. Unfortunately, it is hardwired to the Emacs binary. That fact alone makes org text verboten to most of the known universe. Even if that weren't true, the absence of a standard makes it incredibly difficult for outsiders to maintain feature-parity of their own implementations with the canon, and with each other.
FWIW I use orgajs (https://github.com/orgapp/orgajs). Its well-supported and gives me a pretty complete AST. Highly recommend if you're working in JS.
https://orgmode.org/worg/org-syntax.html is the specification.
For that example, there's a file-local way to specify custom TODO keywords[^0]. Maybe that can get into the standard, but I'd be Ok with with a primitive, vanilla specification for org-mode first as striving to support everything would ensure no projects form around an emacs-free org-mode anytime soon.
---
I heavily abuse commit hooks in my hacky CI/CD pipelines though, so ymmv.
I have been using org-mode for nearly two decades. Org-mode itself has existed for 22 years (beating markdown by 1 year!). For something as important as an archival format, I wouldn't base my decisions on the vagaries of the latest trends.
BrainTool is a browser extension for managing tabs and bookmarks. It saves your data in an org file. One feature is to allow an item to be marked as a TODO. For me personally I then integrate my BrainTool.org file into my overall org workflow and see that TODO in my org-agenda. But ideally a naive BrainTool user would be able to see that task in a tool like Todoist or whatever.
For a while there it seemed like there was some momentum!
I regularly access and update my notes on at least 5 different devices, and I often need to share notes with non-technical people, where the barrier of entry needs to be nothing more than a single link they can click. Currently, Google Docs serves that need, but it's not ideal for writing.
The ideal solution for me would support using a Git service as the backing store, but the churn of making commits to synchronize has to not get in the way.
Alternatively: how about something like this:
- Stick the org source files in a private <Syncthing, or Dropbox, or equivalent> folder, so you can privately sync across devices.
- Use a file watcher to auto-export selected files to a shared version of the folder so you can share rendered content with others, with permissions. pandoc is an option but it doesn't export all of org. I think it's not a crazy idea to use Emacs itself as your command-line exporter. If you want special org sauce in the export, maybe pass the command line invocation a dedicated init file for export-only use.
- Further, because you are familiar with git, it may be not-crazy to run a Github/Gitlab/daemonised "render" action, on push to a remote repo. Once again, using the Emacs binary as the full-blown exporter.
An alternative is to use Git(hub) as the mediator, and here Orgzly is a decent Android app with Git support[1]. It just has a tendency of clobbering your git log with automatically generated commit messages. It has WebDav capabilities too, so you could use Nextcloud as the mediator instead.
There's also Syncthing, which is probably what everyone wants: all devices haves the same info, you commit to VC what you want when you want.
My personal workflow? Accept that my desktop is where I do the real planning, and that the mobile is just for quickly looking up stuff in my notes. If I have ideas, I can email them to myself and process them later when I'm back on my desktop. Is it perfect? Far from it. Does it work? yes.
I also have another set of notes that I sync with my phone and laptop via Syncthing, but that stuff isn't really using the more interesting org features, just quick and dirty notes. For anything serious it's just git.
But the main problem with it is Emacs. I want to use org-mode, but I don't need the hassle that is installing a decently configured emacs in multiple environments and platforms.
Eventually I just gave up and went full markdown first with Joplin and currently with Obsidian.
For your (very legitimate, "just gimme a distro") needs, perhaps Emacs Writing Studio could entice you back into the fold: https://lucidmanager.org/tags/emacs/
Note also that LogSeq is an org-mode based PKM (https://discuss.logseq.com/t/logseq-org-mode-compatability/8...)
I wanted to use orgzly or a text editor and just be able to write templates (in jinja2) or bash scripts to push data in or out of my notes.
Did they publicly establish that that the scoped storage is hurting their performance to an unacceptable degree, before making that choice?
What if users are not fine with that choice of giving a blanket approval to a closed source system.
There is no good reason why Obsidian needs to see more than its own files and the specific documents that the user wants it to see.
Would you trade absolute dogshit performance (looong delays for syncing notes between mobile and desktop) for privacy with a product you pay actual money every month?
Somewhere in there, I gave org-mode 2 or so years and eventually gave it up entirely; it just really plays SO un-nicely with literally everything else.
Anyone else looking for this sort of thing, I'd probably point to Obsidian first, but I'll probably stick with zim for the time being.
But they’re not easily interchangeable, so what you’re really choosing is not the syntax you want to use, but the environment and ecosystem of tools you want to live in. For example, compare org-mode in Emacs (decades of plugins, open source, TUI-oriented, very nerdy) to Obsidian (Markdown, pretty good plugin selection, closed source, GUI-based, approachable).
If I had to pick just one reason: Org-mode's much more regular --- and singular, unlike the many flavours of markdown --- syntax appeals to my sensibilities more. I linked to a post, which I agree with: https://karl-voit.at/2017/09/23/orgmode-as-markup-only/
Can I run source code blocks within a markup document?
I say this as an emacs user who uses org for my company notes.
I assume this is because most Emacs users, especially Emacs devs, disable the menu bar, tool bar, tab bar, scroll bar, etc.
> default keyboard shortcuts not working
Yeah, I think a new Emacs installation should prompt the user to choose between something like "Common keyboard shortcuts" and "Classic Emacs shortcuts". It would take me only a few minutes to set up all the common keyboard shortcuts for a new Emacs installation, but I think it should be just one setting.
Something that will never be adopted by 99% of folks is totally fine.
Most of my SW has less than 1% the adoption of org mode users (and thus less than 99.99% of the dev community will use it). Should I be concerned? Of course not!