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:
- a task system built on capture, refile, the agenda and a weekly review;
- a literate Emacs configuration, written in Org and tangled into an init file;
- a research notebook that keeps data, code, results and prose in one file;
- 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.
| System | Main features | Chapters |
|---|---|---|
| Task system | TODO keywords, logging, capture, refile, archive, custom agenda commands, stuck projects | TODO Items, Tags, Properties and Column View, Dates and Times, Capture, Refile, Archive and Attachments, Agenda Views |
| Literate configuration | Code blocks, header arguments, tangling | Working with Source Code (Babel) |
| Research notebook | Named tables, code blocks with variables, results, export | The Table Editor, Working with Source Code (Babel), Exporting |
| Publishing site | Publishing projects, components, sitemap | Exporting, 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 keywordNEXT; the others areTODO, orWAITINGwhen 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
NEXTtasks and theWAITINGlist. - 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=1withorg-agenda-filesbound to the inbox alone, so it lists every top-level entry of the inbox, whatever its keyword. - The stuck-project definition only accepts
NEXTas a next action. A project with manyTODOtasks but noNEXTis still stuck, because none of its tasks has been judged ready to start. TheLEVEL=1part 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-modesits 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:
- Inbox. For each entry, decide what it is. Refile tasks into their project with
C-c C-w, or turn them intoNEXTactions witht. Delete what no longer matters withC-k. The inbox should be empty at the end. - 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 withC-c C-s, or remove the date if it was never a real commitment. Then open the plain weekly agenda withC-c a aand pressfto check the deadlines of the next week. (In this block agenda, Org 9.8.13 rejectsfwith the errorNot allowed in `tags'-type agenda buffer or component.) - Stuck projects.
Quarterly reporthas tasks but none markedNEXT; decide which one you will start and change its keyword.Conference talkhas nothing left to do, so either add the next step (preparing the slides) or mark the project itself as done. - Waiting. For each
WAITINGentry, 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.elas a build product. Edit onlyconfig.org, and tangle after every change. If you keep the configuration in version control, decide once whether to commitinit.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-cin an Emacs Lisp block evaluates it in the running Emacs, so you can try a setting immediately. - Use
org-babel-load-fileif 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
:sessionheader 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.elis generated fromconfig.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
- Org manual: Capture, Capture templates, Refile and Copy, Archiving, Tracking TODO state changes
- Org manual: Stuck projects, Block agenda, Setting options for custom commands
- Org manual: Working with Source Code, Extracting Source Code, Environment of a Code Block, Evaluating Code Blocks, Exporting Code Blocks
- Org manual: Publishing, Project alist, Simple example, Complex example, Uploading Files, Triggering Publication
- Source: lisp/org-capture.el, lisp/org-refile.el, lisp/ob-tangle.el, lisp/ox-publish.el