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

Introduction

Org is a major mode for GNU Emacs that turns plain text files into an outliner, a task manager, a spreadsheet, a computational notebook and a publishing system. All of these features work on the same kind of file: a text file with the extension .org, written in a small markup language.

This book teaches Org from the first file to the design of your own systems: a task workflow with an agenda, literate programs that generate code and configuration, and documents that export to HTML, LaTeX and other formats.

What Org looks like

An Org file is readable without any software beyond a text editor. Here is a small one:

#+TITLE: Home server

* TODO Replace the backup disk                              :hardware:
DEADLINE: <2026-12-01 Tue>
The current disk reports reallocated sectors.

* Disk usage
| Mount | Used (GB) | Size (GB) |
|-------+-----------+-----------|
| /     |        41 |       120 |
| /data |       812 |      2000 |

* Check free space
#+BEGIN_SRC sh
df -h /data
#+END_SRC

Even without knowing the syntax, you can read the structure: three headlines marked with stars, a task with a deadline and a tag, a table, and a shell command. In Emacs, the same file becomes interactive. The headlines fold and unfold, the task appears in a weekly agenda as its deadline approaches, the table aligns itself and can compute totals, and the shell command can be run with its output inserted below it.

Why plain text

Org’s choice of plain text has practical consequences that shape everything else in the book:

  • Your data stays yours. An Org file opens in any editor, on any system, and will still open in decades. There is no database and no proprietary format.
  • Version control works. Org files diff and merge well in Git, so you can track the history of your notes or tasks like code.
  • Structure is in the syntax. Because headlines, timestamps, tags and properties have a defined textual form, Org (and other programs) can parse a file reliably. The agenda, the exporter and column view are all queries over that parsed structure.
  • Complexity is optional. A file with only headlines and paragraphs is already a valid Org file. You add TODO keywords, tables or code blocks only when you need them.

The price is that Org is best used in Emacs. Other editors can display and edit Org files, but the commands that make Org productive (folding, the agenda, capture, export) are Emacs features.

Who this book is for

The book is written for software engineers who use Emacs at least a little: you should know how to open and save a file, run a command with M-x, and add a line to your init file. No knowledge of Emacs Lisp is required for Parts I to IV; Part V uses a little Lisp to extend Org.

How this book is organized

The book has 20 chapters in 5 parts. Part I is the foundation for everything else. After it, Parts II, III and IV are largely independent, so you can follow the one that matches your goal. Part V combines the earlier parts.

flowchart TD
    P1["Part I: Foundations"] -->|tables inside documents| P2["Part II: Tables"]
    P1 -->|headlines become tasks| P3["Part III: Planning and Tasks"]
    P1 -->|documents and code| P4["Part IV: Code and Publishing"]
    P2 -->|formulas, plots| P5["Part V: Mastery"]
    P3 -->|agenda and capture| P5
    P4 -->|Babel and export| P5

Figure 1.1: Part I is shared ground; Parts II to IV can be read in any order, and Part V draws on all of them.

Part I: Foundations

  1. Introduction: this chapter.
  2. Getting Started: installation, the first file, key conventions, the C-c C-c key, templates, speed keys, in-buffer settings and org-lint.
  3. Document Structure: headlines, folding, motion, structure editing, sparse trees, plain lists, drawers, blocks and display options.
  4. Markup for Rich Contents: emphasis, entities, LaTeX, literal examples, images, captions and footnotes.
  5. Hyperlinks: internal and external links, storing and inserting links, IDs, and custom link types.

Part II: Tables

  1. The Table Editor: creating and editing tables, column widths and Orgtbl mode.
  2. The Spreadsheet and Plotting: references, formulas, recalculation and plots.

Part III: Planning and Tasks

  1. TODO Items: TODO keywords, workflows, logging, priorities, checkboxes and habits.
  2. Tags, Properties and Column View: metadata on entries, searches, and tabular views of an outline.
  3. Dates and Times: timestamps, deadlines, scheduling and repeating tasks.
  4. Clocking, Effort and Timers: measuring time, clock reports, effort estimates and timers.
  5. Capture, Refile, Archive and Attachments: getting items in, moving them, and putting them away.
  6. Agenda Views: collecting tasks and dates from many files into one view, and building custom views.

Part IV: Code and Publishing

  1. Working with Source Code (Babel): evaluating code blocks, passing data between them, and tangling source files.
  2. Exporting: the export dispatcher, settings, and the built-in backends.
  3. Publishing and Citations: publishing projects of many files, and citations with bibliographies.

Part V: Mastery

  1. Hacking and Extending Org: hooks, the element API, new link types and export backends.
  2. Org Beyond the Basics: encryption, org-protocol, mobile access, terminal use and other packages.
  3. Putting It Together: complete systems built from the features in this book.
  4. Key Bindings and Glossary: a key reference grouped by task and a glossary of Org terms.

Suggested paths

  • Task management: chapters 2 and 3, then 8, 10, 12 and 13. Add 9 and 11 when your lists grow, and finish with the task system in chapter 19.
  • Writing and publishing: chapters 2 to 5, then 15 and 16. Read chapter 6 if your documents contain tables.
  • Literate programming and notebooks: chapters 2 to 4, then 14 and 15.

Version and sources

This book describes Org 9.8.13, the latest stable release at the time of writing. All facts were taken from the Org repository at the tag release_9.8.13 (commit e24d7f830679bdedc4f00757753f02ae6aca87be):

  • doc/org-manual.org, the source of the official manual,
  • doc/org-guide.org, the compact guide,
  • lisp/*.el, the Lisp source, which decides whenever the documentation is ambiguous,
  • etc/ORG-NEWS, the list of changes between releases.

Links to source files point to that exact commit in the emacs-straight/org-mode mirror on GitHub, so that they keep showing the code this book describes. The official repository is hosted on Savannah, with a mirror at https://git.sr.ht/~bzg/org-mode; the project website is https://orgmode.org.

The book was written independently of the official manual. It is not a translation or an abridgment of it: the explanations, the order of topics and the examples are its own, and the manual’s text is not copied. Key bindings, names of variables and functions, keywords and short syntax samples are reproduced exactly, because they are the interface of the program. Where the manual and the source disagreed (for instance about the name of a #+STARTUP option), the book follows the source.

Examples that show a result, such as an exported fragment, a recalculated table or the output of a code block, were produced by running Org 9.8.13 in batch Emacs (GNU Emacs 31.1), and the output is shown as Emacs printed it. Each chapter ends with a “Further reading” list that links the corresponding sections of the official manual at https://orgmode.org/manual/ and, where useful, the relevant source files.

Conventions in this book

  • Keys and key sequences are written as code: C-c C-c means Control and c, then Control and c again. M- is Meta (usually Alt) and S- is Shift.
  • Commands, variables and functions are also written as code: org-agenda-files. You can read the documentation of any of them with C-h f (functions) or C-h v (variables).
  • Org examples appear in blocks marked org, configuration in blocks marked elisp, and program output in plain blocks.
  • Each chapter defines Org terms the first time it uses them. Chapter 20 collects them in a glossary.
  • Figures are numbered by chapter in order of appearance: Figure 3.2 is the second figure of chapter 3. The sentence under each figure states what the figure shows.

Further reading