Nicolas Martyanoff — Brain dump

Org-mode headline tips

Org-mode is what got me into Emacs in the first place. I use it to take notes, keep track of what I have to do and plan projects.

An Org file is a tree of elements, each one starting with a headline. Manipulating headlines can be confusing; here are a few tips that you may find helpful.

Do not split lines when adding headlines

At any point, you can insert a new headline below the current one using the C-<return> shortcut, which calls org-insert-heading. However if the cursor is at the middle of a line (headline or content), Org will split it and add the end of the line to the new headline.

Quite annoying, really. Fortunately there is a function to add a headline without splitting the currentline, org-insert-heading-respect-content. I simply bind it to C-<return>:

Obviously I want the same behaviour for C-M-<return> which inserts a TODO headline:

Edit (2023-01-07)
As it turns out, a simpler way to do that is to set org-insert-heading-respect-content:

(setq org-insert-heading-respect-content t)

No need to rebind keys.

Jump quickly to the right headline

Some of my Org files are quite long. For example, my main development tracking file contains more than 700 lines.

I never really thought about navigation, and usually either search for elements by title with C-s or move between folded items manually (I use org-startup-folded so that all items are folded by default).

As it turns out, Org has a buitin navigation system triggered by C-c C-j. At first I could not see how it could help; but then I realized that this feature can use native Emacs completion. This is incredibly useful when combined with a vertical completion framework such as Helm, making it easy to jump to any headline just by typing a couple characters.

In order to do that, we enable completion with org-goto-interface, disable the multi-steps navigation system, and set the maximum depth level used to select headlines which will be listed during completion.

(setq org-goto-interface 'outline-path-completion)
(setq org-outline-path-complete-in-steps nil)
(setq org-goto-max-level 2)

Stop highlighting TODO headlines

By default, Org highlights the entire headline for TODO items, not just the TODO or DONE keyword.

I believe this is a mistake: headlines mark the hierarchy of items, and having multiple red or green headlines is confusing. This behaviour can be configured with two settings:

(setq org-fontify-todo-headline nil)
(setq org-fontify-done-headline nil)

This way, headlines keep their original color (defined by org-level-* faces), and keywords only are highlighted with the org-todo and org-done faces.