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-packagesand upgradeorg. 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 thelispdirectory 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:
- Put point on
* Learn the basicsand pressTABseveral times. The subtree folds and unfolds. - Press
S-TABa few times to switch the whole file between an overview, the list of headlines, and the full text. - On
** TODO Read the structure chapter, pressC-c C-t. The keyword changes fromTODOtoDONE. - Put point at the end of
** TODO Try visibility cyclingand pressM-RET. A new headline appears at the same level. - In the table, change
12to120and pressTAB. The table realigns itself. - Put point on the link and press
C-c C-oto 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:
| Keys | General meaning |
|---|---|
TAB, S-TAB | Cycle visibility; in tables, move between fields. |
M-RET | Insert a new item of the same kind: headline, list item or table row. |
M-LEFT, M-RIGHT, M-UP, M-DOWN | Change the level or the position of the thing at point. |
S-LEFT, S-RIGHT, S-UP, S-DOWN | Change 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 on | C-c C-c does |
|---|---|
| A source block or an inline code call | Evaluate the code (Working with Source Code). |
| A table | Realign it and recalculate the current line; on a #+TBLFM line, apply all formulas. |
| A plain list item with a checkbox | Toggle the checkbox; on other items, repair the list. |
A #+KEYWORD line | Reread all in-buffer settings. |
| A headline | Set tags. |
| A property drawer or property line | Offer property commands. |
| A footnote reference or definition | Jump to the other end. |
A statistics cookie such as [1/3] | Update it. |
A #+BEGIN: line of a dynamic block | Update the block. |
| A timestamp | Correct 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:
| Context | Completes |
|---|---|
| At the start of an empty headline | TODO keywords |
After \ | Entities and TeX symbols |
After : in a headline | Tags |
After : elsewhere | Property 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:
| Key | Block |
|---|---|
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:
| Key | Command | Effect |
|---|---|---|
n, p | org-next-visible-heading, org-previous-visible-heading | Move to the next or previous headline. |
f, b | org-forward-heading-same-level, org-backward-heading-same-level | Move between siblings. |
u | outline-up-heading | Move to the parent. |
c, C | org-cycle, org-shifttab | Cycle the subtree or the buffer. |
s | org-toggle-narrow-to-subtree | Narrow to the subtree, or widen again. |
U, D | org-metaup, org-metadown | Move the subtree up or down. |
r, l | org-metaright, org-metaleft | Demote or promote the headline. |
t | org-todo | Change the TODO state. |
, | org-priority | Set the priority. |
: | org-set-tags-command | Set tags. |
I, O | org-clock-in, org-clock-out | Start or stop the clock. |
w | org-refile | Refile the entry. |
? | org-speed-command-help | List 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:
| Keyword | Sets | Explained in |
|---|---|---|
#+STARTUP: | Options applied when the file opens: visibility, indentation, numbering, logging, previews | This chapter, Document Structure |
#+TODO:, #+SEQ_TODO:, #+TYP_TODO: | TODO keywords for the file | TODO Items |
#+TAGS: | Allowed tags and their fast-selection keys | Tags, Properties and Column View |
#+FILETAGS: | Tags inherited by every entry in the file | Tags, Properties and Column View |
#+PROPERTY: | Default property values for the file | Tags, Properties and Column View |
#+CATEGORY: | The category shown in the agenda | Agenda Views |
#+PRIORITIES: | Highest, lowest and default priority | TODO Items |
#+ARCHIVE: | Where archived subtrees go | Capture, Refile, Archive and Attachments |
#+LINK: | Link abbreviations | Hyperlinks |
#+COLUMNS: | Default column view format | Tags, Properties and Column View |
#+CONSTANTS: | Constants for table formulas | The Spreadsheet and Plotting |
#+SETUPFILE: | Another file (or URL) whose settings are read as if they were in this file | This chapter |
#+TITLE:, #+AUTHOR:, #+OPTIONS: | Export settings | Exporting |
The STARTUP keyword
#+STARTUP: accepts several words separated by spaces, and several #+STARTUP: lines are allowed. A selection of its options:
| Option | Effect |
|---|---|
overview, content, showall, show2levels, showeverything | Initial visibility |
indent, noindent | Turn Org Indent mode on or off |
num, nonum | Turn dynamic headline numbering on or off |
hidestars, showstars | Hide all but the last star of each headline |
hideblocks, nohideblocks | Fold all blocks on startup |
entitiespretty, entitiesplain | Display entities as UTF-8 characters |
linkpreviews, nolinkpreviews | Show image and link previews on startup |
latexpreview, nolatexpreview | Show LaTeX previews on startup |
logdone, lognotedone, nologdone | Record a time (or a note) when a task is completed |
align, noalign | Align 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):
| Line | Message |
|---|---|
| 3 | Missing language in source block |
| 6 | Unknown fuzzy location “Missing heading” |
| 7 | Incorrect contents for PROPERTIES drawer |
| 10 | Missing 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:
| Key | Effect |
|---|---|
C-j, TAB | Show the offending line in the Org buffer. |
RET | Move to the offending line. |
g | Run the checks again. |
h | Hide all reports from the same checker. |
i | Also ignore that checker in later runs. |
S | Sort 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-versionand choose a single installation method for upgrades. - Bind
org-store-link,org-agendaandorg-captureto global keys. - Org keys are context-sensitive;
C-c C-cis the general “apply” key. M-TABcompletes,C-c C-,and<s TABinsert blocks, and speed keys give single-letter commands on headlines.#+keywords configure a single file; pressC-c C-con them after editing.M-x org-lintfinds silent syntax mistakes.
Further reading
- Official manual: Installation, Activation, Conventions, Feedback, Completion, Structure Templates, Speed Keys, The Very Busy C-c C-c Key, Summary of In-Buffer Settings, Org Syntax, Context Dependent Documentation.
- Source at release 9.8.13: lisp/org-keys.el (key bindings and speed keys), lisp/org.el (
org-ctrl-c-ctrl-cand the startup options), lisp/org-tempo.el, lisp/org-lint.el.