Navigating Org-mode files

One of the easiest ways of navigating an Org document, isn’t even an Org feature. Just search for the text you’re looking for and jump right to it.

  • Press C-s (or M-x isearch-forward)

Of course, you might not always know the exact text (or it might not be unique enough to take you right there), so its useful to know some other ways of navigating Org documents.

Another great way to navigate your Org documents is by traversing the headers. My emacs config sets the default startup visibility to folded, so you can always get back to a folded state:

  • Press C-u C-u TAB (or M-x org-set-startup-visibility)

Cycle the visibility of the headers (foldedness):

  • Press TAB to cycle the folding of the selected header (your cursor has to be on a header).
  • Press C-u TAB to cycle the folding of the headers in the whole buffer (cursor can be anywhere).
  • Press C-u C-u C-u TAB (or =M-x org-show-all) to show the entire buffer unfolded.

If you’re in the middle of a paragraph, and want to move to the header of the current section:

  • Press s-<up> (or C-c C-p or M-x org-previous-visible-heading)
  • Press it again to go to the section before that, etc.

To move to the next section:

  • Press s-<down> (or C-c C-n or M-x org-next-visible-heading)

Moving to the next higher heading is very useful:

  • Press C-c C-u (or M-x outline-up-heading).

From the parent heading you get to see the outline of the outer context of what you’re currently writing about. From here you can press Tab twice to fold all all the sibling sections and get an overview.

  • Press C-c C-u TAB TAB.

Here are some other header movement commands:

  • C-c C-f (M-x org-forward-heading-same-level)
  • C-c C-b (M-x org-backward-heading-same-level)

Jumping around (org-goto)

You may frequently find yourself needing to jump around in a document, but don’t want to lose your current place.

  • Press C-c C-j (or M-x org-goto). Mnemonic “jump”.
  • Immediately press Enter to close the org-goto menu (theres advanced searching functions in there, but you ignore that for now).

This will save your current place, allowing you to go find the place you need to temporarily go to.

When you’re done, and you want to go back to to where you were:

  • Press C-c &. (or M-x org-mark-ring-goto).

One mnemonic for & is that it is the same syntax for a C pointer reference.

Indirect Buffers and Narrow To Subtree

One of the advantages of Org-mode is you can organize lots of different articles into one big file. This is also a disadvantage when you are trying to focus on just one of them. It is easy to get lost.

As an example, open the other book named d.rymcg.tech.org (found in this same directory). Let’s say we want to focus on the chapter named Traefik Proxy.

  • Press C-x 4 c. (or M-x clone-indirect-buffer-other-window).

You now have two buffers open for the same file: d.rymcg.tech.org (the original) and d.rymcg.tech.org<2> (the clone), and you are automatically switched focus to the newly cloned buffer.

Rename the new buffer to traefik so you don’t get confused:

  • Press C-x x r (or M-x rename-buffer).
  • Type the new name: traefik.

Now find the chapter you want to focus on:

  • Navigate to the chapter heading named * Traefik Proxy, make sure your cursor is now somewhere on this line.

Narrow the buffer to the selected subtree:

  • Press C-x n s (or M-x org-narrow-to-subtree).

You have now completed the process of narrowing the content of this buffer to only the Traefik Proxy article. It is important to know that the traefik buffer is still an indirect clone of the original d.rymcg.tech.org buffer, and they are both simultaneously editing the same underlying file. But now you know how to focus on a bite sized peice of a larger file. Go ahead and create more buffers to work on other parts you frequently need to focus on.

If you need to widen the buffer again:

  • Press C-x n w (or M-x widen)