Red Green Repeat Adventures of a Spec Driven Junkie

org-mode: Lists & Topics

This article forced me to research into Emacs’ org-mode system more after fumbling blindly in it for the last while. I learned how org-mode helps me outline better and show how org-mode’s list and topic management works.

If you want a simple introduction to org-mode, this is for you. There’s a whole book written just on org-mode and if you want to start using it in less than five minutes, this is article is for you!

Ear Ornament Winged Runner source and more information


I heard about org-mode from other Emacs users and found it intriguing. Instead of asking for details or doing any research, I jumped in and started using org-mode to outline stuff.


To make an list in org-mode, it’s like in any other system: create lines that start with a delimiter (I prefer to use -) and for each ‘sub-topic’, indent with spaces (I prefer two).

A simple example:

- level one
  - level two
	- level three
  - another level two item
- another level one item

Simple and easy to read.

Indenting to Create Sub-topics

I got the basic gist’s of lists, but instead of using space to create sub-topics, use tab in a list and org-mode will indent at “smart” levels.

When I want to put an item after level three, I enter a - and hit tab

- level one
  - level two
	- level three

This got me pretty far when outlining articles and the next neat thing with org-mode: collapsing lists!

If we take the above list and go to an individual level and hit tab:

org-mode indenting

I love that, it helps me organize large outlines together and show/hide exactly what I want. It saves me hitting the space key. (For me, in the space vs tab war, tab is winning, especially here!)

Collapsing Topics

When working with lots of topics and subtopics, it would be nice to shrink down topics that are already fleshed out and be able to just see the current topic and subtopics (without needing to scroll).

Pressing tab on a topic with subtopics in org-mode will collapse topics together! Given the following list:

- level one
  - level two
    - level three
      item at level three
    item at level two
    another item at level two

What’s the big deal, right?

Now put the cursor on level one and hit tab:

- level one...

All the items under level one, collapsed into level one... The ellipses indicate a collapsed topic with subtopics.

Now hit tab again on the same line:

- level one
  - level two...

org-mode expands the first level of level one by revealing level two, which has collapsed topics as it has ... trailing.

Now hit tab once more (while the cursor is at level one):

- level one
  - level two
    - level three
      item at level three
    item at level two
    another item at level two

org-mode has expanded the rest of the topics out. Three tabs to:

  • collapse topic to the first level
  • expand a topic’s subtrees
  • expand all topics’ subtrees and leaves

Here’s a video of it in action:

org-mode collapsing

Isn’t that neat?!

Moving Topics

When I outline, I prefer to go deep with the nesting with topics and details as I think things out. I want content out of my brain and onto the screen in a structured manner.

When I look at the big picture, I realize the article would flow better if the order changed. The order of the topics can be better if they are in a different order.

The way I have moved topics around would be to select the whole section and move it.

  1. Move to the section of interest
  2. Mark the section
  3. Move to the end of the section
  4. Cut the region
  5. Move to the new area I want the section to be
  6. Paste it.

With org-mode, I would:

  1. Move to the section of interest
  2. Collapse it
  3. Cut it as a single line
  4. Move to the new area I want the section to be
  5. Paste it.

Listing this detail, I realize I am saving one action, namely: “Move to the end of the section”. This action takes decisions and effort to execute.

In org-mode, I do not even think about these small details. I collapse, cut, move paste, and continue.

org-mode moving topics

I still can’t believe I fat-finger this operation sometimes.

Shifting Topics

I used org-mode without understanding anything, fumbling my way through lists.

One area that annoyed me is topics shifting. If I wanted to promote or demote a topic, I couldn’t figure out a simple way of doing it, and used multiple cursors mode to move everything in a region. This gets annoying, especially as topics become larger.

I tried even ‘moving topics and indenting the collapsed topic (you know, just to see if the whole thing would ‘auto-magically’ indent, answer: it doesn’t :-( )

This annoyed me enough and the answer wasn’t obvious within 30min, so I read the (short) manual: compact guide to org-mode

The solution is to use keys: Meta-Left/Right and Meta-Shift-Left/Right

Shift Topic

The Meta-Left/Right key combination moves the current topic (kind of boring). I list it here because it helps remember the next combination.

Shift Topic and its Branches

Meta-Shift-Left/Right key combination moves the current topic and its branches in or out. Saving one from invoking multiple cursors and fumbling around there.

This has made outlining easier, because I’m managing the complete topic at once, without working its branches.

org-mode shifting topics

Now that’s power!


How did I go so long without org-mode in my life? I wished I read the manual sooner!

Just knowing about org-mode’s lists and topic helpers has improved my outlining capability for articles. I can get a structured outline from my head to the screen quickly. Manipulate the topics by moving them around within the outline or even promote/demote topics and their branches with ease.

If you like the write, know org-mode will go a long way!