Org Mode Syntax Cheat Sheet (2017)
nhigham.com
nhigham.com
My Glossary:
- <<<Martin Prince>>>: Smart guy, gets bullied a lot Nelson Muntz
- <<<Nelson Muntz>>>: Troubled guy, does a lot of bullying to Martin Prince.
Watching the Simpsons, Martin Prince seems to get into a lot of altercations with Nelson Munz.
You can click on that highlighted text to jump to where it was first defined.
For something similar to what you're asking, I would just go for something like...
The <<<bbc>>> ([[https://www.bbc.com][site]]) is the UK's state broadcasting company. Now when I write bbc (or BBC) these will be highlighted as links and will take you back to the Radio Target in the first sentence and I can then click on the link
Also note that you can mark a word or region and then hit C-c n r (org-insert-radio-target-brackets) to surround it in angle brackets and enable it as a radio target.
(defun org-insert-radio-target-brackets (start end)
"Wraps a region with angular brackets to create a radio target."
(interactive "r")
(save-excursion
(goto-char end)
(insert ">>>")
(goto-char start)
(insert "<<<")))
(keymap-set org-mode-map "C-c n r" #'org-insert-radio-target-brackets)
Here's how I defined it.
(defun org-insert-radio-target-brackets (&optional arg)
"Surround selected text with Org Radio Target angle brackets (eg. <<<arg>>>) and then find and update all radio targets"
(interactive)
(progn
(insert-pair arg "<<<" ">>>")
(org-update-radio-target-regexp)))Roam Research, what it’s based on, might also be of interest.
Basically, think Org Roam, just with Electron instead of Emacs.
Personally, I like to create custom ids for bullet points so that I can easily change the text in the bullet point later without breaking my links:
* My bullet point
:PROPERTIES:
:CUSTOM_ID: foo
:END:
Elsewhere, I can just write [[#foo]] to create a link to that bullet.
Org mode is a bit of a mystery to me thus far, collapsible sections are great but could you expand on what is so helpful to you and how you use it?
Keeping notes. Org Mode doubles up as an Outliner. You can keep hierarchical notes in a single large file. You can mix-in tables (with support for LISP formulae) for tabular data. You can embed images and LaTeX too. You can convert your notes to HTML or Markdown in a jiffy. There are shortcuts for instant note taking. You can archive sections that are no longer required.
I have stopped using mindmaps and now rather rely on Org. It can handle tree-structured information very well.
As a calendar. You can also add diary-remind reminders. Remember one's wedding anniversary (and Spouse's birthday) to save one's marriage.
As with everything in Emacs, configurable and extensible (with ELisp). Almost every method and every variable is Global. This is of course crazy, but the power that this proffers is enormous.
I learn something new about Org Mode every now and then. I do not consider myself as a power user, as I am sure there is still much left to be explored.
This flexibility means you can bend it to rather odd requirements. For example, in my current job I'm required to track time against project codes, but I have to scale the proportion against the hours I'm contracted for (it's a tax thing, I'm told). Org supports clocking in/out of things. It doesn't know what those things are, they are just items in the outline. So I structure my todos under the project codes then track time against those tasks or just directly to the project. Then I have an agenda view which shows me totals for each project and a column scaling the proportions to the total contracted hours over the period.
But you might have completely different requirements. You might want a flat backlog and to "refile" tasks into "sprints" when they get properly defined then set a deadline on the whole sprint. Org supports it all because it doesn't really care that much. Seeing people struggle with the likes of Jira becomes rather comical.
My big blocker is that a significant portion of my time is on a phone rather than a computer these days and I have to think that all the chording with Emacs would get impossibly cumbersome.
Anyone here have a good way to leverage Emacs on the go?
I sync org files to phone (using Syncthing) and use Orgzly to access these from Android. Although it is possible to install Emacs in Android as a terminal tool in Termux or even as a GUI tool, you need to connect a keyboard to do something sensible. Long story short, if your phone is your daily driver, Emacs may not be for you as it is keyboard oriented. But if you are a computer person who occasionally uses the phone, there are ways to get by.
Neither are full org mode, but good enough for reading notes and minor edits/captures on the go.
This was new to me. Can install with F-Droid or support the author by purchasing from an app store.
FWIW, it seems Emacs can now be built for Android natively - there seem to be related files and documentation in the main Emacs repo, though I haven't actually built it myself, so I don't know how well it works.
That being said, it is not perfect. My ultimate (and imperfect) solution was to acquire a GPD Micro[1]. Now that thing makes up for all shortcomings of mobile devices, not just Emacs :)
[0]: https://f-droid.org/en/packages/com.madlonkay.orgro/ [1]: https://gpd.hk/gpdmicropc
I have one, but coming from a tiling wm, and Vim I have a hard time imagining using it productively. It is in my sell pile.
I barely see the desktop TBH. It is there just so I have convenient control of peripherals. 99% of my time is in Web browser or Emacsclient or Terminal. On GPD I use the browser even less, because its purpose is to be a lightweight mobile terminal. Graphical Emacs is just superset of terminal one, so it is preferred is all.
For someone who is disciplined, organized and feels limited by their current tooling, Emacs will probably work great like these anecdotes. If having the discipline itself is a problem then Emacs is probably not the right choice to start with because of the learning curve and the friction due to sub-optimal experience on phone.
That said, I do recommend to give it a go. On Android, Orgzly + Syncthing is good enough to get started.
- Actual emacs as a client strongly preferred; don't assume anything else can correctly parse org-mode - Sync between Windows, Mac OS, Linux, Android - Don't force me to remember to sync, so `git commit`/`git pull` or `rsync` isn't viable unless it's completely hidden - Don't allow me to overwrite the file if the sync has failed - Work from an ssh terminal
The closest I got was `crdt-mode.el`. That gives me real-time updates between connected clients. It needs some UI polish around connecting and disconnecting, but it's nothing unworkable. I can get to it on Android via termux ssh to emacs running in tmux on an always-on raspberry pi in my office. That's just about ok in terms of key chording for most things. You do lose some capabilities. I've contemplated getting a bluetooth keyboard for these situations but obviously that's not usable in a lot of situations you might want to be taking notes in. I got in the habit of using the very top of the file as a dumping-ground for one-liners from mobile because sometimes that was just easier than anything else. If I was feeling particularly keen I might try something in the spacemacs vein to make the key combinations work better on mobile. From memory org-agenda was fine, so I tended to use that as a default view for TODOs.
What's annoyingly broken is having Windows in the mix. There's something not quite right about the way `crdt-mode` handles line endings which means updates from Windows mess up the other copies, and given how much org-mode relies on line endings it can completely break whole sections at a time. I ended up using the version running on SSH from Windows too, but there are a couple of chords which Windows Terminal mucks up. That bit's not great.
Take Windows out and sshing to a shared terminal emacs instance running in `screen` is worth a try, with the caveat that you will have to rebuild the muscle memory for the chording on mobile. The termux keyboard has a couple of niceties that the default Android one doesn't, without which it would be a complete non-starter.
I still use org mode to write my blog and journal but my knowledge management is all in Roam.
I'm not an org power user (yet), but I find this iphone app works great to quickly add todos, view outlines, see my agenda, etc whilst I am out. I have it synced via Dropbox so when I get back to my desktop everything is waiting to be properly organized.
The phone did make it a little challenging but before that I used a notebook and dumped it into org at the end of the day. I've been doing something similar with my phone now.
A lot of people refer to org-mode as the gateway drug for Emacs and it truly is that.
probably the nicest part of org is that you don't pay for things you don't use - using it as a just a nice way of organising bullet points works fine, and then there are a jillion optional features around it.
You start off first writing simple outlines, and then you start creating todos, and then maybe you start to look at agendas to organize your todos (note: I rarely do this).
The biggest game changer for me was org-roam. It's essentially a database of all my files where I can add snippets or link to other files, or whatnot.
The TODO stuff I use a rough general guide of where I am, but I do not strictly adhere to it.
Essentially: Make Org-Mode work for you and your mindset, don't feel the need to bend to it.
do you know good videos of people demonstrating their workflow habits ?
1. "Huh, I wonder at what point SSDs of today are comparable
to RAM speeds of yester-year?"
2. `C-c n c` (create-node) "ssd_ram_yearly" (title)
3. (a document spawns) "\* SSD vs RAM comparison" (I give it a
better unofficial title)
4. I do googling, drag and drop images into the document (org-download
is a must have)
5. Satisfied with the document, I decide to link it to a
parent node
6. `C-c n i` (insert node) "random_thoughts"
7. If the random_thoughts node exists, it just links, if not, it
creates a new document which I can fill out, and then `C-c
C-c` to complete it, and then it links back to the ram document.
8. I finally do `C-c C-c` to complete the original ram document.
1. "Huh, what was I thinking about again?"
2. `C-c n f` (find node) "random_thoughts"
3. `C-c n l` (show backward links) a new buffer pops up showing
all files that link to random_thoughts, and I click on
the Ram ssd one.Alternatives like Asciidoc are not perfect, esp for literate programming, b/c it's also kinda complex and so it also only has one backend (that's runnable from Clojure through JRuby!). I imagine a simpler multi-backend solution like Djot will be the future most likely. Bloated underspeced markups are on the way out.
Because I don't like emacs and I wanted to lean on command line apps for getting data into and out of my orgzly org-mode electronic brain, I've been doing this by combining orgmode with jinja2 (I do this with a cli app I wrote called 'orji').
I think it's a very powerful combination. I use it to generate latex/html/whatever and short bash scripts which are then run. E.g.
* Generate my CV using a latex CV template I found on overleaf that I converted into a jinja2 template.
* Send the contents of a TODO note tagged 'sendemail' as an email with a tiny templated bash script.
* Create jira ticket with the details of a note.
* Generate reveal.js presentations.
All from my phone, using orgzly and one big button which runs a single termux script that seeks out TODO notes with labels (e.g. cv/sendemail) that match the scripts in my library (cv.sh / sendemail.sh).
jinja2 certainly has the capability to end up creating a huge old mess if you abuse it, especially to generate code, but I find that using it to template tiny 5-6 line bash scripts or a latex or an HTML file hits a sweet spot of usability and flexibility.
My favorite is Org Babel (jupyter notebooks on steroids) that can be used for literate programming that you mentioned (reproducible research, devops-y tasks).
Publishing is just one of many applications. There are certainly cases where you might want a more specialized tool.
It's true that Emacs is the canonical Org-Mode compiler, but there are many other compilers, including Github pages. If it's typesetting you want, the support is widely available. If it is org-mode-powered workflows (like TODOs etc.), then support outside of Emacs is narrower, but still quite serviceable [3].
---
[1] built with OrgMode and pandoc: https://www.evalapply.org/
[2] pandoc as compiler FTW. https://github.com/adityaathalye/shite/blob/b4163b566f0708fd...
__shite_templating_compile_source_to_html() {
# If content has front matter metadata, it is presumed to be in a format
# that the content compiler can safely process and elide or ignore.
local file_type=${1:?"Fail. We expect file type of content like html, org, md etc."}
case ${file_type} in
html )
cat -
;;
md )
pandoc -f markdown -t html
;;
org )
pandoc -f org -t html
;;
esac
}
If I wanted to emulate a fraction of org-mode features I use daily in markdown, I would have to use Obsidian with a bunch of plugins, and we would end up in same boat.
I don't know the exact spec situation, but I know that comprehensive parsing libraries in modern non-elisp languages exist. An org-mode contributor has one in Julia[1], another in Dart[2] that powers a Flutter app, and there are many tree-sitter grammar based tools that are useable from neovim (e.g. [3]). The basic org2html or org2pdf CLI needs are already addressed by Pandoc.
[1] https://github.com/tecosaur/Org.jl
Would it be neat to have an alternate complete implementation of org-mode elsewhere? Sure. But unlike say Photoshop, Emacs is already open and extremely hackable. That mitigates most of the reasons you would want to.
Org is hardly more tied up to the editor than any of the many other formats people use – all of these have more or less complete editor support depending on what features you need (e.g. if you start doing fancy literate programming in markdown, or azathoth forbid, try commenting out lines, you'll find spotty support in at least some of the existing implementations). And if you like the full combination of features that Emacs+Org gives you, you'll be hard pressed to find another environment to replace that, so ... why bother?
(OTOH if you only need some minor part, like html export, and you have to work with people already using other formats, then those other formats might be better.)
For better or worse, Org Mode is a feature-rich application, and org mode format is markup tied to that application. Using it as general-purpose markup is kind of a nice side effect of it being plaintext, and that even the portable subset is more feature-rich than most markup alternatives.
For full compatibility, you'd have to port Org Mode to different editors, in the same way you'd port a native app between OS-es. Org Mode is very much an application that's making full use of its platform's specific features and APIs, except here the platform isn't Windows/Win32 API, but Emacs/Elisp.
I also cut my teeth on Elisp when ChatGPT was new, and it was very helpful.
This seems to be subtle but it results in many misunderstandings and unnecessary discussion issues.
To "solve" this situation, I tried to coin the term "Orgdown" for the syntax alone: https://gitlab.com/publicvoit/orgdown/ and https://karl-voit.at/2021/11/27/orgdown/
There are many use-cases to use Orgdown outside of Emacs and there are many tools that support Orgdown already: https://gitlab.com/publicvoit/orgdown/-/blob/master/doc/Tool...
Although I'm using Orgdown and Org-mode for over a decade, I do think that even with an objective point of view, Orgdown does have its benefits from a syntax definition point of view in comparison to Markdown and other lightweight markup languages (LML): https://karl-voit.at/2017/09/23/orgmode-as-markup-only/
Oh and btw, the linked cheat-sheet covers only the most basic Orgdown syntax elements. Within the Orgdown concept, I defined misc "levels" of syntax elements, starting with OD1: https://gitlab.com/publicvoit/orgdown/-/blob/master/doc/Orgd... This also serves as some sort of cheat sheet I guess.
HTH
Some 15 years ago I started using Orgmode heavily. But a lack of a mobile solution and it not being available ubiquitously made me go back to Markdown and Obsidian for note taking and Kanban boards in Notion for task management.
Markdown is available everywhere. In forums, in chatgpt, in any kind of text editor.
So although I still use Emacs, I stopped (heavy heartedly) using Orgmode.
#+BEGIN_QUOTE
#+END_QUOTE
A titan in his niche.