Emacs: Org Mode Features

Overview of the Org mode features, based on Org Manual and other sources.

Headings start with * and the number of stars defines the heading level. A couple of ** create the second level. And so on…

Instead of typing many ~*~s, you can use TAB at the beginning of the line to indent and Shift-TAB to de-indent.

The text under the heading becomes the section text and is indented according to the parent heading.

Note: The confusion: coming from markdown, I thought that * starts a list. But this is not a list, this is a heading (similar to markdown's #, ##, etc.). It is displayed in org mode as a hierarchical (and collapsible) structure, so it kind of looks and works like a list too.

Use TAB when the cursor is on the document node (in insert mode in evil) to collapse/expand the current node (cycles through states)

• The cycle is: Folded -> Children -> Subtree

Use Shift-TAB to collapse/expand all nodes

• The cycle is: Overview -> Contents -> Show all

TAB / Shift-TAB are multi-functional, the effect depends on the context:

• After the heading marker (*) it shifts / unshifts the marker.
• On the table, it formats the table
• On the list item (heading) it cycles through folding states.
• More commands to control the visibility: org#Global and local cycling

Note: The M-x toggle-truncate-lines is useful to toggle truncation on and off.

Motion commands:

• Next heading: C-c C-n (org-next-visible-heading).
• Previous heading: C-c C-p (org-previous-visible-heading).
• Next heading same level: C-c C-f (org-forward-heading-same-level).
• Previous heading same level: C-c C-b (outline-backward-same-level).
• Backward to higher level heading: C-c C-u (outline-up-heading).

Structure editing commands:

• Insert new heading on the same level: M-RET (org-meta-return)
• Insert new TODO heading on the same level: M-S-RET (org-insert-todo-heading)
• Cycle through levels in a new empty entry: TAB (org-cycle)
• Promote/demote heading or list item: M-LEFT (org-metaleft), M-RIGHT (org-metaright)
• Move subtree up or down: M-UP (org-move-subtree-up), M-DOWN (org-move-subtree-down)
• Refile entry or region to a different location: C-c C-w (org-refile)
• Narrow/widen buffer to current subtree:
  • Narrow: C-x n s (M-x org-narrow-to-subtree)
  • Widen: C-x n w (M-x widen)

Filtering the document ("sparse tree"): we can filter the document (collapse unrelated headings) based on several properties (such as TODO items, tags, dates). The simplest mode is "Regex" where we can enter the search term and only keep sections that contain it expanded.

Sparse tree commands:

• Prompt for the filter type: C-c / (org-sparse-tree)
• Occur: prompts for a regexp: C-c / r (org-occur)
  • Highlights occurrences, highlight can be removed with C-c C-c.

Lists can be started with +, - or * (the * should not be at the start of the line or it will be a heading), the list with + markers:

• Item 1
  • Item 1.1
    • Item 1.1.1 (use TAB to indent sub-items)
• Item 2
  • Item 2.2 (items can also be indented by adding more spaces before the marker)

Structure editing commands (see above) that can be used for headings are also useful for lists. So, for example, M-Up / M-Down move list items up and down.

List with - marker and check-boxes (added with [ ], [x], [-])

• [ ] not started
• [-] in progress
• [X] complete

Links:

• [[link]]
• [[link][description]]
• [[file:file.org]]
• [[file:file.org::heading]]

The link format is similar to HTML: <a href="target">desc</a> (first link, then description).

Once the link is inserted, it is rendered as a hyperlink. To update it, use M-x org-insert-link or switch to the fundamental mode with M-x fundamental-mode for a plain text view.

Links to images without description are rendered automatically:

• Web image:
  • 
• Local image:
  • 

To display the image in Emacs, put the cursor on the link and do M-x org-link-preview.

To automatically display all images in Emacs:

Org mode can display link previews automatically when opening buffers. Either customize 'org-startup-with-link-previews' or use the '#+STARTUP: linkpreviews' keyword to enable previews for that specific buffer when opening it. '#+STARTUP: nolinkpreviews' will disable previews on startup in the buffer.

The M-x org-store-link and M-x org-insert-link are useful to get links to org documents or nodes and paste in another document.

The link can be edited by using M-x org-insert-link again.

For more reliable cross-links in org documents, use M-x org-set-property and insert the CUSTOM_ID property.

Links can point to a place inside other files:

• file:~/code/main.c::255 - find line 255
• file:~/xx.org::My Target - find <<My Target>>
• [[file:~/xx.org::#my-custom-id]] - find the entry with a custom ID

Table is added with |, like this:

Table is reformatted with TAB when cursor is inside the table.

Markup is different from Markdown, but similar by nature:

• Bold (*Bold*)
• italic (/italic/)
• underline (_underline_)
• verbatim (=verbatim=)
• code (~code~)
• strike-through (+strike-through+)

Markup can be combined: combination (_*/combination/*_).

code (~code~) and verbatim (=verbatim=) need to be the inner-most markup.

More information: Emphasis Markers

Org mode renders the markup, so, for example, after you add a link, it is hard to edit the URL.

Switching to M-x fundamental-mode shows everything as plain text.

• Is there a better way to do this?

Example block:

block example

Source block:

(message "Hello World")

To wrap text into the block, use M-x org-insert-block-template.

Code blocks can be executed. Emacs Lisp works by default and more languages can be added like this (a snippet from the emacs config):

;; use python3
(setq org-babel-python-command "python3")
;; Enable python and bash support in org-babel,
;; so that we can run code blocks in org-mode.
(org-babel-do-load-languages
 'org-babel-load-languages
 '((python . t)
   (shell . t)))

Execute the code block with M-x org-babel-execute-src-block, the output goes into the following #+RESULTS block:

echo "Hello World (bash)"

Hello World (bash)

return "Hello World (python)"

Hello World (python)

We have access to the outside world too, for example, get the list of *.el files in the current folder, calculate file sizes and print as a table:

from pathlib import Path
elFiles = []
for el_file in Path("./").glob("*.el"):
    elFiles.append([
        el_file.name,
        "{:4.1f} KiB".format(el_file.stat().st_size / 1000)])
return elFiles

• C-c C-x C-i - Start the clock
• C-c C-x C-o - Stop the clock
• C-c C-x C-e - Change the effort estimate

• M-x org-capture

• C-c a a - Open the agenda (day / week view)
• C-c a t - List all TODO entries
• C-c a m - Match tags and properties

https://www.reddit.com/r/emacs/comments/1upaqm5/underappreciated_emacs_builtins_emacs_calc/

Press C-x *, then ? to see the calculator help.

Calculator can work in its own window, but it can also be used in the org document to calculate embedded expressions.

Press C-x * u on the formula to evaluate it.

$(80 km/h) * 2h$

The formula like above will be replaced with the result.

To keep the formula and add the result, use the => at the end of the formula:

$(80 km/h) * 2h => $

C-x * a detects and activates every "assignment-formula", so we can have some assignments and then evaluate the formula that uses them:

$mass := 2 kg$
$v := 3 m/s$
$E_c := (1/2) mass * v^2 => $

Out comes 9 kg m^2 / s^2

The calculator understands units:

$side1 := 3 m$
$side2 := 40 cm$
$hyp := usimplify(sqrt(side1^2 + side2^2)) => 3.02654919008 m $

It can solve equations! Press C-x * u on the next formula:

$solve(22 x + 33 = 65, x) => x = 1.45454545455 $

Copy code, then insert with M-x org-rich-yank to get it formatted as org mode block.

Put the cursor on a link, copy it (can do vi[y if on an org link) then run M-x org-download-yank to download the image and insert a local link into the org file.

Use M-x org-link-preview to display images inline. Use M-x org-link-preview-refresh to make sure all images are displayed.

org-download also allows dragging and dropping images to Emacs.

Google Docs document can be converted to org mode by downloading it as docx and then converting with pandoc:

# The --extract-media=images will put extracted images in the images/media folder.
pandoc -f docx -t org --extract-media=images -o Document.org ~/Downloads/Document.docx

My notes based on the "How I org in 2023" article:

• https://github.com/nickanderson/how-i-org
• https://github.com/nickanderson/org-config

• Org mode quick start (web)
• Org mode guide (web)
• Org mode tools (web)
• The Org Manual (Info)
• Org mode community wiki (web)
• Org mode tutorials (web)
• Org mode Reference Card (web, pdf)