Org-mode basics: structuring your notes

I’ve been putting off writing about org-mode as it is hard to know where to start. What is org-mode? From the org-mode web page

Org mode is for keeping notes, maintaining TODO lists, planning projects, and authoring documents with a fast and effective plain-text system.

For many people, org-mode is the reason they started using emacs. I only came to it after using emacs for about 10 years, but it was responsible for me moving from using emacs as a simple text editor to using emacs almost everywhere, and seeing a huge productivity boost.

Org-mode is very versatile, and I use it to (among other things):

  • Write general notes;
  • Write pdf lecture handouts and slides;
  • Write my research notes, analysis code, results, and final published papers in a single document allowing for reproducible research;
  • Manage my to do list and deadlines;
  • Write this blog;
  • Create static web pages;
  • Compose emails

One key thing to note is that while doing all these things, all org-mode documents are simple plain text that can be read in any text editor.

There are lots of org-mode tutorials out there such as

I don’t want to reinvent the wheel here, but I think the sheer amount that org-mode can do can be overwhelming for new users. So, in the spirit of this blog, I’ll write a series of posts to pick out some of the key features of org-mode that I use the most.

I’ll start here with the use of org-mode to make simple structured notes. This was the thing that got me hooked on org-mode, and everything else followed from here.

Org-mode is included in emacs, but you should install the most recent version (8.3.1 as of today).

The easiest way to get started is to open a new file in emacs with .org as the extension. Below is an example org document, and I would suggest typing this into your org-mode file to get a feeling for how the structure works.

* org-mode structure
Text in org is structured by headings, denoted by lines starting with
one or more * so we are currently in a section!

** A subheading
Starts with an extra * and so on

** navigation
Headings can be expanded or collapsed by moving to the (sub)heading
and pressing TAB. S-TAB cycles all headings. You can jump to next and
previous headings with C-c C-n and C-c C-p respectively.

You can move headings up and down to reorder them with the arrow keys,
using M-up or M-down. You can change the level of headings with M-left
and M-right (and use M-S-left and M-S-right to also change the levels
of and subheadings).

** lists
*** bullet lists
 - bullet lists can be created like this (start a line with one or
   more space and a -
 - pressing M-RET gives you a new bullet
 - we might also like nested bullets
   - like this one (I pressed M-RET TAB to indent it)
   - and another (M-RET now indents to the new level)
 - the nice thing is that for long lines of text, emacs wraps them
   so that they line up with the bullet
 - you can also reorder list items and change indentation using
   M-up or M-down just like with section headings
 - you can change bullet style using S-left and S-right

*** numbered lists
 1) numbered lists are also possible
 2) M-RET gives me a new number

*** checklists [/]
 - [ ] we can even have check lists
 - [ ] M-S-RET gives a new item with a check box
 - [ ] C-c C-c check/unchecks a box
 - [ ] you can have sub items
   + [ ] like this
   + [ ] that can be checked off individually
 - [ ] and you can track the number of items by adding [/] to the end
   of a line above a checklist - this updates when you check items off

*** definition lists
 - definition lists :: these are useful sometimes
 - item 2 :: M-RET again gives another item, and long lines wrap in a
      tidy way underneath the definition

I would suggest a couple of customisation to org-mode at this stage. Add the following to your emacs config file:

;; set maximum indentation for description lists
(setq org-list-description-max-indent 5)

;; prevent demoting heading also shifting text inside sections
(setq org-adapt-indentation nil)

That’s all for now. Try using org-mode to make simple notes and I think you’ll like the structure it gives you compared to simple text.

  • What I like about org-mode is the minimalism of the UI.
    You need to know that * in the left-most column controls the heading level, and the TAB key hides and shows. Oh, and more stuff.
    But “less is more” is the UI blessing of the day.

  • fkunze

    i like your decision to write about org-mode in the context of a notebook. – Thanks!

  • Pingback: Org Mode Basics: Structuring Notes | Irreal()

  • At some point of time, I would love to see a post about multiplatform(Linux and Android ofcourse) org-mode setup. And I would also love to see org-mode as a replacement of Evernote which means it could hold objects like images and maybe other multimedia files.

    • Ben Maughan

      I can’t really help about multiplatform use with a mobile device. I tried MoblieOrg and didn’t really like it. Orgzly is a more recent solution but I’ve not tried it.

      I will be covering adding images to org-mode documents, and also a nice workflow solution I have to scanning paper documents and then filing them with org-mode.

      • Erik Nilsson

        Emacs can now be run on Android Termux.

  • The first tab at any heading collapses (Folded) the list, the second tab expends (Children) the list and the final third tab doesn’t do anything. On the third tab press I see subtree being printed in bottom. What is happening here?

  • Jun Xuan Ng

    I am using the emacs version 25 with v9 of org mode. I am unable to get the text to wrap like in your example in the “the nice thing is that for long lines of text, emacs wraps them so that they line up with the bullet”

    Is there some config i need to set? Thanks!