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.