# The Magnificence of Org > Published May 05 2024, last updated Apr 04 2025 > By Ryan Fleck and written without LLMs! > Original post at > An article of astonishing quality and insight. Happy Hacking! Of all the productivity and thinking tools I've come across, *all* shake and tremble beneath the brilliant and towering presence of [org-mode](https://orgmode.org/) in all of my note-taking, organization, scheming, and tinkering. Over the past four months, my workflow has entirely surrendered to the insanely flexible power of the [EMACS](https://www.gnu.org/software/emacs/) text editor and community-driven libraries. ...that is exceedingly high praise for a text editor. I promise by the end of this article I'll at least have you curious about this **profoundly excellent system** for managing your thoughts, work, and life.
![My own Org-Roam notes network, visualized with [org-roam-ui](https://github.com/org-roam/org-roam-ui)](/org/my-roam.png?invert=true) {{< toc >}}
> Org is a highly flexible structured plain text file format, composed > of a few simple, yet versatile, structures — constructed to be both > simple enough for the novice and powerful enough for the expert. > ([src](https://orgmode.org/)) > Nearly every Org user has a story to tell about how Org enables and > empowers them — some have found it so useful that they have written > [(scientific) papers](https://orgmode.org/worg/org-papers.html) > about the value of Org for conducting reproducible research. > ([src](https://orgmode.org/)) {{< jumper >}} # What is Emacs? What is Org-Mode? **Emacs** is a text editor[^2a] and **Org-Mode** is an operating mode[^3a] for the editor. Emacs is special because it is built around an interpreter for a programming language called [Emacs Lisp](https://www.gnu.org/software/emacs/manual/html_node/eintr/Preface.html), a functional programming language that enables developers to write very powerful and flexible programs. Because the editor is a Lisp program, it is very easy to update the program while it is running, allowing a user like you to **change the editor as it is running**. This venerable text editor is an extremely long-lived[^4] community project. EMACS will certainly outlast all other text editors. It first emerged in 1976[^5], and its record of published versions (starting with 13) goes back to 1985[^6]. When I was born, the current release was 20, and now we're up to 29! **Org-Mode** is automatically started when you begin editing an `.org` file in EMACS. Org files are a lot like Markdown files - everything is in plaintext, and the files can be read easily by people with any editor. In other words: *the data is completely within your control, and can be viewed and modified with or without a copy of the org program.* By contrast, files in Word or OneNote are tough to decipher if you try to open them without the programs that created them. Together, **Emacs** with **Org-Mode** is powerful enough, but as stated earlier, it is extremely easy to customize the Emacs editor to your taste on the fly. If you've read or written Racket or Scheme before, Emacs Lisp (elisp) will be very familiar to you. The [manual](https://www.gnu.org/software/emacs/manual/html_mono/elisp.html#Introduction) may help. The syntax for lisps is simple: ```lisp ;; Comments start with semicolons ;; A lisp form (function-name argument-1 argument-2 argument-3) ;; Placing a ' at the start of a form makes it a list ;; and informs the compiler "evaluate this form as data" '(1 2 3 4 5) ;; Refer to functions outside of calls using #' (apply #'function-name 1 2 3) ``` ...apart from macros, that's all the syntax there is. Nice, right? With this programming language, you can build modes or extensions for the Emacs editor. Even faster libraries from any compiled language are easy to call. The ease of working with elisp allows the editor and the libraries you install to conform to your habits and taste, making the living systems created with Emacs very personal. # The Org File Format Org[^7] is a lot like Markdown - a simple, clean, plain-text format that can be read and modified with any text editor. This said, org files really shine when used with the Emacs editor and the org-mode package, which enables a myriad of magic tricks to kick your productivity to the next level. Let's start with the basics. I'm sure you can pick this up in no time at all: ```org #+TITLE: Your Document Title * This is a Headline This is just some ordinary text under the first headline. ** This is a secondary Headline # This is a comment and won't be exported. You can mark up text in *bold*, _underlined_, /italic/, +strikethrough+, ~inline code~, =emphasis=, and other ways. - Lists are great and there are lots of ways to manipulate them - They can also be collapsed 1) They can have a variety of 'bullet' types or numbers 1. It is easy to cycle through bullet types - [ ] Lists can have checkboxes - [X] And they can be /checked!/ * Tables You can modify simple ascii tables like these | Property | Value & Notes | |-------------------+-----------------------------------| | Membership Number | UCP-1284980 | | Expiry Date | 31/01/2027 | | Constituency | Eagleduck-Cowsnake | * Code Blocks I know this is more complex than markdown's triple-backtick to type, but there are lots of shortcuts to do this fast! #+begin_src lisp ;; Guess my Number Game ;; Define global variables (defparameter *small* 1) (defparameter *big* 100) (defun guess-my-number () (ash (+ *small* *big*) -1)) #+end_src Of course, org files have support for a lot of other cool things, but this covers the =bare necessities=. ``` In Emacs, pressing `TAB` with your cursor on a headline will collapse it, giving you more room to focus on the idea at hand. `SHIFT-TAB` will cycle all the headlines into a few different visibility states: just the first-level headlines, all headlines (but still no content), and all headlines and all content expanded. The ability to view just the headlines makes it easy to pick out a section. # Storing Knowledge as Plaintext There is a tremendously philosophical aspect to computing in this manner, and I hope you'll understand the gravity of this idea: **Plaintext belongs to you.** By storing things in plaintext, you'll never lose access, you'll always be able to rebuild whatever functionality was lost, and most importantly, you have **complete control over your tools** and the **fredom to choose** them. Plaintext has _longevity_ - you can read and write plaintext with an _innumerable_ number of programs. You can easily reprocess plaintext into a variety of other formats and websites with ease. The stuff you write is *fundamentally yours* as if it were written with a pen on paper. Locking your wisdom and data in a proprietary format makes it difficult to synchronize and share, and makes you dependant on large companies that positively _hate your guts_ and see you only as _ad-rev dollars_. Do you really trust those eyelidless staring bureaucratic nether entities with your notes? Now that we're through the metaphysics - _let's get on to the fun stuff!_ # Capture Ideas As They Appear Have you ever been working when a distracting or urgent task comes to the fore and shatters your train of thought? Imagine if you could simply and safely file that thought away and immediately continue with the task at hand. This is the use case for a bit of Emacs functionality called **capture templates.** The code below may look like a jumble of lisp at first, but here's what it really says: The user sets the configuration for the variable `org-capture-templates` to include two different capture commands: 1. An **Events** capture template that saves whatever you type in the capture buffer as a new headline in the file `events.org` 1. A **TODO** capture template that saves whatever you type in the capture buffer as a new headline in the file `todo.org` ```lisp ;; Org-Capture Templates (setq org-capture-templates '( ;; Events ("e" "Event" entry (file "~/org/events.org") "* %?\nAt: %T\n%i" :time-prompt t ;; :jump-to-captured t :empty-lines 1) ;; TODO Entries ("t" "Todo" entry (file "~/org/todo.org") "* TODO %?\n %i\n %a" :empty-lines 1))) ``` When interrupted by a call to join an event, or the idea that you must complete some chore today, simply typing `C-c c` and `e` for event or `t` for todo will open a capture buffer where the idea can be captured and unceremoniously forgotten until later. # Execute Code Blocks in Any Language [Literate programming](https://en.wikipedia.org/wiki/Literate_programming) was first conceived by Donald Knuth in 1984 and involves the interleaving of a program with its documentation, enabling more thorough explanation to be presented alongside source code. This is most popular today in the form of *Jupyter notebooks* for enabling data science and machine learning in Python. _Allow me to shout this ultra cool feature from the rooftops:_ **Org enables you to execute any[^1] language inline!** This means you can mix all of your favourite languages in a single file and have the output for each execution *printed directly and effortlessly back into your org file*. In the editor, an inline code block looks like this: ```org *car* grabs the first element of a list. #+begin_src lisp (car '(pork beef chicken shrimp)) #+end_src ``` You only need to hit `C-c C-c` to execute it, or any code block, with its language of choice and have the results printed immediately below the inline code: ```org #+RESULTS: : PORK ``` Here's a second example with some inline Clojure: ```org *get* allows you to grab keys, and can return nil or a default: #+begin_src clojure (get {:x 1 :y 2} :y) ;; => 2 (get {:x 1 :y 2} :z) ;; => nil (get {:x 1 :y 2} :z 3) ;; => 3 #+end_src ``` ```org *get-in* allows you to dig into nested maps: #+begin_src clojure (get-in {:head 1 :chest {:ribs 10 :cavity {:heart "pumpin'" :lungs 2}}} [:chest :cavity :heart]) #+end_src #+RESULTS: : pumpin' ``` My work-in-progress [Clojure manual](https://manuals.ryanfleck.ca/clj/) is actually an org-mode file. I'm not just writing code on the side and pasting it into the file - the file itself has a first-class connection to the REPL. By using org, there is no difference between programming and writing the aforementioned webpage for my own future reference. With the **tangle** command, you can extract selected code blocks into an external script, enabling the writing of complex code within a system in a literate manner. _Aside: Some people even write their [EMACS settings in an ORG file](https://ryan.himmelwright.net/post/org-babel-setup/)._ # In-File Tables & Table Formulas Not only does org make it easy to create and navigate tables in plaintext, but it provides an easy way to write formulas that can be applied to these plaintext tables! Here's an example of a simple table I have: ```org | Date | Service | Cost | |------------------+-------------------------------------+--------| | [2022-10-05 Wed] | Oil Change | 0 | | [2023-05-23 Tue] | Oil Change & Recall | 0 | | [2023-09-25 Mon] | Oil Change, Trans. Fluid, Brakes | 674.30 | | [2023-11-29 Wed] | Self: Antifreeze fluid, air filter | 68.72 | | [2023-12-02 Sat] | Self: Rust Inhibitor, Chip Paint | 70.04 | | [2024-01-03 Wed] | Fix chip in windshield | 15.73 | | [2024-02-14 Wed] | Oil Change & Cooling system service | 281.96 | | [2024-04-15 Mon] | Travis - Inspect Pothole Damage | 50.00 | | [2024-04-26 Fri] | Replace Stabilizer Links | 376.08 | ``` ...what if I want a running total of how much I've spent on my car? Using [Emacs Calc syntax](https://orgmode.org/manual/Formula-syntax-for-Calc.html), I can do this by adding a column, typing `C-c =` to add a formula for the column, and using the formula `$4=vsum(@I$3..@$3)`. ```org | Date | Service | Cost | Total [c] | |------------------+-------------------------------------+--------+-----------| | [2022-10-05 Wed] | Oil Change | 0 | 0.00 | | [2023-05-23 Tue] | Oil Change & Recall | 0 | 0.00 | | [2023-09-25 Mon] | Oil Change, Trans. Fluid, Brakes | 674.30 | 674.30 | | [2023-11-29 Wed] | Self: Antifreeze fluid, air filter | 68.72 | 743.02 | | [2023-12-02 Sat] | Self: Rust Inhibitor, Chip Paint | 70.04 | 813.06 | | [2024-01-03 Wed] | Fix chip in windshield | 15.73 | 828.79 | | [2024-02-14 Wed] | Oil Change & Cooling system service | 281.96 | 1110.75 | | [2024-04-15 Mon] | Travis - Inspect Pothole Damage | 50.00 | 1160.75 | | [2024-04-26 Fri] | Replace Stabilizer Links | 376.08 | 1536.83 | #+TBLFM: $4=vsum(@I$3..@$3);%.2f ``` **Calc** formulas have a similar function to Excel formulas. For more complex operations, Emacs has two more tricks up its sleeve: 1. You can call **elisp functions** in these formulas[^2]. 2. You can **use the data in code blocks** for advanced processing. # Use Tables as Data in Code Blocks If you wanted to take the latest (lowest) number in a particular column within your table and save that value for further use in other code blocks, here's how you wire a table into your code block as a variable: 1. Add a name property to the table `#+NAME: abc-table` 2. Add a var property to the code block `:var data=abc-table` ```org Let's say we have a simple table of financial data: #+NAME: big-loan | Date | Balance $CAD | |------------------+--------------+ | [2023-01-30 Mon] | 16,128.39 | | [2023-09-17 Sun] | 14,479.61 | | [2023-12-23 Sat] | 12,332.19 | | [2024-03-02 Sat] | 11,379.16 | | [2024-03-03 Sun] | 9,120.16 | | [2024-04-12 Fri] | 8,784.89 | | [2024-04-27 Sat] | 7,808.79 | We can grab the first row of the table: #+begin_src elisp :var data=big-loan (car data) #+end_src #+RESULTS: | [2023-01-30 Mon] | 16,128.39 | We can print the last updated balance as a dollar amount: #+begin_src elisp :var data=big-loan :exports both (setq big-loan-cad (to-num (col-last data 1))) (render-human-dollars big-loan-cad) #+end_src #+RESULTS: : $7,808.79 ``` The functions called here are all custom and loaded when Emacs is started. Here's the function for picking out the last entry in a column, though you'll need to learn a bit more about lisp to understand it: ```lisp (defun col-last (data col-index) (nth col-index (caar (list (last data))))) ``` Again, the beautiful thing about Emacs is its **customizability** - I wrote this short function to re-run all of the table calculations, then run all the code blocks in the current file. ```elisp (defun rcf/recompute () (interactive) (org-table-recalculate-buffer-tables) (org-babel-execute-buffer)) (global-set-key (kbd "C-c o r") 'rcf/recompute) ``` All I need to do now is hit `C-c o r` and all my computations are re-run. # Build an Idea Graph with Org-Roam When taking notes, have you ever been frustrated when realizing that you have information on one topic scattered into several different notes or places? **Org-roam** can fix that - it's like building a second brain[^3]. - `org-roam` enables note-taking with the [Zettelkasten](https://medium.com/the-pub/how-to-remember-everythwhat-you-learn-zettelkasten-method-aa3325c3b2ac) methodology. - `org-roam-ui` allows you to beautifully visualize your nodes - `org-roam-protocol` allows you to use browser extensions and external tools to build your node web ![An example from [Alex Kehayias's](https://notes.alexkehayias.com/org-roam-ui-helps-you-peer-into-your-brain/) notes](/org/roam-ui.png) Building out this graph is as easy: - Type `C-c r f` to find an existing node or create a new one - Type `C-c r i` to insert a reference to a new or existing node This is accomplished with some simple keybindings: ```elisp (global-set-key (kbd "C-c r f") #'org-roam-node-find) (global-set-key (kbd "C-c r i") #'org-roam-node-insert) ``` Be [mindful](https://www.youtube.com/watch?v=FrvKHFIHaeQ) when building your knowledge graph. It is easy to copy-paste in bucketfuls of data, but the Zettelkasten method when applied correctly encourages brevity. # Agenda and ToDo Tracker Holding shift on a headline allows you to cycle between states, to `TODO` or `DONE`. Typing `C-c a t` allows you to see ToDos from all your Org files, and indicates the file the todo is in and any tags or priorities set. You can set a custom sequence on a per-file basis: ```org #+SEQ_TODO: TODO(t) FOLLOW-UP(f) RECURRING(r) IN_PROGRESS(p) STALE(s) | DONE(d) CANCELLED(c) ``` You can use `C-c C-s` to *schedule* a time for a task, or `C-c C-d` to set a *deadline* with a day and time. All these will show up in your agenda. ![Week Agenda - [Bill de Hora - How I Use Org Mode](https://dehora.net/journal/how-i-use-org-mode)](/org/agenda-week.png) With these tools alone, Org becomes an extremely powerful way to organize all of your ToDos. Even if you add a date under a heading with `C-c .`, it'll show up in the agenda so you can keep track of when notes were taken. **Org-agenda** allows you to see [at a glance](https://orgmode.org/manual/Agenda-Views.html) all of your organized `TODO`s in a linear calendar, in a list, or filtered by a tag applied to a headline with `C-c C-q`. Checking all of your actions related to a project, IT ticket, or week is a breeze. ![Agenda Commands - [Caleb Rogers - How I Stay Organized using Emacs](https://blog.calebjay.com/posts/my-emacs-environment/)](/org/agenda.png) # Time Tracking In addition to pre-emptively organizing your time, you can also keep track of how long you spend on any given task and get a clear overview of where your time is going. If you are taking notes beneath a header, tapping `C-c C-x C-i` will **clock in** and `C-c C-x C-o` will **clock out**. If you expand the properties under the headline that'll look like this: ```org ** FINISHED Rich Dad, Poor Dad :LOGBOOK: CLOCK: [2023-12-15 Fri 19:31]--[2023-12-15 Fri 20:28] => 0:57 CLOCK: [2023-12-15 Fri 13:21]--[2023-12-15 Fri 13:59] => 0:38 :END: ``` A clocking table can be added anywhere in the file, with configurable scope and depth (how many headers will be shown before times are combined). ```org #+BEGIN: clocktable :scope file :maxlevel 3 #+CAPTION: Clock summary at [2024-01-26 Fri 18:02] | Headline | Time | | |------------------------------------+------+------| | Total time | 2:26 | | |------------------------------------+------+------| | Money - Finance, Saving, Investing | 2:26 | | | \_ Rich Dad, Poor Dad | | 1:35 | | \_ Multiple Streams of Income | | 0:51 | #+END: ``` You can jump to the current clock task/header with `C-c C-x C-j`, and recompute the table or time interval with `C-c C-c` while the cursor is placed over top of these respective items. # Searchability - GREPing your Stuff Would you like to hit a single key to do a full-text search of all your org files? If you've installed the `projectile` package, you can add this bit of elisp to your config: ```elisp ;; projectile is another amazing package from the ;; creator of CIDER. It's got lots of commands ;; for searching and managing files in a project. ;; https://projectile.mx/ (setup (:package projectile) (projectile-mode +1) (:bind "s-p" projectile-command-map "C-c p" projectile-command-map) (global-set-key [f9] 'projectile-grep)) ``` Now, hitting `f9` will do a **full-text search on all your Org files**, and anything else in the directory. You can exclude files and paths in a `.projectile` configuration file at the root of your projects folder. # LaTeX Export - Or Any Format, Really You can write LaTeX inline in org files. Mathematics formulas included. Output can be customized easily with some headers: ```org #+LATEX_CLASS_OPTIONS: [letterpaper,10pt] #+LATEX_HEADER: \usepackage[margin=1.0in]{geometry} ``` ...far deeper export customization is available, but I haven't leveraged it yet. Typing **"org export"** into `M-x` for me yields 196 options with my current configuration. Many of these are the same file format via a different technology. For example, there are 15 different methods of exporting to a PDF. On a Mac, you can export to PDF with `M-x org-latex-export-to-pdf` - though LaTeX export won't work on OSX without: ```sh ╭─r@Ryans-MacBook-Pro.local /Library/TeX/texbin ╰─➤ sudo tlmgr install wrapfig marvosym wasysym capt-of ``` _Enjoy your beautiful PDF export!_ # Extending Org-Mode and Emacs A good portion of the things I've described above have been combined in a unique way or altered to my taste. The best part about a programmable text editor is that it's **extremely easy to hack on and change** to fit your working style. While it's **not for the faint of heart**, Emacs is a journey worth taking, something I wish I pursued far sooner in my life as it certainly would have made a positive impact on my University grades. Here are some more inspirational sites to start you on your Emacs journey: 1. [orgmode.org - simple Org tutorial](https://orgmode.org/worg/org-tutorials/orgtutorial_dto.html) 1. [github.com/emacs-tw/ - awesome-emacs#table-of-contents](https://github.com/emacs-tw/awesome-emacs?tab=readme-ov-file#table-of-contents) 1. [orgmode.org - org-mode hacks](https://orgmode.org/worg/org-hacks.html) 1. [systemcrafters.net - basics-of-emacs-configuration](https://systemcrafters.net/emacs-from-scratch/basics-of-emacs-configuration/) 1. [wilfred.me.uk .emacs.d/init.el](http://www.wilfred.me.uk/.emacs.d/init.html) 1. [github.com/caisah/ #a-list-of-people-with-nice-emacs-config-files](https://github.com/caisah/emacs.dz?tab=readme-ov-file#a-list-of-people-with-nice-emacs-config-files) 1. [config.phundrak.com - org.el](https://config.phundrak.com/emacs/packages/org.html) 1. [sqrtminusone.xyz - emacs.el](https://sqrtminusone.xyz/configs/emacs/) 1. [www.patrickdelliott.com - emacs.d/](https://www.patrickdelliott.com/emacs.d/) 1. [Visualizing your Org-Roam Network](https://lucidmanager.org/data-science/visualise-org-roam/)
!["Real Programmers" (upscaled, sharpened - [xkcd](https://xkcd.com/378/))](/org/real_programmers.jpg) ![The satirical 'M-x butterfly' command in action.](/org/mx-butterfly-sm.gif?invert=true&gif) # Summary **Org-mode** along with some additional packages enables you to: 1. Build a body of personal knowledge in plaintext 2. Organize that body with files, headlines, and **Org-roam** 3. Instantly search all of this with _grep_ 4. Include data in tables with calculated columns 5. Manipulate those data tables in any programming language 6. Manage all of this in varying states of completion 7. Add dates, times, priorities, and time estimates 8. Easy access to the source code to tweak things to your taste 9. All of this is completely under your control # Conclusion This article is more a case of **tell** than _show_. What I hope you take away from this is that you have *freedom* in your ability to manipulate and manage your own data. There are brilliant tools outside of the walled gardens to manage and visualize your time and thoughts. If you have the wherewithal, I'd like you to take a moment and try Emacs on for size. The zen of having a single extensible place to read, write, manage, and think is truly glorious.
_This article was researched and written entirely without the use of AI._ [^1]: **Any Language:** Caveat: Any language with an interpreter or executable that can run on your system. It's not magic, but it is unbelievably flexible. [^2a]: **Text Editor:** Calling Emacs a text editor is akin to calling a computer a calculator. It is far closer to a philosophy or an application framework than just an editor. [^3a]: **Operating Mode:** When opening a file, Emacs can apply a *major mode* and any number of additional *minor modes* that add functionality like spell checking, bracket matching, highlighting, etc. [^2]: Org Mode Docs: [Org spreadsheet LISP formulas](https://orgmode.org/worg/org-tutorials/org-spreadsheet-lisp-formulas.html) [^3]: Org-roam Manual: [Introduction](https://www.orgroam.com/manual.html#Introduction) [^4]: Bozhidar Batzov, [Forever Emacs](https://emacsredux.com/blog/2022/06/09/forever-emacs/), 2022 [^5]: Wikipedia: [GNU Emacs](https://en.wikipedia.org/wiki/GNU_Emacs) [^6]: GNU Project: [Emacs History](https://www.gnu.org/software/emacs/history.html) [^7]: Org Mode Syntax: [Org Syntax](https://orgmode.org/worg/org-syntax.html) > Thank you for reading! > Find more content at > Source page: > Site index: [llms.txt](https://ryanfleck.ca/llms.txt)