Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Getting Started

This chapter takes you from an empty Emacs to a working Org setup and a first file. Along the way it introduces the habits that the rest of the book relies on: how Org names its keys, why one key can do many things, how to insert common structures quickly, and how to tell Org about per-file settings. It ends with org-lint, a checker that catches mistakes before they cause confusing behavior.

Installing and checking Org

Org is part of GNU Emacs, so you probably have it already. To see which version you are running, type M-x org-version. This book describes Org 9.8.13; if your version is older, most of the material still applies, but some commands (for example the link preview commands in Markup for Rich Contents) are new in 9.8.

Each Org release supports the latest Emacs release and the two before it. According to ORG-NEWS, Org 9.8 requires at least Emacs 28; support for Emacs 26 and 27 was dropped in this release.

Installing a newer version

If the bundled version is too old, you can install a newer Org on top of it. Choose one method and stay with it, because mixing installation methods is a common cause of strange errors.

  • From the package archive. Run M-x list-packages and upgrade org. Do this in a session where you have not yet opened any Org file; otherwise parts of the old version are already loaded and will conflict with the new one. With Emacs 30 or later, the safest way is a separate batch process:

    emacs -Q -batch -eval "(progn (package-refresh-contents) (package-upgrade 'org))"
    
  • From the Git repository. Clone the repository, run make autoloads (this step is required: it generates the version file and the autoload definitions), and put the lisp directory first in your load path:

    (add-to-list 'load-path "~/src/org-mode/lisp")
    

The examples in this book were run against a Git checkout of the release_9.8.13 tag, loaded exactly this way.

Activating Org

Files whose names end in .org open in Org mode automatically. For a file with another extension, make the first line a mode line:

MY PROJECTS    -*- mode: org; -*-

Org needs Font Lock (syntax highlighting), which is on by default in Emacs. Many Org commands also act on the active region, which relies on Transient Mark mode, also on by default.

Three global keys

Most Org commands only make sense inside an Org buffer, but three are useful everywhere: storing a link to the current location, opening the agenda, and capturing a quick note. Bind them to keys that work in every buffer. The key sequences C-c followed by a plain letter are reserved for users, so these bindings will not collide with any mode:

(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)

The rest of this book assumes these bindings. The commands themselves are explained in Hyperlinks, Agenda Views and Capture, Refile, Archive and Attachments.

Your first file

Open a new file, for example ~/org/start.org, and type the following. Do not worry about every symbol yet; the point is to see how little syntax a useful file needs.

#+TITLE: Getting started with Org

* Learn the basics
** TODO Read the structure chapter
** TODO Try visibility cycling
- press TAB on a headline
- press S-TAB anywhere

* Shopping
| Item   | Qty |
|--------+-----|
| apples |   3 |
| kiwi   |  12 |

* Notes
Org files are plain text. Emphasis looks like *this*,
and a link looks like [[https://orgmode.org][the Org website]].

Now try a few commands:

  1. Put point on * Learn the basics and press TAB several times. The subtree folds and unfolds.
  2. Press S-TAB a few times to switch the whole file between an overview, the list of headlines, and the full text.
  3. On ** TODO Read the structure chapter, press C-c C-t. The keyword changes from TODO to DONE.
  4. Put point at the end of ** TODO Try visibility cycling and press M-RET. A new headline appears at the same level.
  5. In the table, change 12 to 120 and press TAB. The table realigns itself.
  6. Put point on the link and press C-c C-o to open it.

Each of these actions has its own chapter: Document Structure for 1, 2 and 4, TODO Items for 3, The Table Editor for 5, and Hyperlinks for 6.

How Org names its keys

Org uses the standard Emacs notation. C-x means holding Control while pressing x, M-x means Meta (usually Alt), and S- means Shift. RET, TAB, SPC and the arrow keys LEFT, RIGHT, UP, DOWN are written as words. C-c C-t is a sequence: first C-c, then C-t.

Most Org-specific keys start with C-c, followed by a control key (C-c C-t) or by C-c C-x and another key (C-c C-x C-w). The plain-letter C-c keys stay free for your own bindings.

One key, many meanings

Org deliberately reuses a small set of keys and lets the context decide what they do. The idea is that one familiar gesture should mean “the natural operation here”. M-RIGHT is a good example: on a headline it demotes the headline, in a plain list it indents the item, and in a table it moves the column to the right.

Internally, such keys are bound to a generic command (here org-metaright) that inspects point and calls the specific command (org-do-demote, or org-table-move-column-right). This book, like the manual, names the specific command whenever it can.

The main families of context-sensitive keys are:

KeysGeneral meaning
TAB, S-TABCycle visibility; in tables, move between fields.
M-RETInsert a new item of the same kind: headline, list item or table row.
M-LEFT, M-RIGHT, M-UP, M-DOWNChange the level or the position of the thing at point.
S-LEFT, S-RIGHT, S-UP, S-DOWNChange a value at point: TODO state, priority, timestamp, bullet type.
C-c C-c“Do the obvious thing here.”

The Shift-arrow keys conflict with Emacs’s Shift selection. By default (org-support-shift-select is nil), Org gives them its own meaning in these contexts instead of selecting text. On a text terminal, some of these key combinations may not reach Emacs at all; Org Beyond the Basics lists the alternative keys.

The busy key: C-c C-c

C-c C-c (org-ctrl-c-ctrl-c) is the most heavily loaded key in Org. When you are unsure how to “apply” or “update” something, it is usually the right key. The command checks a series of conditions in a fixed order and runs the first action that applies.

flowchart TD
    K["C-c C-c"] --> A{"Column view or temporary highlights?"}
    A -- yes --> A1["Quit column view or remove highlights"]
    A -- no --> B{"Special buffer, such as capture?"}
    B -- yes --> B1["Finish: file the note"]
    B -- no --> C{"Babel result hash, or a function on org-ctrl-c-ctrl-c-hook?"}
    C -- yes --> C1["Run that handler"]
    C -- no --> D["Inspect the element or object at point"]
    D --> E["Act on it: run a code block, align a table, toggle a checkbox, refresh keywords, set tags, jump to a footnote"]
    D --> F["Nothing matches: org-ctrl-c-ctrl-c-final-hook, else an error"]

Figure 2.1: C-c C-c first checks a few global situations, then dispatches on the syntax at point.

The order comes from the source of org-ctrl-c-ctrl-c in lisp/org.el. The most common actions, by what is at point:

Point is onC-c C-c does
A source block or an inline code callEvaluate the code (Working with Source Code).
A tableRealign it and recalculate the current line; on a #+TBLFM line, apply all formulas.
A plain list item with a checkboxToggle the checkbox; on other items, repair the list.
A #+KEYWORD lineReread all in-buffer settings.
A headlineSet tags.
A property drawer or property lineOffer property commands.
A footnote reference or definitionJump to the other end.
A statistics cookie such as [1/3]Update it.
A #+BEGIN: line of a dynamic blockUpdate the block.
A timestampCorrect the day name.

Two of these can be seen in batch Emacs. With point in this table, C-c C-c produces the aligned version on the right:

| Name | Qty |
|-
| apples | 3 |
| kiwi | 12 |
| Name   | Qty |
|--------+-----|
| apples |   3 |
| kiwi   |  12 |

And on a timestamp with the wrong day name, <2026-11-19 Mon> becomes <2026-11-19 Thu>.

The two hooks let packages add their own behavior. A function on org-ctrl-c-ctrl-c-hook runs before Org’s own checks and takes over the key whenever it returns non-nil; a function on org-ctrl-c-ctrl-c-final-hook runs only if nothing else applies.

Completion

Inside an Org buffer, M-TAB completes the text before point. Org does not bind M-TAB itself; it adds its own function to completion-at-point-functions, and the global M-TAB command uses it. What is completed depends on what you have typed:

ContextCompletes
At the start of an empty headlineTODO keywords
After \Entities and TeX symbols
After : in a headlineTags
After : elsewhereProperty names used in the buffer
After [[Link abbreviations
After [[*Headlines of the buffer, for internal links
After #+Keywords such as TITLE or STARTUP; a second M-TAB after a complete keyword inserts example settings
After #+STARTUP:Startup options

If your window manager uses M-TAB to switch windows, C-M-i runs the same command, and ESC TAB also works.

Structure templates

Blocks such as #+begin_src … #+end_src are typed so often that Org provides a shortcut. C-c C-, (org-insert-structure-template) asks for a key and inserts the matching block at point. With an active region, it wraps the region in the block. For example, selecting the line (message "hi") and choosing src emacs-lisp gives:

#+begin_src emacs-lisp
(message "hi")
#+end_src

The keys come from org-structure-template-alist. In Org 9.8.13 its default value is:

KeyBlock
a#+begin_export ascii
c#+begin_center
C#+begin_comment
e#+begin_example
E#+begin_export
h#+begin_export html
l#+begin_export latex
q#+begin_quote
s#+begin_src
v#+begin_verse

Pressing TAB, RET or SPC at the prompt lets you type any block type instead. You can add your own entries; this one makes el produce an Emacs Lisp source block:

(with-eval-after-load 'org
  (add-to-list 'org-structure-template-alist '("el" . "src emacs-lisp")))

Org Tempo: typing <s TAB

If you prefer to type the shortcut directly in the text, load Org Tempo:

(require 'org-tempo)

You can also enable it by adding org-tempo to org-modules. Then type <s at the start of a line and press TAB: Org replaces the two characters with an empty source block. Every key in org-structure-template-alist works this way, and org-tempo-keywords-alist adds keyword shortcuts. By default <L expands to #+latex: , <H to #+html: , <A to #+ascii: and <i to #+index: .

Speed keys

Most Org commands need a modifier key. Speed keys remove that need in one specific place: when point is at the very beginning of a headline (before the first star), a single letter runs a command. Elsewhere, letters insert themselves as usual. This makes navigation and restructuring fast, especially when you are reviewing an outline.

Speed keys are off by default. Turn them on with:

(setq org-use-speed-commands t)

The built-in keys are defined in org-speed-commands. Some of the most useful ones:

KeyCommandEffect
n, porg-next-visible-heading, org-previous-visible-headingMove to the next or previous headline.
f, borg-forward-heading-same-level, org-backward-heading-same-levelMove between siblings.
uoutline-up-headingMove to the parent.
c, Corg-cycle, org-shifttabCycle the subtree or the buffer.
sorg-toggle-narrow-to-subtreeNarrow to the subtree, or widen again.
U, Dorg-metaup, org-metadownMove the subtree up or down.
r, lorg-metaright, org-metaleftDemote or promote the headline.
torg-todoChange the TODO state.
,org-prioritySet the priority.
:org-set-tags-commandSet tags.
I, Oorg-clock-in, org-clock-outStart or stop the clock.
worg-refileRefile the entry.
?org-speed-command-helpList all active speed keys.

To add your own, append entries to org-speed-commands. Each entry pairs a single character with a command; an entry containing only a string becomes a heading in the help list. Choose letters that are not already taken, because the first matching entry wins:

(setq org-speed-commands
      (append org-speed-commands
              '(("Personal")
                ("y" . org-copy-subtree))))

In-buffer settings

Many Org options can be set in two places: globally in your init file, or for a single file through lines that start with #+. Such a line is called a keyword (an in-buffer setting when it configures Org). It has the form #+NAME: value; the name is case-insensitive.

#+TITLE: Home server notes
#+STARTUP: overview indent
#+TODO: TODO WAIT | DONE
#+FILETAGS: :homelab:

Per-file settings travel with the file, which matters when you share it or open it on another machine. A setting in the file overrides the global default for that buffer only.

flowchart LR
    I["Init file: setq org-..."] -->|global default| B["Buffer settings"]
    S["#+SETUPFILE: shared.org"] -->|keywords read from it| B
    K["#+KEYWORD lines in the file"] -->|override for this file| B
    B -->|inherited by entries| E["Entry"]
    P["Properties of a subtree"] -->|override for some options| E

Figure 2.2: Settings flow from the init file through per-file keywords down to individual entries, with each level able to override the one above for its own scope.

Org reads the keywords when it opens the file. After editing a keyword line, press C-c C-c on it, or Org will keep using the old values. For example, if you add #+TODO: TODO WAIT | DONE to an open buffer, the list of TODO keywords stays ("TODO" "DONE") until you press C-c C-c on that line; afterwards it is ("TODO" "WAIT" "DONE"), and Emacs reports “Local setup has been refreshed”.

The following keywords are the ones you will meet most often:

KeywordSetsExplained in
#+STARTUP:Options applied when the file opens: visibility, indentation, numbering, logging, previewsThis chapter, Document Structure
#+TODO:, #+SEQ_TODO:, #+TYP_TODO:TODO keywords for the fileTODO Items
#+TAGS:Allowed tags and their fast-selection keysTags, Properties and Column View
#+FILETAGS:Tags inherited by every entry in the fileTags, Properties and Column View
#+PROPERTY:Default property values for the fileTags, Properties and Column View
#+CATEGORY:The category shown in the agendaAgenda Views
#+PRIORITIES:Highest, lowest and default priorityTODO Items
#+ARCHIVE:Where archived subtrees goCapture, Refile, Archive and Attachments
#+LINK:Link abbreviationsHyperlinks
#+COLUMNS:Default column view formatTags, Properties and Column View
#+CONSTANTS:Constants for table formulasThe Spreadsheet and Plotting
#+SETUPFILE:Another file (or URL) whose settings are read as if they were in this fileThis chapter
#+TITLE:, #+AUTHOR:, #+OPTIONS:Export settingsExporting

The STARTUP keyword

#+STARTUP: accepts several words separated by spaces, and several #+STARTUP: lines are allowed. A selection of its options:

OptionEffect
overview, content, showall, show2levels, showeverythingInitial visibility
indent, noindentTurn Org Indent mode on or off
num, nonumTurn dynamic headline numbering on or off
hidestars, showstarsHide all but the last star of each headline
hideblocks, nohideblocksFold all blocks on startup
entitiespretty, entitiesplainDisplay entities as UTF-8 characters
linkpreviews, nolinkpreviewsShow image and link previews on startup
latexpreview, nolatexpreviewShow LaTeX previews on startup
logdone, lognotedone, nologdoneRecord a time (or a note) when a task is completed
align, noalignAlign all tables on startup

Type #+STARTUP: and press M-TAB to see the complete list.

Sharing settings with SETUPFILE

When several files need the same settings (the same TODO keywords, tags, or export options), put them in one file and refer to it:

#+SETUPFILE: ~/org/setup/common.org

Org reads only the in-buffer settings from that file and ignores its other content. The value may also be a URL, in which case Org downloads the file and caches it; C-c C-c on the #+SETUPFILE line rereads the file and clears the cache. C-c ' on the line opens a local setup file for editing.

Checking a file with org-lint

Org is forgiving: syntax it does not recognize simply becomes plain text. The disadvantage is that a mistake rarely produces an error message; a link silently goes nowhere, or a drawer is ignored. M-x org-lint runs a set of checks over the buffer and lists suspicious places in a report buffer.

Consider this short file, which contains four mistakes:

#+TITLE: Notes
* Heading
#+BEGIN_SRC
(+ 1 2)
#+END_SRC
See [[*Missing heading]].
:PROPERTIES:
:ID: x
:END:
A note.[fn:9]

Org 9.8.13 reports the following (line number and message):

LineMessage
3Missing language in source block
6Unknown fuzzy location “Missing heading”
7Incorrect contents for PROPERTIES drawer
10Missing definition for footnote [9]

The third report deserves an explanation: a PROPERTIES drawer is only valid directly after a headline, and here it follows a paragraph. Each report also carries a trust level, because some checks can produce false positives.

In the report buffer, these keys are available:

KeyEffect
C-j, TABShow the offending line in the Org buffer.
RETMove to the offending line.
gRun the checks again.
hHide all reports from the same checker.
iAlso ignore that checker in later runs.
SSort the reports by the column at point.

Running org-lint on a file that behaves strangely is a good first step before searching for a bug elsewhere.

Getting help

C-c C-x I (org-info-find-node) opens the section of the Org manual that matches the syntax at point; on a headline, for example, it shows the chapter on document structure. Press q to close the Info window.

If you think you have found a bug, first check whether it happens in a clean Emacs: start emacs -Q (with Org’s lisp directory in the load path if you use a newer Org than the bundled one) and reproduce the problem there. If it persists, M-x org-submit-bug-report prepares an email to the Org mailing list with your Emacs and Org versions and relevant settings already filled in.

A starter configuration

The following configuration collects the suggestions from this chapter. It was evaluated with Org 9.8.13 in batch mode without errors. Treat it as a starting point; later chapters add settings for tasks, the agenda and capture.

;; Global entry points
(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)

;; Where your Org files live
(setq org-directory "~/org")

;; Single-key commands at the start of headlines
(setq org-use-speed-commands t)

;; Indented display of every Org file
(setq org-startup-indented t)

;; <s TAB and friends
(require 'org-tempo)
(with-eval-after-load 'org
  (add-to-list 'org-structure-template-alist '("el" . "src emacs-lisp")))

Summary

  • Org ships with Emacs; check the version with M-x org-version and choose a single installation method for upgrades.
  • Bind org-store-link, org-agenda and org-capture to global keys.
  • Org keys are context-sensitive; C-c C-c is the general “apply” key.
  • M-TAB completes, C-c C-, and <s TAB insert blocks, and speed keys give single-letter commands on headlines.
  • #+ keywords configure a single file; press C-c C-c on them after editing.
  • M-x org-lint finds silent syntax mistakes.

Further reading