Emacs: org-mode Basics, Writing Outline

Xah Lee, 2010-03-15, …, 2012-02-09

Emacs has a mode called outline-mode. A much improved version is called org-mode. org-mode is bundled with emacs 22 (2007). This page shows you the basics of org-mode.

Sometimes you need to write some notes with a tree-structure. For example, headings, subsections, and content text. This is called outline format. You want to be able to view just the headings, or view all content of a section but hide the rest, etc.

Creating Outline

Asterisk * for Headings

In your file, any line that starts with a star followed by space * , is level 1 heading.

Any line starting with 2 stars ** is level 2 heading. Here's a example file.

* to do
Remember to bring lunch box and 2 bananas.
** call mom
don't forget to call mom
** do that
* call Jane.
her phone is 123-4567

* finish coding absca.
john was not happy.
** give that tutorial to john.
** Dave wanted do lunch. He got some ideas.
* learn emacs outline stuff

texts can actually be free form.

Copy the above text in a file and save it. Now, open the file, type 【Alt+x org-mode】. Then, emacs will display it like this:

Show/Hide Sections

• Press Tab ↹ to show/hide the current heading's content. Type it again to cycle show/hide its subsections.
• Press 【⇧ Shift+Tab ↹】 to cycle show/hide for the whole file.

Create New Heading

• 【Alt+Enter ↵】. Insert a new heading at the cursor position.
• 【Ctrl+Enter ↵】. Insert a new heading at the end of the current branch.

Tree Branch Manipulation

Here are commands that helps move headings.

• {【Alt+⇧ Shift+↑】, 【Alt+⇧ Shift+↓】}. Move branch up/down but keep in same level.
• {【Alt+⇧ Shift+←】, 【Alt+⇧ Shift+→】}. Move branch up/down a level.
• {【Alt+←】, 【Alt+→】}. {promote, demote} a heading one level.

Open Files in org-mode Automatically

If you name your file ending in “.org”, emacs will open it in org-mode automatically.

You can also put this line as the first line of the file:

-*- mode: org -*-

Emacs will start org-mode when the file is opened.

If you want any file ending in “.txt” open in org-mode, you can add this line to your emacs init file:

(add-to-list 'auto-mode-alist '("\\.txt\\'" . org-mode))

Using org-mode for Todo

org-mode is often used for todo notes too. org-mode has many features for todo. Here are some basics in using org-mode for todo.

TODO Headings

You can mark headings as a todo item. For org-mode to recognize a todo item, the word “TODO” (all caps) must happen as the first word in a heading. It will be automatically highlighted. Like this:

* TODO call mom for bday
* DONE finish coding absca

• Place your cursor on a heading, 【⇧ Shift+→】 to change heading among 3 states: TODO, DONE, and normal. It will add the word “TODO” or “DONE” in the heading.
• 【Ctrl+c Ctrl+v】 to view just todo headings.

Inserting Date/Time

• 【Ctrl+c .】 to insert a date. It will insert current date like this: <2010-07-31 Sat>.
• 【Ctrl+u Ctrl+c .】 to insert a timestamp. It will insert current date like this: <2012-02-09 Thu 03:32>.
• Put cursor on the date, then press {【⇧ Shift+↑】, 【⇧ Shift+↓】} to {increase, decrease} any {year, month, day, hour}.

Tags

Each heading may have keywords associated with it, called “tags”. For example, you can have items with tags such as {work, family, urgent, coding}, or any word you like.

The syntax for tag is any word between colon, like this: :something: or :this:that:. They are usually placed at end of the line. Like this:

** call mom for bday. :family:...
* finish writing the org-mode tutorial. :emacs:work:

Tag name characters must be any alphabets A to z, or digits 0 to 9, or “_” and “@”. It cannot have spaces or hyphen.

Tags are inherited from parent nodes, in the sense that when you search for a tag, a heading with that tag will show but also all its children, even if the children's headings do not contain that tag.

• 【Ctrl+c Ctrl+q】 to insert a tag. You can also just type the tag yourself.
• 【Ctrl+c \】 to show only headings of a given tag.

Export to HTML

One great feature of org-mode is export to HTML.

【Ctrl+c Ctrl+e】. Export the file to HTML, and automatically show the file in default web browser. (command name and key may have changed. Use the menu to find out about the command.)

The newly generated file have the same name as your org file, but with “.html” extension, in the same directory.

Remember to use Menu and Learn More

When in org-mode, there's a menu 〖Org〗. Try it. I always forgot to use the menu. From the menu, you can learn the most useful commands and the key shortcuts.

org-mode also has a big website with tutorials, FAQ, and lots other tips and discussion forum, wiki, also a Google Techtalk video where the author Carsten Dominik speaks about it. Its home page is at: orgmode.org.