Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 38 ยท Org Mode

Org Mode Basics: Outlines, Lists and Links

Start with Org mode: create headings, fold and unfold with TAB, restructure outlines, write lists and inline markup, add links, and use structure templates for code blocks.

Org mode is the feature that makes many people stay with Emacs. It is a plain-text system for notes, task lists, planning, documents and even literate programming, all in files you can read in any editor. Org ships with Emacs, so nothing needs installing: open a file ending in .org and Org mode turns on.

The core of Org is the outline: a tree of headings. Everything else in this chapter (TODO items, tags, the agenda, tables and code blocks) hangs on that tree.

Headings

A heading is a line that starts with one or more asterisks followed by a space. The number of asterisks is the level.

ORG
* Projects
** Website redesign
*** Gather requirements
** Learn Emacs
* Reading list

Everything between a heading and the next heading of the same or higher level belongs to it. Write plain paragraphs under a heading as the body.

Useful keys, which work anywhere in an Org buffer:

Keys Command Effect
TAB org-cycle On a heading, cycle that subtree: folded, children, everything
S-TAB org-global-cycle Cycle the whole buffer: overview, contents, all
M-RET org-meta-return New heading (or list item) at the same level
M-<left> / M-<right> Promote / demote a heading
M-S-<left> / M-S-<right> Promote / demote the whole subtree
M-<up> / M-<down> Move the subtree up or down
C-c C-n / C-c C-p Next / previous heading
C-c C-f / C-c C-b Next / previous heading at the same level
C-c C-u Up to the parent heading
C-c C-x C-w / C-c C-x M-w Cut / copy a whole subtree

Pressing TAB on a folded heading shows its children; pressing again shows everything inside; pressing a third time folds it. Folding gives you big-picture navigation in a very long file. C-c * turns the current line into a heading and back. A folded heading ends with ..., a sign that content is hidden: edits inside hidden text are blocked to prevent accidents.

JS Stand-in: parse an Org outline

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Plain lists

Org understands bullet lists (- or +), numbered lists (1. or 1)) and description lists (- term :: description). Pressing M-RET inside a list adds a new item, M-<left> and M-<right> change the indentation of an item, and M-<up>/M-<down> to reorder items. Numbering updates itself.

ORG
- Buy groceries
  - milk
  - bread
1. First step
2. Second step
- Emacs :: a Lisp-powered editor
- Org :: outlines, planning, literate documents

Checkbox items use [ ] and [X] after the bullet; the next lesson covers them with TODO items.

Text markup

Org uses lightweight markup in running text: *bold*, /italic/, _underlined_, =verbatim=, ~code~ and +strike-through+. The org-hide-emphasis-markers variable hides the marker characters for a cleaner look. Comment lines start with # , and a block of text can be commented with #+begin_comment ... #+end_comment. A line of at least five hyphens (-----) becomes a horizontal rule on export.

Lines starting with #+ are keywords that give information to Org and the exporter: #+title: My notes, #+author:, #+options:, #+startup: overview and so on. Put them at the top of the file. #+startup: overview makes the file open folded, and #+startup: indent gives clean indentation without extra asterisks.

The general link form is [[target][description]]. Targets can be:

  • A URL: [[https://www.gnu.org/software/emacs/][Emacs home]]
  • A file: [[file:~/notes/todo.org][To-do]], optionally with a search such as ::*Heading
  • A heading in this file: [[*Projects]]
  • A custom target or an ID.

C-c C-l (org-insert-link) asks for the link and description; C-c C-o follows the link at point; C-c & returns you to where you jumped from. Links display as just the description. To see the raw link put point on it or toggle display with M-x org-toggle-link-display.

C-c l (org-store-link) stores a link to the current location (a file, a Dired directory, a web page in EWW, an email in some clients). Then C-c C-l in another Org buffer offers it as the default. Note that C-c l, C-c a and C-c c are suggested global bindings that you must add yourself; Org does not enable them. In your init file:

ELISP
(global-set-key (kbd "C-c l") #'org-store-link)
(global-set-key (kbd "C-c a") #'org-agenda)
(global-set-key (kbd "C-c c") #'org-capture)

Structure templates and blocks

Source blocks, quotes and examples are written between #+begin_... and #+end_... lines. Rather than type them, press C-c C-, (org-insert-structure-template) and choose a letter: s source, q quote, e example, c center. If you enable org-tempo ((require 'org-tempo)), you can type <s followed by TAB to expand a source block.

ORG
#+begin_src python
print("hello")
#+end_src

#+begin_quote
Programs must be written for people to read.
#+end_quote
JS Stand-in: extract links and list items

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How do you make a level-two heading in Org?

    The number of asterisks at the start of the line is the heading level.
  2. 2. What does S-TAB do?

    S-TAB runs org-global-cycle: overview, contents, then everything.
  3. 3. Which key inserts a link?

    C-c C-l inserts or edits a link; C-c C-o follows one.
  4. 4. Which keys move a whole subtree down?

    M-<up> and M-<down> move the heading and its children.

Summary

  • Org files are outlines: * headings of increasing depth, folded and unfolded with TAB and S-TAB.
  • M-RET, M-<arrows> and C-c C-n/p/f/b/u create, restructure and navigate headings.
  • Lists, light markup, #+keywords and blocks give structure; [[target][text]] makes links (C-c C-l).
  • Bind org-store-link, org-agenda and org-capture to keys of your choice.

Next: Org TODO Items, Tags and Properties