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

Putting It Together

The previous chapters describe Org one feature at a time. Real use rarely looks like that: a working system combines capture with refiling, refiling with the agenda, code blocks with export, and export with publishing. This chapter assembles 4 such systems from the features you already know:

  1. a task system built on capture, refile, the agenda and a weekly review;
  2. a literate Emacs configuration, written in Org and tangled into an init file;
  3. a research notebook that keeps data, code, results and prose in one file;
  4. a small website published from a directory of Org files.

These systems are this book’s suggestions, not part of Org. The Org manual documents the building blocks (capture templates, refile targets, custom agenda commands, tangling, publishing projects) but does not prescribe how to combine them, and many Org users work quite differently. Every option used below is documented in the manual or in the docstrings of Org 9.8.13; each section links to the chapter that explains the feature in detail. Treat the configurations as starting points and change them as soon as your own habits disagree with them.

The table below shows which chapters each system draws on.

SystemMain featuresChapters
Task systemTODO keywords, logging, capture, refile, archive, custom agenda commands, stuck projectsTODO Items, Tags, Properties and Column View, Dates and Times, Capture, Refile, Archive and Attachments, Agenda Views
Literate configurationCode blocks, header arguments, tanglingWorking with Source Code (Babel)
Research notebookNamed tables, code blocks with variables, results, exportThe Table Editor, Working with Source Code (Babel), Exporting
Publishing sitePublishing projects, components, sitemapExporting, Publishing and Citations

Every result shown in this chapter (the captured entries, the agenda, the tangled file, the evaluated notebook and the list of published files) was produced by Org 9.8.13 in Emacs batch mode. The task system uses the sample files from Agenda Views and assumes that “today” is Friday, 13 March 2026, the day of the weekly review.

A task system

The idea

A task system has to answer 3 questions reliably: where does a new commitment go, what should I do now, and is anything slipping? The design below answers them with 3 kinds of files and 2 regular habits.

  • An inbox file receives everything new. Capturing must be fast enough that you never postpone it, so the inbox has no structure at all.
  • Project files hold the real structure. A project is a level-1 headline tagged project; its tasks are the children. Tasks that you can start right now carry the keyword NEXT; the others are TODO, or WAITING when someone else must act first.
  • Dates are reserved for real commitments. A deadline means “this has consequences if late”; a scheduled date means “I plan to start on this day”. Tasks without a real date have no date.
  • A daily view shows today’s fixed items, the NEXT tasks and the WAITING list.
  • A weekly review empties the inbox, looks back over the week and forward at the next one, and finds projects without a next action.

Files and keywords

The system uses the 2 files from Agenda Views, work.org and home.org, plus an inbox.org that starts with only a title. All 3 live in one directory, and the directory itself is the agenda file list, so a new file in it joins the agenda automatically:

(setq org-directory "~/org/")
(setq org-default-notes-file (expand-file-name "inbox.org" org-directory))
(setq org-agenda-files (list org-directory))

The TODO keywords add logging to the workflow, which TODO Items explains in detail. WAITING(w@/!) asks for a note when a task starts waiting (so you record what you are waiting for) and records a timestamp when it stops waiting; DONE(d!) records when a task was finished; CANCELED(c@) asks why. org-log-into-drawer keeps these records in a LOGBOOK drawer, out of the way of the entry text:

(setq org-todo-keywords
      '((sequence "TODO(t)" "NEXT(n)" "WAITING(w@/!)"
                  "|" "DONE(d!)" "CANCELED(c@)")))
(setq org-log-into-drawer t)

Capturing into the inbox

Capture, described in Capture, Refile, Archive and Attachments, opens a small buffer from a template, lets you type, and files the result when you press C-c C-c. For an inbox, the templates should be as short as possible. The target (file "") means org-default-notes-file, so both templates below write to inbox.org:

(setq org-capture-templates
      '(("t" "Task" entry (file "")
         "* TODO %?%i\n:PROPERTIES:\n:CREATED: %U\n:END:\n")
        ("n" "Note" entry (file "")
         "* %?%i :note:\n%U\n%a\n")))
(global-set-key (kbd "C-c c") #'org-capture)

In the templates, %? marks where point is placed, %i inserts the active region if there is one, %U inserts an inactive timestamp with the time, and %a inserts a link to the place where you started the capture. The CREATED property records when the task arrived; it costs nothing at capture time and helps you notice, during the review, tasks that have stayed in the system for months.

After 2 captures with C-c c t, one on Thursday morning and one on Friday, the inbox contains:

#+TITLE: Inbox
* TODO Ask Maria about the hosting budget
:PROPERTIES:
:CREATED: [2026-03-12 Thu 10:42]
:END:
* TODO Book a room for the offsite
:PROPERTIES:
:CREATED: [2026-03-13 Fri 09:15]
:END:

Do not decide anything while capturing. Whether the room booking belongs to a project, whether it needs a date, whether it is a NEXT action: these are questions for the review, when you have time to think.

Refiling into projects

Refiling moves an entry under another headline, in the same file or a different one. With the settings below, C-c C-w offers every headline up to level 2 in every agenda file as a target, and shows targets as paths that start with the file name, such as work.org/Website redesign:

(setq org-refile-targets '((org-agenda-files :maxlevel . 2)))
(setq org-refile-use-outline-path 'file)
(setq org-outline-path-complete-in-steps nil)

Setting org-outline-path-complete-in-steps to nil lets you complete the whole path at once, which works well with completion frameworks that match substrings. You can refile from the inbox file itself, or directly from an agenda line with the same key C-c C-w.

The daily view

For the day, a block agenda gives one screen with today’s calendar, the next actions and the waiting list. It is the command d from Agenda Views, here as the first entry of the custom commands:

(setq org-agenda-custom-commands
      '(("d" "Daily overview"
         ((agenda "" ((org-agenda-span 'day)))
          (todo "NEXT"
                ((org-agenda-overriding-header "Next actions")))
          (todo "WAITING"
                ((org-agenda-overriding-header "Waiting for others")))))))

During the day, you work from this view with the remote editing keys: t to change states, S-RIGHT to postpone, I and O to clock in and out if you track time (see Clocking, Effort and Timers), and g to refresh.

The weekly review

The daily view only shows what is already organized. Once a week, the review brings everything else back under control. Figure 19.1 shows how it connects to the rest of the system.

flowchart TD
  C["Capture: C-c c"] -->|"new entries"| I["inbox.org"]
  I -->|"1. clarify, C-c C-w"| P["Project files"]
  P -->|"2. dates and closed items"| W["Week agenda with log"]
  P -->|"3. no NEXT task"| S["Stuck projects"]
  S -->|"define a NEXT action"| P
  P -->|"4. WAITING entries"| F["Follow up or wait"]
  P -->|"NEXT and today's dates"| D["Daily view: C-c a d"]
  D -->|"ideas during work"| C

Figure 19.1: The weekly review drains the inbox into projects and repairs projects that have stopped moving, so the daily view can be trusted for the rest of the week.

The review is one custom agenda command with 4 blocks, one per step. Each block has an overriding header that says what to do with it:

(setq org-stuck-projects
      '("+project+LEVEL=1/-DONE" ("NEXT") nil ""))

(add-to-list 'org-agenda-custom-commands
             '("r" "Weekly review"
               ((tags "LEVEL=1"
                      ((org-agenda-files (list org-default-notes-file))
                       (org-agenda-overriding-header "1. Inbox: clarify and refile")))
                (agenda ""
                        ((org-agenda-span 'week)
                         (org-agenda-overriding-header "2. This week: done and planned")))
                (stuck ""
                       ((org-agenda-overriding-header "3. Projects without a next action")))
                (todo "WAITING"
                      ((org-agenda-overriding-header "4. Waiting for others"))))
               ((org-agenda-start-with-log-mode t))))

Some choices in this command need a word of explanation.

  • The first block is a match view for LEVEL=1 with org-agenda-files bound to the inbox alone, so it lists every top-level entry of the inbox, whatever its keyword.
  • The stuck-project definition only accepts NEXT as a next action. A project with many TODO tasks but no NEXT is still stuck, because none of its tasks has been judged ready to start. The LEVEL=1 part prevents the tasks inside a project from being treated as projects themselves (see the stuck projects section of Agenda Views).
  • org-agenda-start-with-log-mode sits in the settings shared by all blocks. In Org 9.8.13, log mode is set up when the agenda buffer is created, so the option has no effect inside a single block.

On Friday afternoon, the review over the sample files looks like this:

1. Inbox: clarify and refile
  inbox:      TODO Ask Maria about the hosting budget
  inbox:      TODO Book a room for the offsite

===============================================================================
2. This week: done and planned
Monday      9 March 2026 W11
  work:        9:30-9:45  Team standup
  work:       Scheduled:  TODO [#A] Write the summary                :project::
Tuesday    10 March 2026
  work:       16:10...... Closed:     DONE Submit the abstract       :project::
  home:       Scheduled:  TODO Call the plumber                          :call:
  work:       Deadline:   TODO Collect sales figures                 :project::
Wednesday  11 March 2026
  home:       15:00-16:00 Dentist appointment
  work:       Scheduled:  NEXT Draft the new navigation          :project::web:
Thursday   12 March 2026
  work:       14:00...... 1:1 with Maria
  home:       Alex turns 36
Friday     13 March 2026
  work:       Sched. 4x:  TODO [#A] Write the summary                :project::
  home:       Sched. 3x:  TODO Call the plumber                          :call:
  work:       Sched. 2x:  NEXT Draft the new navigation          :project::web:
  work:        3 d. ago:  TODO Collect sales figures                 :project::
  work:       Deadline:   TODO Review the color palette with design  :project::
  home:       In   7 d.:  TODO Renew passport                          :errand:
Saturday   14 March 2026
Sunday     15 March 2026

===============================================================================
3. Projects without a next action
  work:       Quarterly report                                        :project:
  work:       Conference talk                                         :project:

===============================================================================
4. Waiting for others
  work:       WAITING Final copy from marketing                      :project::

Work through the blocks from top to bottom, using the agenda’s remote editing keys so that you never leave the review buffer for long:

  1. Inbox. For each entry, decide what it is. Refile tasks into their project with C-c C-w, or turn them into NEXT actions with t. Delete what no longer matters with C-k. The inbox should be empty at the end.
  2. This week. Log mode shows what you finished (the closed abstract on Tuesday) next to what you planned. The Friday page is the honest part: Sched. 4x: means the summary has been postponed silently for 4 days. Either do it, give it a realistic new date with C-c C-s, or remove the date if it was never a real commitment. Then open the plain weekly agenda with C-c a a and press f to check the deadlines of the next week. (In this block agenda, Org 9.8.13 rejects f with the error Not allowed in `tags'-type agenda buffer or component.)
  3. Stuck projects. Quarterly report has tasks but none marked NEXT; decide which one you will start and change its keyword. Conference talk has nothing left to do, so either add the next step (preparing the slides) or mark the project itself as done.
  4. Waiting. For each WAITING entry, decide whether to send a reminder. The note that the keyword asked for when you set it tells you what exactly you are waiting for.

Finish with g to rebuild the review: the inbox block should be empty and the stuck-project block should list only projects you have consciously put on hold.

Archiving finished work

Finished projects should leave the project files, both to keep the files readable and to keep the agenda fast. C-c C-x C-s (org-archive-subtree) moves the subtree at point to the archive location; in the agenda, $ does the same for the entry on the current line. By default the archive location is a file next to the original, named after it with _archive appended, so work.org is archived into work.org_archive. The variable org-archive-location changes this, as described in Capture, Refile, Archive and Attachments.

A good moment to archive is the end of the weekly review: a project whose last task is done, such as the conference talk once the talk has been given, can go.

A literate Emacs configuration

The idea

An Emacs configuration grows over years, and after a while it is hard to remember why a line is there. Literate programming reverses the usual relation between code and comments: you write a document that explains your choices, and the code lives in blocks inside it. Org’s tangling, described in Working with Source Code (Babel), extracts the code blocks into a plain Emacs Lisp file that Emacs loads at startup. Figure 19.2 shows the 2 outputs of the same source file.

flowchart LR
  O["config.org"] -->|"C-c C-v t: tangle"| E["init.el"]
  E -->|"loaded at startup"| M["Emacs"]
  O -->|"C-c C-e: export"| H["HTML or PDF documentation"]

Figure 19.2: One Org file is both the source of the configuration and its documentation, because tangling and export read the same blocks.

The source file

The file below is a complete, if small, literate configuration. The #+PROPERTY line sets a default header argument for every Emacs Lisp block in the file, so each block is written to init.el without repeating :tangle on every block:

#+TITLE: My Emacs configuration
#+PROPERTY: header-args:emacs-lisp :tangle init.el

* Header
The first line turns on lexical binding for the generated file.

#+begin_src emacs-lisp
;;; init.el --- generated from config.org  -*- lexical-binding: t -*-
#+end_src

* Appearance
#+begin_src emacs-lisp
(setq inhibit-startup-screen t)
(column-number-mode 1)
#+end_src

* Org
** Agenda
#+begin_src emacs-lisp
(setq org-agenda-files '("~/org/"))
(global-set-key (kbd "C-c a") #'org-agenda)
#+end_src

** Experiments
This block is kept for reference but not written to init.el.

#+begin_src emacs-lisp :tangle no
(setq org-agenda-span 'day)
#+end_src

The headlines do the work that comments do in a plain init file, but better: you can fold them, move them with the structure editing commands, tag them, and link to them. The last block shows how a header argument on a single block overrides the file-wide default: :tangle no keeps it out of the generated file.

Tangling

C-c C-v t (org-babel-tangle) writes every block with a :tangle target to its file. Tangling this file reports Tangled 3 code blocks from config.org and produces:

;;; init.el --- generated from config.org  -*- lexical-binding: t -*-

(setq inhibit-startup-screen t)
(column-number-mode 1)

(setq org-agenda-files '("~/org/"))
(global-set-key (kbd "C-c a") #'org-agenda)

Blocks are separated by a blank line, in the order in which they appear in the document. The experiment block is missing, as intended.

Making it practical

A few habits make a literate configuration pleasant to maintain:

  • Treat init.el as a build product. Edit only config.org, and tangle after every change. If you keep the configuration in version control, decide once whether to commit init.el; committing it means that a new machine can start Emacs before Org has ever tangled anything.
  • Test a block before tangling it. C-c C-c in an Emacs Lisp block evaluates it in the running Emacs, so you can try a setting immediately.
  • Use org-babel-load-file if you prefer one step. It tangles the Emacs Lisp blocks of an Org file and loads the result; its docstring explains the details.
  • Keep secrets out. The document is meant to be read, exported and perhaps published; tokens and passwords belong in a separate file that the configuration loads.

For noweb references, which let one block include another by name, and for the full list of tangling header arguments, see Working with Source Code (Babel).

A research notebook

The idea

A notebook keeps an investigation in one place: the question, the data, the code that analyzes it, the results, and your interpretation. In Org, the data can be a table, the code a source block that reads the table through a variable, and the results are inserted below the block when you evaluate it. Export turns the notebook into a report that shows code and results together.

A notebook file

The notebook below compares response times before and after a change. The table has a name, so a code block can refer to it, and the #+PROPERTY line makes every block export both its code and its results:

#+TITLE: Response times after the cache change
#+PROPERTY: header-args :exports both
#+OPTIONS: toc:nil author:nil

* Data
Response times in milliseconds, measured before and after the change.

#+NAME: timings
| run | before | after |
|-----+--------+-------|
|   1 |    212 |   148 |
|   2 |    198 |   151 |
|   3 |    225 |   139 |

* Analysis
#+NAME: mean-improvement
#+begin_src emacs-lisp :var rows=timings
(let* ((before (mapcar (lambda (r) (nth 1 r)) rows))
       (after (mapcar (lambda (r) (nth 2 r)) rows))
       (mean (lambda (xs) (/ (apply #'+ xs) (float (length xs))))))
  (format "%.1f ms faster on average"
          (- (funcall mean before) (funcall mean after))))
#+end_src

* Environment
#+begin_src shell :results output
uname -s
#+end_src

The header argument :var rows=timings passes the table to the block as a list of rows. Because the table has a header row separated by a horizontal rule, Org removes the header before passing the data, so rows contains only the 3 numeric rows.

Evaluating

Only Emacs Lisp is enabled by default (org-babel-load-languages is ((emacs-lisp . t))), so the shell block needs one more language:

(org-babel-do-load-languages 'org-babel-load-languages
                             '((emacs-lisp . t) (shell . t)))

C-c C-c evaluates the block at point; C-c C-v b (org-babel-execute-buffer) evaluates all blocks in the buffer. After evaluation, the Analysis and Environment sections contain the results:

#+RESULTS: mean-improvement
: 65.7 ms faster on average
#+RESULTS:
: Linux

Evaluating code is the one Org feature that can damage your system if a file comes from someone else. By default, Org asks before each evaluation. The variable org-confirm-babel-evaluate controls this; besides t and nil it accepts a function of the language and the code, so you can decide case by case instead of turning the question off globally. Working with Source Code (Babel) discusses this in more detail.

Exporting the report

Export, described in Exporting, evaluates the blocks again (unless org-export-use-babel is nil) and renders the notebook in the chosen format. The plain text exporter (C-c C-e t a) gives a compact report:

                _______________________________________

                 RESPONSE TIMES AFTER THE CACHE CHANGE
                _______________________________________


1 Data
======

  Response times in milliseconds, measured before and after the change.

   run  before  after
  --------------------
     1     212    148
     2     198    151
     3     225    139


2 Analysis
==========

  ,----
  | (let* ((before (mapcar (lambda (r) (nth 1 r)) rows))
  |        (after (mapcar (lambda (r) (nth 2 r)) rows))
  |        (mean (lambda (xs) (/ (apply #'+ xs) (float (length xs))))))
  |   (format "%.1f ms faster on average"
  |           (- (funcall mean before) (funcall mean after))))
  `----

  ,----
  | 65.7 ms faster on average
  `----


3 Environment
=============

  ,----
  | uname -s
  `----

  ,----
  | Linux
  `----

For a report addressed to readers who do not care about code, change the file-wide default to :exports results. For one that teaches the method, keep both. :exports none leaves a block out of the report completely, which suits blocks that only prepare data for later ones.

Growing the notebook

As a notebook grows, a few features of earlier chapters become useful:

  • Table formulas (The Spreadsheet and Plotting) can compute simple derived columns directly in the data table, without any code block.
  • A :session header argument keeps an interpreter running between blocks, so expensive data loading happens once.
  • Results can be tables (:results table) or files (:results file), so a block can produce a chart image that the export includes.
  • An inactive timestamp under each heading, inserted with C-c !, turns the notebook into a dated lab journal.

A small publishing site

The idea

Publishing, described in Publishing and Citations, exports a whole directory tree of Org files to another directory, copies the other files the pages need, and only rebuilds what has changed. A personal site or a team handbook fits this model well: you write pages in Org, and a single command produces a directory of HTML files that any web server can serve.

The project definition

The site uses this layout:

src/
  index.org
  posts/agenda-tips.org
  img/week.png
public/          (created by publishing)

A publishing project is an entry in org-publish-project-alist. Different kinds of files usually need different treatment, so the site is split into 2 components: one exports Org files to HTML, the other copies images and stylesheets unchanged. A third entry groups them, so that one command publishes both. Figure 19.3 shows the structure.

flowchart LR
  S["src/*.org"] -->|"org-html-publish-to-html"| A["site-pages"]
  M["src/img/*.png"] -->|"org-publish-attachment"| B["site-static"]
  A -->|"HTML and sitemap"| P["public/"]
  B -->|"copied files"| P
  G["site"] -->|"components"| A
  G -->|"components"| B
  P -->|"rsync or similar tool"| W["Web server"]

Figure 19.3: A project groups components that each handle one kind of file, and all of them write into the same publishing directory.

The definition:

(require 'ox-publish)
(setq org-publish-project-alist
      '(("site-pages"
         :base-directory "~/site/src/"
         :base-extension "org"
         :recursive t
         :publishing-directory "~/site/public/"
         :publishing-function org-html-publish-to-html
         :auto-sitemap t
         :sitemap-title "All pages"
         :sitemap-sort-files anti-chronologically
         :with-toc nil
         :section-numbers nil)
        ("site-static"
         :base-directory "~/site/src/"
         :base-extension "png\\|jpg\\|css"
         :recursive t
         :publishing-directory "~/site/public/"
         :publishing-function org-publish-attachment)
        ("site" :components ("site-pages" "site-static"))))

Most properties are self-explanatory. :recursive t includes subdirectories, so posts/ is published too. :auto-sitemap t generates a page that lists all pages; :sitemap-sort-files anti-chronologically puts the newest pages first. Options such as :with-toc and :section-numbers are ordinary export settings, applied to every page in the component.

Publishing

C-c C-e P x (org-publish) asks for a project and publishes it; C-c C-e P p publishes the project of the current file, C-c C-e P f only the current file, and C-c C-e P a all projects. Publishing site reports each file as it is processed and produces this directory:

public/img/week.png
public/index.html
public/posts/agenda-tips.html
public/sitemap.html

The generated sitemap.org in the source directory, from which sitemap.html is exported, reflects the directory structure:

#+TITLE: All pages

- [[file:index.org][Notes]]
- posts
  - [[file:posts/agenda-tips.org][Three agenda tips]]

Links between Org files, such as [[file:sitemap.org][list of all pages]] in index.org, become links between the HTML files.

Org remembers when each file was last published and skips files that have not changed. When a change affects pages whose own files did not change, for example an edit to a file that the pages include with #+SETUPFILE or #+INCLUDE, force a full rebuild with a prefix argument (C-u C-c C-e P x) or through org-publish-use-timestamps-flag.

Getting the files to a server

The publishing directory can be remote, through Tramp, but the manual itself suggests a simpler approach for most cases: publish to a local directory and then synchronize it with a dedicated tool such as rsync or Unison. Local publishing is faster, and synchronization tools check contents and file attributes as well as timestamps. With this approach, the site-static component is optional, because the synchronization tool can copy images directly from the source tree.

Designing your own system

The 4 systems above share a pattern that is worth making explicit, because it applies to any system you build with Org:

  • Keep one source of truth. The agenda shows entries but stores nothing; init.el is generated from config.org; the HTML pages are generated from Org files. Edit the source, regenerate the rest.
  • Let structure arrive late. Capture into an unstructured inbox and organize during a review. Write a notebook first and extract a library later. Structure imposed too early slows down the moment of writing.
  • Make the regular check a single command. A weekly review that requires 5 different views will be skipped; one block agenda will not. The same is true for tangling and publishing.
  • Add one feature at a time. Every option in this chapter solves a specific problem. Add clocking when you need to know where time goes, effort estimates when you need to plan capacity, and tags when match views would answer a real question.

When something in your files looks wrong, M-x org-lint checks a buffer for common syntax mistakes, as described in Getting Started.

Further reading