--- title: "The Complete Practical Guide to GNU Emacs Org Mode" date: 2026-09-01 summary: "A progressive, vanilla-first technical book for using Org Mode as a durable system for planning, knowledge, writing, computation, and publishing." tags: [pesquisa, org-mode, emacs, plain-text, knowledge-management, reproducible-research] flowerColor: "#72d6c9" --- # The Complete Practical Guide to GNU Emacs Org Mode Org Mode is a system for working with structured plain text inside GNU Emacs. It begins with an unusually small set of primitives—headings, lists, timestamps, links, properties, and blocks—and composes them into an outliner, task manager, agenda, notebook, spreadsheet, publishing tool, and executable research environment. This book teaches that composition. It starts with almost no configuration, grows one running example, and introduces extensions only after the corresponding vanilla limitation is clear. The baseline is **GNU Emacs 30.2** and **Org 9.8**, the current stable versions verified on 1 September 2026. Default bindings below assume unmodified GNU Emacs; distributions such as Doom and Spacemacs deliberately replace many of them. The central principle is simple: > Org is powerful not because it contains a thousand unrelated features, but because a small vocabulary of structured plain-text primitives can be combined into many systems. ## How to read this book Read Parts I–III in order if Emacs is new to you. Later parts can be used as a reference. Type the examples: Org's model becomes clearer through folding, moving, scheduling, and executing real text than through passive reading. Every major chapter ends with a short summary and exercises at three levels. “Built in” means shipped with Org or Emacs. “External” identifies an independently maintained package or program. “Convention” means a workflow choice rather than a feature. The evolving example starts here: ```text ~/org/ ├── inbox.org ├── projects.org ├── notes.org └── journal.org ``` Later we add archives, attachments, bibliography data, source code, and published output. This gradual growth is intentional. ## Part I — Foundations ## 1. Org's mental model Markdown primarily describes how text should be rendered. Org also describes structure and behavior. A heading can simultaneously be a section of a book, a task with a deadline, a database-like record with properties, a clockable unit of work, and a target visible in a computed agenda. An Org file remains readable text: ```org * TODO Prepare the release :software: DEADLINE: <2026-09-18 Fri> :PROPERTIES: :OWNER: Maya :EFFORT: 3:00 :END: The release requires a clean migration test. - [ ] Run the test suite - [ ] Update the deployment notes ``` The text is the source of truth. Agenda does not copy this task; it computes a view of it. Export does not replace the file; it transforms it. Babel does not turn Org into a proprietary notebook; it evaluates marked source blocks and writes results back according to declared rules. This is why “Markdown with extra features” is inadequate. Org is an interactive outline data model, a command set, parsers, exporters, and conventions built on plain text. Its cost is equally real: Emacs has a learning curve, collaboration is not Google Docs-like, mobile clients are third-party, and a highly customized setup becomes software that you must maintain. ### A short history GNU Emacs descends from the extensible Emacs editor tradition begun in the 1970s; GNU Emacs was launched by Richard Stallman in 1984. Carsten Dominik began Org as an outlining and planning mode, announced it publicly in 2003, and developed the compositional model that still defines it. Org entered GNU Emacs in 2006. Bastien Guerry maintained it from 2011 through 2024; Ihor Radchenko became maintainer in December 2024. Babel, created chiefly by Eric Schulte with Dan Davison, joined Org core in version 7.0. ### Version discipline in 2026 GNU publishes Emacs 30.2 as the stable release (14 August 2025). The current Org manual identifies Org 9.8. Emacs ships a bundled Org; GNU ELPA and Org's repository may provide a newer build. Mixing installation methods can load old and new libraries in one session, producing baffling errors. Prefer the bundled version while learning. If upgrading, follow Org's official isolated-upgrade procedure and verify with `M-x org-version`. Old web advice needs scrutiny. The modern citation system uses `org-cite` syntax, not only older `org-ref` recipes. `org-structure-template-alist` plus `C-c C-,` superseded the old ` [2026-09-15 Tue] <2026-09-15 Tue 09:00-10:30> ``` Use `C-c .` for an active timestamp, `C-c !` for an inactive one, `C-c C-s` to schedule, and `C-c C-d` to set a deadline. ```org * TODO Prepare conference slides SCHEDULED: <2026-09-15 Tue> DEADLINE: <2026-09-20 Sun -3d> ``` `SCHEDULED` means “do not expect this task before this date” or “plan to work on it then.” It is not a synonym for due date. `DEADLINE` expresses the last acceptable date; `-3d` begins warning three days earlier. Repeaters distinguish scheduling semantics: ```org * TODO Weekly review SCHEDULED: <2026-09-04 Fri +1w> ``` `+1w` advances from the previous timestamp, `++1w` catches up from the last scheduled occurrence, and `.+1w` schedules relative to completion. Consult the current manual before choosing: the difference matters after missed repetitions. Enable habit display with: ```elisp (require 'org-habit) (add-to-list 'org-modules 'org-habit) ``` A habit is a repeating TODO with `STYLE` set to `habit`: ```org * TODO Walk for thirty minutes SCHEDULED: <2026-09-01 Tue .+1d/3d> :PROPERTIES: :STYLE: habit :END: ``` The Agenda consistency graph makes patterns visible. Track only behavior where the graph improves decisions; turning every ordinary activity into a streak creates administrative guilt rather than insight. ### Exercises - **Basic:** Insert active and inactive timestamps and observe their different appearance. - **Practical:** Schedule work and give it a separate deadline with warning period. - **Advanced:** Create one habit, miss a test occurrence, and study how your chosen repeater advances. ## 7. Agenda: computed views over source files Agenda reads declared files, selects entries, and displays a temporary operational view. Edits made with Agenda commands update the source heading. The source file—not the Agenda buffer—is authoritative. ```elisp (setq org-agenda-files (list (expand-file-name "inbox.org" org-directory) (expand-file-name "projects.org" org-directory) (expand-file-name "areas.org" org-directory))) ``` `C-c [` adds the current file to the Agenda list for the session; `C-c ]` removes it. `M-x org-agenda` (commonly globally bound by users to `C-c a`) opens the dispatcher. In it, `a` shows a calendar agenda, `t` a global TODO list, `m` a tag match, and `s` a text search. Verify choices in the dispatcher because custom commands can add or replace keys. Inside the Agenda, `n`/`p` move lines, `RET` visits the source, `TAB` displays it, `t` changes TODO state, `s` schedules, `d` sets a deadline, `r` refreshes, `f` moves forward, `b` backward, and `q` quits. These are Agenda-buffer bindings, not Org-buffer bindings. Tags and property queries turn Agenda into a selective dashboard: ```text work+TODO="NEXT" OWNER="Maya"+PRIORITY="A" software/!NEXT|WAITING ``` Query syntax varies by view; use the manual's matching section and minibuffer prompts rather than guessing punctuation. A useful custom command grows from a real need: ```elisp (setq org-agenda-custom-commands '(("d" "Daily focus" ((agenda "" ((org-agenda-span 1))) (todo "NEXT") (tags-todo "+waiting"))))) ``` This creates a block view: one day, all NEXT items, then tasks tagged waiting. It does not create or duplicate tasks. ### Applied views - **Personal:** today's appointments, household deadlines, and NEXT actions. - **Software:** release milestone plus `software` tasks grouped by state. - **Business:** meetings and actions filtered by client property. - **Research:** reading deadlines, experiment tasks, and scheduled writing. - **Recurring administration:** repeating tax, backup, and renewal tasks. Agenda performance depends chiefly on the files scanned and the work performed while parsing/fontifying them. Do not put an entire archive or every note into `org-agenda-files`. Narrow the scope before reaching for obscure tuning variables. The manual includes “Speeding Up Your Agendas” and profiling is better than folklore. ### Summary Agenda is a queryable lens. Design source files for durable meaning and views for temporary decisions. ### Exercises - **Basic:** Add two files and open weekly Agenda and global TODO views. - **Practical:** Reschedule a task from Agenda, then inspect its source. - **Advanced:** Build a two-block custom command for one real workday. ## 8. Capture and Refile: input before organization Capture separates fast recording from later classification: ```text thought → capture → inbox.org → review → refile → project, note, or task ``` Bind the command globally: ```elisp (global-set-key (kbd "C-c c") #'org-capture) ``` Then add a few templates: ```elisp (setq org-capture-templates `(("t" "Task" entry (file ,(expand-file-name "inbox.org" org-directory)) "* TODO %?\n:PROPERTIES:\n:CREATED: %U\n:END:\n%i\n%a") ("n" "Note" entry (file ,(expand-file-name "notes.org" org-directory)) "* %? :note:\n%U\n%i\n%a") ("j" "Journal" entry (file+olp+datetree ,(expand-file-name "journal.org" org-directory)) "* %U %?\n%i"))) ``` Each entry has a key, description, capture type, target, and template. `%?` leaves point for editing; `%U` inserts an inactive timestamp; `%i` includes the active region; `%a` stores an annotation link. Other expansions include `%t` for active time, `%u` for inactive time, `%x` for clipboard contents, and prompted fields such as `%^{Title}`. Clipboard capture can expose sensitive data; use it deliberately. Finish with `C-c C-c` or abort with `C-c C-k`. Avoid twenty templates. A template earns its place when it captures distinct metadata or targets a genuinely different review process. Refile moves a heading with `C-c C-w`: ```elisp (setq org-refile-targets '((org-agenda-files :maxlevel . 3))) (setq org-refile-use-outline-path 'file) (setq org-outline-path-complete-in-steps nil) ``` The target specification permits headings up to level three in Agenda files. Full outline-path completion disambiguates repeated headings. During review, clarify the captured item, make it actionable if necessary, refile it, or delete it. Capture without review merely creates a trusted pile of forgotten text. ### Summary Capture optimizes interruption; Refile restores structure. Their connecting practice is a regular inbox review. ### Exercises - **Basic:** Capture one task and finalize it. - **Practical:** Capture a bookmark with annotation, then refile it under a project. - **Advanced:** Add a meeting template with title, participants property, timestamp, and action-item subtree. ## 9. Tags, properties, metadata, and Column View Tags are lightweight categories placed on headings: ```org #+FILETAGS: :work: * NEXT Review contract :legal:@computer: ``` File tags and parent tags can be inherited. Configure controlled vocabularies and groups: ```elisp (setq org-tag-alist '((:startgroup) ("@home" . ?h) ("@office" . ?o) (:endgroup) ("deep" . ?d) ("waiting" . ?w))) ``` The group makes locations mutually exclusive. Use tags for membership and cross-cutting context. Use headings for hierarchy. Use properties when a field has a value. ```org * Deploy customer portal :PROPERTIES: :ID: 6f2c8f52-82f7-4dba-942a-f82d2cfa2ca4 :CATEGORY: Portal :OWNER: Maya :STATUS: Approved :EFFORT: 5:00 :END: ``` Properties can inherit when `org-use-property-inheritance` permits it, but global inheritance adds parsing cost and can make values surprising. Prefer explicit, selective inheritance. `C-c C-x p` sets a property; `C-c C-c` on a property line refreshes it. Column View turns heading properties into a temporary table-like summary: ```org #+COLUMNS: %40ITEM(Task) %TODO %OWNER %EFFORT{:} %CLOCKSUM ``` Run `M-x org-columns` on a scope. This is excellent for a lightweight project dashboard. It is not a relational database: constraints, concurrent transactions, and complex joins belong elsewhere. ### Exercises - **Basic:** Add two tags and one OWNER property. - **Practical:** Search Agenda for tasks owned by one person. - **Advanced:** Define a Column View that sums effort and clock time for a project. ## Part IV — Tables, time, and records ## 10. Tables as structured calculations Type `| Name | Score |` and press `TAB`; Org aligns it: ```org | Name | Hours | Rate | Total | |-------+-------+------+-------| | Alice | 2.5 | 80 | 200 | | Bob | 3 | 70 | 210 | #+TBLFM: $4=$2*$3 ``` `TAB` and `S-TAB` move among cells. `M-left`/`M-right` move columns; `M-up`/`M-down` move rows. `C-c -` inserts a horizontal rule. `C-c ^` sorts. `C-c C-c` recalculates at point; `C-u C-c C-c` recalculates the table. Formula references include `$2` (column 2), `@3` (row 3), `@2$4` (one cell), and ranges such as `@2$2..@>$2`; `@>` means the last row. Org can use Calc syntax or Lisp formulas. Name tables when Babel should consume them: ```org #+name: monthly-hours | Month | Hours | |-------+-------| | Jan | 18 | | Feb | 21 | ``` Use Org tables for small, inspectable datasets, estimates, inventories, and report inputs. Use a spreadsheet or database for large datasets, rich charts, complex validation, multiple editors, or transactional integrity. ### Exercises - **Basic:** Create, align, and sort a three-row table. - **Practical:** Calculate quantity × unit price and a total. - **Advanced:** Name a table and pass it into a Babel block in Chapter 13. ## 11. Clocking, effort, reports, and habits Clocking records time beneath a heading. Use `C-c C-x C-i` (`org-clock-in`) and `C-c C-x C-o` (`org-clock-out`). `C-c C-x C-j` jumps to the active clock; `C-c C-x C-r` inserts a clock report. ```org * DONE Diagnose database latency :PROPERTIES: :EFFORT: 1:30 :END: :LOGBOOK: CLOCK: [2026-09-01 Tue 09:10]--[2026-09-01 Tue 10:25] => 1:15 :END: ``` Clock history lets you resume recent tasks. Idle-time resolution can ask what to do with time when Emacs detects inactivity; customize `org-clock-idle-time` only after understanding its prompts. Dynamic clock tables summarize a scope: ```org #+BEGIN: clocktable :scope subtree :maxlevel 3 :block thisweek #+END: ``` Place point on `#+BEGIN` and press `C-c C-c` to update it. Consultants can group by client property; students by course; developers by project; writers by chapter. Reports remain only as honest as the clocking behavior. Use coarse categories if minute-level recording interrupts the work it measures. ### Exercises - **Basic:** Clock five minutes on a practice task. - **Practical:** Compare EFFORT with actual CLOCKSUM in Column View. - **Advanced:** Build a weekly clock table for one project and interpret—not merely collect—the result. ## 12. Journals and datetrees Org does not prescribe one journal layout: - A single file makes chronological search and capture simple but grows indefinitely. - Yearly files keep manageable boundaries and easy archiving. - Monthly files reduce size further but scatter cross-month context. - Daily files integrate naturally with file-based PKM, at the cost of many files. - Datetrees create year/month/day heading hierarchies inside a file. The capture template from Chapter 8 uses `file+olp+datetree`. It creates dates only when needed. Journal timestamps should generally be inactive so the Agenda is not flooded. Choose by retrieval: if you remember *when*, chronological journals work well. If you remember *what project*, capture a journal entry with a link or refile durable conclusions into project notes. A journal is not automatically a knowledge base; synthesis creates reusable knowledge. ### Exercises - **Basic:** Add today's entry under a datetree. - **Practical:** Link one journal observation to a project. - **Advanced:** Compare yearly-file and daily-file Git diffs for your likely workflow. ## Part V — Org Babel and reproducible work ## 13. Executable documents Org Babel connects prose, code, data, and results. Insert a source block with `C-c C-, s` and choose a language, or type it: ```org #+begin_src python print("Hello, Org") #+end_src ``` Place point in it and press `C-c C-c` (`org-babel-execute-src-block`). Org asks for confirmation and inserts results according to header arguments. Enable only languages you use: ```elisp (org-babel-do-load-languages 'org-babel-load-languages '((emacs-lisp . t) (python . t) (shell . t) (sql . t) (js . t))) ``` Support libraries, interpreters, and exact language names differ. For example, JavaScript uses Org's `ob-js`; shell uses `ob-shell`; SQL requires a suitable client and connection settings. Enabling a Babel backend does not install its external runtime. Header arguments control evaluation: ```org #+name: doubled #+begin_src python :var values='(1 2 3) :results value table :cache yes return [[x, x * 2] for x in values] #+end_src ``` Common arguments include `:results value|output`, `:exports code|results|both|none`, `:session`, `:var`, `:dir`, `:file`, `:cache yes`, and `:tangle`. They may be set per block, subtree property, language, or file: ```org #+PROPERTY: header-args:python :results value :exports both ``` More global settings are convenient but harder to audit. Prefer local declarations in shared or security-sensitive documents. ### Data flow Tables can become block inputs: ```org #+name: expenses | Item | Cost | |---------+------| | Hosting | 20 | | Backup | 10 | #+begin_src python :var rows=expenses :results value return sum(row[1] for row in rows) #+end_src ``` Named blocks can feed later blocks. Noweb composes source text: ```org #+name: greeting #+begin_src python name = "reader" #+end_src #+begin_src python :noweb yes :results output <> print(f"Hello, {name}") #+end_src ``` Sessions preserve interpreter state and can be convenient for exploration, but hidden state weakens reproducibility. Prefer isolated blocks with explicit inputs for final research. Tangling extracts code: ```org #+begin_src emacs-lisp :tangle init-generated.el (setq inhibit-startup-screen t) #+end_src ``` Run `C-c C-v t` (`org-babel-tangle`). Documentation now becomes the maintained source of executable files. This is literate programming, not merely documentation containing copied code. `:cache yes` avoids recomputation when Org judges inputs unchanged, but cached results can outlive external dependencies or files not represented in the hash. Record environment versions and provide an explicit rebuild path. File-producing blocks declare `:file` and return a link: ```org #+begin_src python :var rows=monthly-hours :results file graphics :file figures/hours.png import matplotlib.pyplot as plt labels = [r[0] for r in rows] values = [r[1] for r in rows] plt.bar(labels, values) plt.savefig("figures/hours.png", dpi=150, bbox_inches="tight") return "figures/hours.png" #+end_src ``` ### Shell, SQL, JavaScript, and Lisp ```org #+begin_src shell :results output printf 'Kernel: '; uname -s #+end_src #+begin_src sql :engine sqlite :db inventory.sqlite :results table SELECT service, status FROM services ORDER BY service; #+end_src #+begin_src js :results output console.log(JSON.stringify({generated: true})); #+end_src #+begin_src emacs-lisp :results value (mapcar #'upcase '("org" "babel")) #+end_src ``` Exact SQL connection options and JS runtime behavior depend on backends and external tools. Keep credentials out of blocks and document dependencies beside the experiment. ### Security: an Org file can be a program Babel asks before evaluating source blocks through `org-confirm-babel-evaluate`. Do not globally set it to `nil` merely to remove friction. A block can delete files, exfiltrate data, run shell commands, or execute arbitrary Emacs Lisp with your user privileges. Trust boundaries include more than Babel. File-local variables can request Lisp evaluation; export may evaluate Babel; links may invoke handlers; tangling writes executable files. Emacs prompts for risky local variables—read the prompt. Safe practice: 1. Inspect an untrusted Org file as text before execution. 2. Keep confirmation enabled; if automation requires exceptions, use a narrowly scoped predicate. 3. Run risky research in a container or low-privilege account. 4. Never embed API keys in source blocks or header arguments. 5. Pin dependencies and preserve inputs. 6. In CI, use a minimal init file and an explicit allowlist of languages. 7. Treat generated results as untrusted until validated. ### Reproducible research workflow ```text raw data → named Python block → Org result table → plot block → interpretation → export ``` Store immutable raw data separately. Record checksums, interpreter and package versions, random seeds, and commands. Keep commentary next to the result it interprets. Re-run from a clean process before publication. Compared with Jupyter, Org offers transparent text diffs, many languages in one document, mature outlining, and flexible export. Jupyter offers stronger browser collaboration, ubiquitous scientific widgets, and a familiar notebook ecosystem. Both can hide session state. Choose based on collaborators and execution requirements, not identity. ### Summary Babel creates declared data flow between prose, code, and results. Its greatest strength—execution—is also its greatest security risk. ### Exercises - **Basic:** Execute a Python or shell block that prints one line. - **Practical:** Feed an Org table to code and return a calculated table. - **Advanced:** Produce a figure from immutable data in a clean process, recording versions and checksum. ## 14. Literate Emacs configuration A literate configuration explains decisions around executable Lisp: ```org * Interface Wrap prose visually; do not modify file line endings. #+begin_src emacs-lisp :tangle init-generated.el (add-hook 'org-mode-hook #'visual-line-mode) #+end_src ``` The simplest startup strategy tangles manually, then loads the generated file from `init.el`: ```elisp (load (expand-file-name "init-generated.el" user-emacs-directory) 'noerror) ``` Advantages include rationale beside code, section-level organization, and reusable blocks. Costs include another build step, harder startup debugging, and the temptation to narrate trivial settings. Keep a small bootstrap readable without Org, tangle deterministically, and test the generated file with a clean Emacs. If startup fails, run `emacs -Q`, load the generated file incrementally, enable `toggle-debug-on-error`, and inspect `*Messages*`. The generated file—not beautiful prose—is what Emacs executes. ## Part VI — Writing, citation, and publishing ## 15. Export, images, math, and citations `C-c C-e` opens the export dispatcher. Built-in backends cover HTML, LaTeX/PDF, OpenDocument, ASCII/UTF-8 text, and Org; Markdown exporters ship with Org but may need `(require 'ox-md)` or the relevant backend. PDF normally means Org → LaTeX → a TeX engine, so a working TeX distribution is an external dependency. Document metadata is plain text: ```org #+TITLE: Service Reliability Report #+AUTHOR: Maya Chen #+DATE: 2026-09-01 #+OPTIONS: toc:2 num:t #+LANGUAGE: en ``` HTML can use `#+HTML_HEAD:` for a stylesheet. LaTeX can use document-class and header keywords, but avoid filling the source with backend-specific markup until a real requirement exists. Pandoc is useful when a target or house style is better served by its conversion ecosystem; native Org exporters understand Org semantics most directly. Images are links: ```org #+CAPTION: Weekly processing time. #+NAME: fig:processing [[file:figures/processing-time.png]] ``` `C-c C-x C-v` toggles inline image display (`org-toggle-inline-images`). Keep media in predictable relative directories so preview, export, Git, and publishing agree. Math uses LaTeX fragments: ```org The relationship is \( E = mc^2 \). \[ \bar{x} = \frac{1}{n}\sum_{i=1}^{n}x_i \] ``` Preview with `C-c C-x C-l` (`org-latex-preview`). Rendering requires an appropriate TeX/toolchain or configured preview process. Modern Org citations are native: ```org #+bibliography: references.bib The method follows earlier literate-programming work [cite:@schulte2012]. #+print_bibliography: ``` Use `M-x org-cite-insert`. Org's default `basic` processor reads BibTeX or CSL bibliographies. Built-in export processors include `basic`, `csl`, `bibtex`, `natbib`, and `biblatex`; CSL processing uses `citeproc-el`, while the last three target LaTeX-derived workflows. Select one explicitly when reproducible typography matters: ```org #+cite_export: csl styles/apa.csl ``` Older tutorials centered on `org-ref` may still describe useful specialist workflows, but native `org-cite` is the current baseline. Do not mix syntaxes casually. ### Long-form writing For a book, use one master file for front matter and includes, or one file until editing friction justifies splitting: ```org #+TITLE: Reliable Small Systems #+INCLUDE: "chapters/01-foundations.org" #+INCLUDE: "chapters/02-operations.org" #+bibliography: references.bib #+print_bibliography: ``` Use named figures and tables, footnotes, stable custom IDs, and relative paths. Put prose, bibliography, and small assets in Git. Generate large or reproducible outputs during the build. Export in CI before release so missing figures and TeX errors fail visibly. ### Exercises - **Basic:** Export a two-section document to HTML. - **Practical:** Add a captioned image, one citation, and a bibliography. - **Advanced:** Export the same source to HTML and PDF and document backend-specific differences. ## 16. `org-publish`: a small static-site pipeline Publishing maps source projects to output projects: ```text notes/*.org → org-publish → public/*.html assets/* → org-publish → public/assets/* ``` ```elisp (setq org-publish-project-alist '(("site-notes" :base-directory "~/site/notes/" :base-extension "org" :publishing-directory "~/site/public/" :recursive t :publishing-function org-html-publish-to-html :with-author nil :with-creator nil :html-head "") ("site-assets" :base-directory "~/site/assets/" :base-extension "css\\|png\\|jpg\\|svg" :publishing-directory "~/site/public/assets/" :recursive t :publishing-function org-publish-attachment) ("site" :components ("site-notes" "site-assets")))) ``` Run `M-x org-publish-project` and choose `site`. Org records timestamps for incremental publishing; use a prefix argument or `org-publish-all` when a complete rebuild is necessary. Deployment is a separate, explicit step—copying to a server, pushing a hosting branch, or uploading an artifact. Org publishing is excellent when Org is already the authoring source and the site is mostly documents. Dedicated static-site generators usually provide richer themes, asset pipelines, taxonomies, preview servers, and contributor ecosystems. Org can also feed one: export Markdown or HTML as an intermediate artifact, but understand the additional transformation. ### Exercises - **Basic:** Publish one Org page and one CSS file locally. - **Practical:** Add two linked pages and verify relative links in `public/`. - **Advanced:** Perform a clean batch rebuild and deploy only the validated output. ## Part VII — A durable knowledge system ## 17. Vanilla knowledge management before graph packages Vanilla Org already supplies file links, heading links, IDs, search, Agenda, capture, and exports. A personal wiki can therefore begin with four files and a few map headings: ```org * Maps ** Distributed systems - [[id:...][Consensus notes]] - [[id:...][Failure testing]] ``` Reference notes preserve sourced facts. Project notes support an outcome. Daily notes preserve chronology. Evergreen notes express a durable idea in your own words. These are conventions, not mutually exclusive Org object types. Create stable IDs for heavily referenced headings. Keep titles descriptive. Record sources at capture time. Periodically synthesize notes into maps or project decisions. A graph visualization cannot substitute for this intellectual work. ### org-roam and Denote in 2026 **org-roam** models a network of nodes backed by Org files/headings and an SQLite database that provides backlinks and queries. The official repository is active and mature: v2.3.1 was released 26 June 2025 and code was pushed in April 2026; it is GPL-3.0-or-later. It suits users who genuinely navigate by backlinks and node relationships. Costs include database maintenance, extra concepts, and a workflow that can overwhelm beginners. **Denote** emphasizes predictable filenames, file types, identifiers, signatures, and keywords without requiring a central database for the core model. It is very actively maintained: GNU ELPA carried 4.2.x in May 2026 and the official repository was active in August 2026; GPL-3.0-or-later. It suits file-oriented users who want disciplined naming and linking across Org and other text formats. Vanilla Org is enough when search, IDs, and a modest file tree answer retrieval needs. Choose org-roam for graph-shaped node workflows; Denote for file-naming and portable note management. Do not install either before you can articulate the retrieval failure it solves. ### Digital gardens and transclusion A digital garden is a publishing convention: evolving linked notes exposed to readers. `org-publish` can implement it. `org-transclusion` can display referenced content in-place without copying it; its repository was active in April 2026, although its latest formal GitHub release remains v1.3.0 from 2022 while source declares 1.4.0. Treat it as active but release-irregular, GPL-3.0-or-later, and situational. ### Exercises - **Basic:** Build a five-note vanilla wiki with file links. - **Practical:** Replace fragile heading-name links with IDs where justified. - **Advanced:** Pilot the same ten notes in vanilla Org and either Denote or org-roam; compare retrieval, not screenshots. ## 18. Synchronization, Git, backup, encryption, and mobile Plain text improves inspectability and merging; it does not eliminate concurrent-edit conflicts. Two devices can edit the same subtree and a sync service may create conflict copies or silently choose a winner. ### Sync choices | Method | Strength | Main risk | |---|---|---| | Git | history, branches, meaningful diffs | manual discipline; conflicts; no automatic mobile UX | | Syncthing | direct continuous replication | concurrent conflicts; device availability | | Cloud drive/WebDAV | broad device support | provider behavior, latency, privacy, conflict copies | | Direct remote editing/TRAMP | one authoritative remote file | network dependency and latency | A robust pattern uses synchronization for availability and a separate backup system for recovery. Keep local versioned snapshots, an offsite copy, and tested restores. Git is not by itself a backup when every replica can be deleted or force-pushed. Emacs backup and auto-save files protect recent edits but need deliberate location and cleanup policies. Avoid editing the same file simultaneously on two devices. Let synchronization finish before opening and after closing. Commit coherent changes. Review conflict files as text; never bulk-delete them before comparison. ### Mobile reality in 2026 Mobile support is third-party. **Orgzly Revived** is an actively maintained GPL-3.0-or-later Android app; v1.23.0 was released 12 August 2026. **beorg** is a proprietary, actively updated iOS app (2026.8 in July 2026) oriented toward Org agenda and tasks. **Plain Org** is a proprietary iOS editor/rendering app still available, but its latest verifiable release is 1.10.0 from February 2025, so current activity is uncertain. No mobile client implements every Emacs/Org behavior. Test repeated timestamps, drawers, custom TODO sequences, IDs, and file encodings with your actual files. Git on mobile gives history but adds commit/merge friction. Syncthing is natural on Android; iOS background and filesystem constraints often favor app-supported cloud/WebDAV routes. Keep a recoverable copy before changing sync engines. ### Encryption and sensitive information `org-crypt` encrypts selected subtrees with GnuPG, typically marked by a configured tag. It protects ciphertext at rest when the key remains secret. It does not automatically protect headings left outside the encrypted subtree, filenames, Git history containing earlier plaintext, swap/backup files, clipboard contents, screen capture, a compromised running Emacs, or exports made while decrypted. Passwords, recovery codes, private keys, and production credentials belong in a dedicated password/secret manager. If encrypted Org is appropriate for narrative sensitive notes, verify GPG recovery keys, exclude plaintext artifacts, inspect history, and test restoration. A few encrypted headings do not make the whole knowledge system secure. ### Exercises - **Basic:** Initialize Git for sample files and inspect one readable diff. - **Practical:** Simulate a conflict on copies and resolve it without data loss. - **Advanced:** Write and test a restore procedure from an offsite backup; measure recovery time. ## Part VIII — Integration and extension ## 19. Packages, completion, web capture, mail, and presentations Emacs 30 includes `package.el`, built-in `use-package`, and `package-vc`. Prefer GNU ELPA and NonGNU ELPA where possible; MELPA offers breadth but often tracks snapshots. A minimal declaration is readable: ```elisp (use-package org-modern :ensure t :hook (org-mode . org-modern-mode)) ``` `use-package` organizes loading and configuration; `:ensure` asks the package system to install. It is not itself a package manager. `package-vc-install` can install directly from version-control sources; pinning a commit improves reproducibility. ### Curated package status, 1 September 2026 | Package | Purpose | License | Status | Beginner? | Vanilla alternative | |---|---|---|---|---|---| | [org-roam](https://github.com/org-roam/org-roam) | Nodes, backlinks, graph PKM | GPL-3.0-or-later | Active/mature | Later | IDs, links, search | | [Denote](https://protesilaos.com/emacs/denote) | Predictable file notes | GPL-3.0-or-later | Very active/mature | After basics | Files, capture, IDs | | [org-modern](https://github.com/minad/org-modern) | Visual styling | GPL-3.0-or-later | Very active | Optional | Org faces | | [org-appear](https://github.com/awth13/org-appear) | Reveal hidden markup | MIT | Active | Optional | Keep markers visible | | [org-super-agenda](https://github.com/alphapapa/org-super-agenda) | Agenda grouping | GPL-3.0-or-later | Mature, slow maintenance | Advanced | Custom block agendas | | [org-ql](https://github.com/alphapapa/org-ql) | Programmatic Org queries | GPL-3.0 | Mature, slow maintenance | Advanced | Agenda matches/mapping API | | [org-transclusion](https://github.com/nobiot/org-transclusion) | Live transclusion | GPL-3.0-or-later | Active, irregular releases | Advanced | Links/INCLUDE | | [org-present](https://github.com/rlister/org-present) | Present inside Emacs | GPL-3.0-or-later | Dormant/minimal | Situational | Narrowing/font scaling | | [org-reveal/ox-reveal](https://github.com/yjwen/org-reveal) | Reveal.js export | GPL-3.0-or-later | Legacy/dormant | No default recommendation | HTML/Beamer export | Package status is evidence, not a verdict. Mature software may need few commits; nevertheless, dormant exporters coupled to fast-moving JavaScript deserve more caution than a tiny presentation helper. ### Modern completion, optionally Built-in completion is enough. Vertico changes minibuffer presentation; Orderless adds flexible matching; Consult supplies richer search/navigation commands; Embark provides context actions; Corfu provides in-buffer completion popups. They can improve capture target selection, heading navigation, citation insertion, and `M-x`, but they do not change Org's data model. Add one layer at a time and preserve standard command names in your notes. ### Browser and mail capture `org-protocol` registers `org-protocol://` URLs and routes browser calls through `emacsclient` to handlers such as `capture`, `store-link`, and `open-source`. It requires a running Emacs server and operating-system URL-handler registration. URL-decode and inspect external inputs; a capture endpoint is an input boundary, not magic clipboard glue. Notmuch and mu4e are external Emacs mail systems. Their Org link/capture integrations can store a stable message search or identifier beside action items. Reliability depends on the mail database and link type. Never copy confidential message bodies into broadly synchronized notes by default. RSS can be represented by Org's RSS facilities or external readers that store links. Capture the durable reference and your annotation, not an uncontrolled full-page scrape. ### Presentations Vanilla export can produce Beamer or HTML. `org-present` offers a minimal in-Emacs presentation mode but has seen little activity since 2024. `org-reveal`/`ox-reveal` exports to reveal.js but appears dormant since 2023. Use them only after testing against current dependencies; do not make an important talk depend on an untested legacy pipeline. ### Exercises - **Basic:** Use built-in completion to find a heading; note what is already sufficient. - **Practical:** Install one cosmetic package and confirm your files remain ordinary Org when it is disabled. - **Advanced:** Create a browser capture route in a test profile and threat-model its inputs. ## 20. Terminal, remote work, automation, and machine parsing Org's outlining, TODOs, Agenda, tables, and Babel work well in terminal Emacs. GUI Emacs is better for proportional fonts, high-quality image display, rich clipboard behavior, and comfortable math previews. Terminal key encodings can make some combinations unavailable; run `C-h k` to see what Emacs actually receives. TRAMP lets `find-file` edit paths such as `/ssh:host:/etc/service.conf`. Direct remote editing keeps one authoritative copy and works well for modest files. Large remote directories, many subprocesses, or Agenda scans over TRAMP can be slow. Never run unfamiliar remote Babel blocks merely because the document is local. ### Batch workflows Automation should load a small, controlled init file: ```bash emacs --batch -Q \ --load build.el \ --funcall my-org-build ``` `--batch` disables interactive display; `-Q` avoids personal and site initialization. `build.el` should load needed libraries, set explicit paths, perform export/publish/tangle, log useful context, and signal errors so CI receives a nonzero exit. Pin Emacs/Org and external tool versions. Treat repository Org files as executable input if Babel export is enabled. Typical jobs include exporting a report, publishing a site, tangling configuration, and generating an Agenda artifact. Reproducibility improves when the build does not depend on an interactive session's package state. ### Structure-aware parsing `grep` is excellent for literal discovery but cannot reliably distinguish a heading from text inside an example block, parse nested objects, or understand affiliated keywords. Org supplies element and mapping APIs, including `org-element-context`, `org-element-at-point`, `org-element-parse-buffer`, and `org-map-entries`. Org 9.8 continues parser work, so consumers of low-level AST details should consult current docstrings and release notes. Use regex for intentionally simple, constrained files. Use Org's parser for transformations, export-aware tools, refactoring, and nested syntax. External parsers exist in multiple languages, but compatibility varies because Org syntax is richer and partly context-sensitive. Test against a representative corpus and preserve unknown constructs. ### AI and Org in 2026 Org's readable text is good LLM context: select a subtree, include source links, and export to Markdown if a tool does not understand Org. Keep the Org file as source of truth; store AI summaries as clearly labeled derivatives and verify claims against primary material. For private notes, prefer local models or carefully scoped excerpts, understand provider retention, and remove credentials and personal data. Retrieval-augmented generation can index headings and IDs, but stale embeddings and missing access controls are real failure modes. Org remains fully useful without AI, which is an important resilience property. ### Exercises - **Basic:** Open and edit an Org file in terminal Emacs. - **Practical:** Write a clean batch export function and check its exit status. - **Advanced:** Compare a regex heading count with `org-element-parse-buffer` on a file containing example blocks. ## Part IX — Complete workflows ## 21. Six working systems built from the same primitives ### Personal system ```text ~/org/ ├── inbox.org quick unprocessed capture ├── projects.org outcomes and next actions ├── areas.org recurring responsibilities ├── notes.org durable reference notes ├── journal.org chronological record └── archive.org inactive material ``` Capture to inbox. During daily review, clarify, refile, schedule only date-bound work, and choose a small number of NEXT actions. Weekly, inspect projects without next actions, future deadlines, waiting items, and clock data. Archive completed subtrees with `C-c C-x C-a` or `org-archive-subtree` according to your archive policy. ### Software development One project subtree can contain a requirement, source links, decisions, TODOs, deployment checklist, test-output block, and release notes. Link to Git issues rather than duplicating team state. Use Babel for safe read-only reports or deterministic build snippets; keep destructive deployment commands confirmable and outside automatic export. ```org * NEXT Release 2.4 :PROPERTIES: :OWNER: Maya :END: ** Decision log ** Test evidence ** Deployment checklist - [ ] Database backup verified - [ ] Rollback tested ``` ### System administration Maintain server inventory as properties or tables, recurring maintenance as TODOs, incident timelines as inactive timestamps, and diagnostic commands as nonexecuted examples until reviewed. Link to the secret manager; never store plaintext credentials. A post-incident subtree can tangle sanitized documentation while sensitive raw evidence stays access-controlled elsewhere. ### Business management Capture meetings into dated headings. Record decisions separately from discussion, assign OWNER and due date to actions, and surface them through Agenda. Org works well for a small owner-operated system; a team needing permissions, notifications, simultaneous editing, and audit workflows likely needs a collaborative service. ### Research Keep bibliography, reading notes with citation keys, immutable data, named Babel blocks, generated figures, and interpretation together. Pin environments, rebuild cleanly, and export the article. Org organizes the research narrative; it does not replace domain-specific validation or peer review. ### Writing a book Use a master Org file, chapter includes, an images directory, BibTeX data, custom IDs, and Git. Capture research into an inbox; refile verified notes into chapter research; draft without executing untrusted code; export HTML frequently and PDF at milestones. A release tag should identify exact prose, bibliography, generated assets, and build environment. ## 22. Four coherent styles **Minimalist:** a few files, Capture, Agenda, links, no external packages. Lowest maintenance and best starting point; less automated backlink discovery. **Project-oriented:** properties, deadlines, dependencies, effort, clocking, dashboards. Strong for individual execution; can become bureaucracy if metadata does not drive decisions. **Research-oriented:** citations, Babel, tables, figures, export, immutable inputs. Strong provenance; external runtimes and reproducibility discipline add complexity. **PKM-oriented:** many small notes, IDs, maps, optional Denote or org-roam. Strong associative retrieval; easy to accumulate fragments without synthesis. These styles can coexist in separate files. Do not force journal entries, operational tasks, academic sources, and permanent notes into identical templates. ## 23. Comparisons without winners | System | Org's advantage | Other system's advantage | |---|---|---| | Markdown | hierarchy, tasks, metadata, tables, execution, export semantics | broader renderer/tool interoperability, simpler syntax | | Notion | local ownership, scriptability, Git, offline longevity | real-time collaboration, databases, polished web/mobile UX | | Obsidian | deep outlining, Agenda, Babel, programmable Emacs | approachable Markdown vault, graph/plugin UX, mobile app | | Logseq | mature files, export, task and computation breadth | block/journal-first interaction and queries | | Jupyter | text diffs, outlining, multi-language literate documents | scientific widgets, browser sharing, notebook ecosystem | | Task managers | customizable data and integrated notes | notifications, collaboration, mobile polish, less maintenance | Org can replace a personal task manager when flexibility and ownership outweigh reminders and team collaboration. It should not replace systems of record that require access control, concurrent transactions, regulated audit logs, or reliable push notifications. ## 24. Performance, maintenance, and anti-patterns Measure before tuning. Large files can slow fontification and structural operations; thousands of Agenda files multiply scanning; Babel results and inline images increase display work; org-roam requires database synchronization; archives included in Agenda revive old costs. First responses are structural: reduce `org-agenda-files`, archive completed work outside Agenda, split files at lifecycle boundaries, avoid global property inheritance, limit expensive hooks, and profile with Emacs' profiler. Keep a clean-profile reproduction to distinguish Org from configuration. Common anti-patterns: - Configuring before learning hides the model behind borrowed behavior. - Huge copied configs combine version assumptions and undocumented dependencies. - Too many TODO states make transitions ambiguous. - Too many tags turn retrieval into taxonomy maintenance. - Too many capture templates slow the supposedly fast inbox. - Putting every note in Agenda makes the daily view noisy and slow. - Installing org-roam before learning links and IDs hides what it adds. - Globally disabling Babel confirmation expands the attack surface. - Storing secrets in plain text mistakes convenience for security. - Endless Org maintenance displaces the work the system exists to support. Quarterly, remove unused templates, packages, and dashboard blocks. A smaller system is easier to trust. ## Part X — Troubleshooting and reference ## 25. A diagnostic method When something breaks: 1. Read the exact error and `*Messages*`. 2. Enable `M-x toggle-debug-on-error` and reproduce. 3. Describe the command, variable, key, and mode with `C-h f`, `C-h v`, `C-h k`, and `C-h m`. 4. Check versions with `M-x emacs-version` and `M-x org-version`. 5. Reproduce under `emacs -Q`; load only Org and a minimal snippet. 6. Add external packages one at a time. 7. Search current official manuals and release notes using the exact symbol. | Symptom | Checks | |---|---| | File absent from Agenda | Inspect `org-agenda-files`; save file; confirm active timestamp/TODO; refresh with `r` | | Capture template error | Check tuple shape, target path, parentheses, `%` expansion, and `*Messages*` | | Refile target missing | Save target file; inspect `org-refile-targets`; check maximum level and completion path | | Babel language disabled | Inspect `org-babel-load-languages`; require correct `ob-*`; verify external interpreter | | Block fails | Execute minimal code outside Org; inspect working directory, session, header arguments, and backtrace | | Export fails | Isolate smallest document; inspect exporter backend and external TeX/Pandoc logs | | Image preview broken | Verify relative path, image support, file format, and `org-display-remote-inline-images` if remote | | Link breaks after move | Prefer IDs for durable targets; refresh ID locations; avoid unmanaged attachment moves | | Bundled/external conflict | Inspect `org-version`, `locate-library`, and load path; use one install method | | Sync conflict | Stop editors/sync, preserve both copies, compare and merge, then resume | | Slow Agenda | Reduce scope, exclude archives, disable suspect hooks, profile | | Stale org-roam DB | Use package's current database synchronization command and inspect its diagnostics | An error that disappears under `emacs -Q` is probably configuration or extension interaction. An error reproducible with bundled Org and a tiny file is a stronger Org bug candidate. Report exact versions, minimal source, steps, and backtrace. ## 26. Consolidated, explained configuration This configuration contains only concepts already introduced: ```elisp ;; One canonical directory. (setq org-directory (expand-file-name "~/org/")) ;; Only operational files participate in Agenda. (setq org-agenda-files (mapcar (lambda (name) (expand-file-name name org-directory)) '("inbox.org" "projects.org" "areas.org"))) ;; A small task state machine with transition logging. (setq org-todo-keywords '((sequence "TODO(t)" "NEXT(n)" "WAITING(w@)" "|" "DONE(d!)" "CANCELLED(c@)"))) ;; Deliberately small context vocabulary. (setq org-tag-alist '((:startgroup) ("@home" . ?h) ("@office" . ?o) (:endgroup) ("deep" . ?d) ("waiting" . ?w))) ;; Capture is available outside Org buffers. (global-set-key (kbd "C-c c") #'org-capture) (setq org-capture-templates `(("t" "Task" entry (file ,(expand-file-name "inbox.org" org-directory)) "* TODO %?\n:PROPERTIES:\n:CREATED: %U\n:END:\n%i\n%a") ("j" "Journal" entry (file+olp+datetree ,(expand-file-name "journal.org" org-directory)) "* %U %?\n%i"))) ;; Refile to headings up to level three in operational files. (setq org-refile-targets '((org-agenda-files :maxlevel . 3)) org-refile-use-outline-path 'file org-outline-path-complete-in-steps nil) ;; Enable only reviewed, installed Babel languages. (org-babel-do-load-languages 'org-babel-load-languages '((emacs-lisp . t) (python . t) (shell . t))) ;; Keep the evaluation prompt: Org documents may execute programs. (setq org-confirm-babel-evaluate t) ;; Visual wrapping changes display, not file contents. (add-hook 'org-mode-hook #'visual-line-mode) ``` What is intentionally absent: a package framework, org-roam, visual decoration, global property inheritance, automatic execution, and dozens of templates. Add them only in response to observed needs. ## Appendix A — Syntax quick reference ```org * TODO [#A] Heading :tag: SCHEDULED: <2026-09-02 Wed> DEADLINE: <2026-09-05 Sat -2d> :PROPERTIES: :ID: UUID-HERE :OWNER: Maya :END: Paragraph with *bold*, /italic/, _underline_, +strike+, ~code~, =verbatim=, a [[https://example.org][link]], a citation [cite:@key], and a footnote.[fn:1] - [ ] Checkbox 1. Ordered item term :: Description | A | B | |---+---| | 2 | 4 | #+TBLFM: $2=$1*2 #+name: example #+begin_src python :results output print("structured and executable") #+end_src [fn:1] Footnote definition. ``` ## Appendix B — Verified default bindings Bindings are defaults for Org 9.8 in ordinary GNU Emacs, and many are context-sensitive. Use `C-h k` in your installation. | Area | Binding | Command / purpose | |---|---:|---| | Folding | `TAB`, `S-TAB` | `org-cycle`, `org-shifttab` | | Heading navigation | `C-c C-n/p/f/b/u` | next/previous/forward/back/up headings | | Structure | `M-up/down` | move subtree or list item | | Structure | `M-left/right` | promote/demote | | New heading/item | `M-RET` | `org-meta-return` | | TODO | `C-c C-t` | `org-todo` | | Priority | `C-c ,` | `org-priority` | | Schedule | `C-c C-s` | `org-schedule` | | Deadline | `C-c C-d` | `org-deadline` | | Timestamp | `C-c .`, `C-c !` | active/inactive timestamp | | Tags | `C-c C-q` | `org-set-tags-command` | | Property | `C-c C-x p` | `org-set-property` | | Link | `C-c C-l`, `C-c C-o` | insert/edit, open | | Refile | `C-c C-w` | `org-refile` | | Archive | `C-c C-x C-a` | archive subtree default command | | Clock | `C-c C-x C-i/o/j/r` | in/out/goto/report | | Attach | `C-c C-a` | `org-attach` dispatcher | | Table | `TAB`, `S-TAB`, `C-c C-c` | navigate/recalculate | | Babel | `C-c C-c` in block | execute source block | | Babel | `C-c C-v t` | tangle | | Block template | `C-c C-,` | insert structure template | | Inline image | `C-c C-x C-v` | toggle images | | LaTeX preview | `C-c C-x C-l` | preview fragments | | Export | `C-c C-e` | export dispatcher | | Agenda dispatcher | `M-x org-agenda` | often user-bound to `C-c a` | | Capture | `M-x org-capture` | often user-bound to `C-c c` | ## Appendix C — Important commands and variables | Symbol | Purpose and caveat | |---|---| | `org-agenda` | Open dispatcher; meaningful only with appropriate Agenda files | | `org-capture` | Start capture; templates and global binding are user configuration | | `org-refile` | Move subtree; target scope controls discoverability and cost | | `org-id-get-create` | Add stable ID; maintain ID locations for cross-file resolution | | `org-babel-execute-src-block` | Execute code; preserve confirmation for untrusted content | | `org-babel-tangle` | Extract source files; may overwrite declared targets | | `org-export-dispatch` | Choose export; backends and external programs vary | | `org-publish-project` | Publish named project; deployment remains separate | | `org-agenda-files` | Source set for Agenda; excessive scope hurts clarity/performance | | `org-directory` | Conventional base directory; does not move or create files itself | | `org-todo-keywords` | State sequences; changing them affects existing workflows | | `org-capture-templates` | Capture grammar; malformed targets fail at capture time | | `org-refile-targets` | Candidate destinations; broad scans cost time | | `org-tag-alist` | Controlled tag vocabulary and fast keys | | `org-use-property-inheritance` | Inheritance policy; broad enablement can surprise and slow scans | | `org-confirm-babel-evaluate` | Execution confirmation; disabling globally is dangerous | | `org-babel-load-languages` | Enabled backends; does not install interpreters | | `org-cite-global-bibliography` | Bibliography defaults; file-level declarations improve portability | | `org-publish-project-alist` | Publishing pipeline definitions and directories | | `org-attach-id-dir` | Root for ID-based attachments; synchronize/backup with notes | ## Appendix D — Glossary **Agenda:** computed view over selected Org files. **Babel:** Org's source-block execution and literate-programming system. **Buffer:** Emacs' in-memory text object. **Capture:** rapid structured input into a target. **Clocking:** recording time intervals under headings. **Drawer:** collapsible region for metadata or logs. **Heading:** star-prefixed node in an Org outline. **Hook:** list of functions run at an event. **ID:** stable unique target for links. **Major mode:** primary editing behavior for a buffer. **Property:** key/value metadata attached to an entry. **Refile:** move or copy a subtree to another outline location. **Subtree:** heading plus all descendants and content. **Tag:** categorical label used for filtering. **Tangling:** extracting source blocks into code files. **Timestamp:** active planning or inactive recording date/time. **Window:** viewport displaying a buffer. **Frame:** top-level Emacs display containing windows. ## Appendix E — A 30-day learning path Week 1: use headings, folding, lists, links, and four files with no extra packages. Week 2: add TODOs, timestamps, Agenda, one capture template, and daily inbox review. Week 3: add properties, tables, clocking, IDs, and one complete project. Week 4: choose one specialty—Babel research, long-form export, publishing, or PKM—and build a small end-to-end result. At day 30, remove anything unused before adding extensions. ## 27. Deep practice: designing the data model The shortest path to a fragile Org system is to assign every concept to the wrong primitive. Before adding configuration, decide what a thing *is*. ### Heading, list item, property, tag, or file? A heading has identity, children, planning state, and foldable content. Use it when the item deserves navigation or lifecycle. A list item is lighter: it belongs to the surrounding heading and is ideal for steps, options, or a short checklist. Converting every bullet to a heading creates visual and Agenda noise; burying important tasks in checkboxes makes them invisible to TODO searches. A property answers a field-like question: Who owns this? What system does it affect? What is the estimate? A tag answers membership: Is it done at home? Is it related to security? A heading answers containment: Which project contains this task? A file answers operational boundaries: Is this material scanned together, shared together, backed up together, or retired together? Consider a server migration: ```org * TODO Migrate atlas.example.net :infrastructure: DEADLINE: <2026-10-16 Fri> :PROPERTIES: :ID: 49aacdf2-4c16-4bb6-847d-94e082910307 :OWNER: Noor :EFFORT: 8:00 :SERVICE: atlas :END: ** Decision record The new host will use encrypted storage because ... ** Checklist - [ ] Verify restore on an isolated network - [ ] Reduce DNS TTL - [ ] Announce maintenance window ** Evidence [[file:evidence/atlas-restore-2026-10-10.txt]] ``` The migration is a heading because it has a lifecycle. The decision is a child heading because it should be linkable and preserved. Checklist steps are list items because they do not need independent scheduling. OWNER and SERVICE are properties because they hold values. The broad domain is a tag. Evidence is an external file because raw logs should not dominate the outline. ### Inheritance and locality Org hierarchy naturally provides context. A task nested under `* Client A` is visibly related to that client even without a tag. Property and tag inheritance can make that relationship queryable, but invisible inherited state can surprise readers. Use file-level settings for facts true throughout a file: ```org #+FILETAGS: :research: #+PROPERTY: header-args:python :session none :results replace ``` Use a parent property when all descendants share it: ```org * Customer portal :PROPERTIES: :CLIENT: Northwind :END: ``` Then explicitly configure only properties whose inheritance you need: ```elisp (setq org-use-property-inheritance '("CLIENT" "AREA")) ``` The list is safer than `t`, which makes every property inheritable. Query results become easier to explain, and Agenda does less work. ### State versus evidence TODO state answers “where is this item in its workflow now?” A LOGBOOK answers “what transitions occurred?” An inactive timestamp answers “when did this observation happen?” A linked artifact answers “where is the supporting evidence?” Do not encode historical events as permanent tags such as `:was_blocked:`. Let logs preserve history and current metadata describe current state. ### Stable identity policy Not every heading needs an ID. Create one when another file, external system, or published page should refer to the heading independently of its title and location. IDs create maintenance work: they need unique generation and discoverable locations. A local fuzzy link is easier for a short document; a `CUSTOM_ID` produces readable HTML anchors; an Org `ID` best survives refactoring across files. A practical policy is: 1. Use fuzzy links within a small document. 2. Use file-plus-heading links for nearby, moderately stable material. 3. Use `CUSTOM_ID` for deliberate public anchors. 4. Use generated IDs for durable cross-file knowledge links. ### A design exercise with an answer Suppose a laboratory tracks experiments. Each experiment has an investigator, sample batch, planned run date, protocol, raw data, analysis, and conclusion. A reasonable model is one heading per experiment, properties for investigator and batch, `SCHEDULED` for the planned run, child headings for protocol/analysis/conclusion, links for raw data, and an ID for citation from the manuscript. A tag such as `:microscopy:` groups experiments by method. This model remains legible without Emacs and lets Agenda find scheduled runs without scanning raw datasets. ### Chapter review - Structure should communicate meaning before automation reads it. - Choose the lightest primitive that preserves the needed identity and lifecycle. - Make inherited behavior selective and visible in documentation. - Separate current state from historical evidence. ### Exercises - **Basic:** Classify ten items from your current system as headings, list items, properties, tags, links, or files. - **Practical:** Remodel one overloaded heading whose title currently encodes owner, status, date, and category. - **Advanced:** Write a one-page schema for a research or operations file, including identity and archive policy. ## 28. Deep practice: Agenda as a query engine Agenda design becomes easier when treated as query design. Every view has four parts: a source set, a selector, presentation rules, and actions that write back to source. ### Source set `org-agenda-files` may contain files or directories. Directory entries are convenient, but they can silently bring unrelated `.org` files into scope. Explicit file lists make operational boundaries auditable. Generate the list programmatically only if the rule is simple and stable: ```elisp (setq org-agenda-files (directory-files-recursively org-directory "\\.org\\'")) ``` This example is intentionally *not* the default recommendation: it may include archives, exported examples, vendor data, or thousands of notes. A curated list is usually clearer. ### Selectors The calendar agenda selects active timestamps, schedules, and deadlines in a date span. A global TODO view selects unfinished keywords. A tags/property match uses metadata expressions. A search view finds text. A stuck-project view applies a project heuristic. These views answer different questions; forcing all of them into one dashboard makes the dashboard hard to read. The daily Agenda is time-oriented. A NEXT list is action-oriented. A WAITING list is review-oriented. Keep these distinctions visible: ```elisp (setq org-agenda-custom-commands '(("w" "Weekly review" ((agenda "" ((org-agenda-span 7) (org-agenda-start-on-weekday 1))) (todo "NEXT") (todo "WAITING") (tags-todo "+project-DEADLINE={.+}"))) ("r" "Research" ((tags-todo "+research+TODO=\"NEXT\"") (tags "+research+TYPE=\"paper\"")))))) ``` The exact final selector should be tested interactively before embedding it. Agenda match syntax is expressive, and quoting inside Lisp adds a second syntax layer. Build the query in the dispatcher, confirm its results, then copy it into configuration. ### Presentation Categories normally derive from file names or `CATEGORY` properties. Prefix formats can show category, effort, or time. Sorting can prioritize time, deadline, priority, TODO order, category, or user-defined functions. Filters temporarily narrow by tag, category, effort, or regular expression. Presentation should support a decision. Showing OWNER is useful in a delegation review; showing every tag wastes horizontal space on a personal daily list. If a dashboard needs color, icons, and elaborate grouping to reveal its meaning, the source model or selector may be too broad. ### Acting from the view Agenda is not a read-only report. Scheduling, changing TODO state, setting tags, clocking, and refiling from the Agenda act on the originating entry. `org-agenda-goto` visits the source; `org-agenda-switch-to` displays it. Refresh after external edits. Bulk operations are powerful and deserve caution. Mark several entries only after checking their source context. A bulk state transition may trigger logging prompts or repeaters. Commit or back up before experimenting on valuable files. ### A weekly review, step by step 1. Open the seven-day calendar and inspect overdue deadlines. 2. Visit each overdue item; renegotiate, complete, cancel, or reschedule it. Do not merely move every date forward. 3. Review WAITING tasks and their last log entry. Follow up or remove stale waits. 4. Review project headings lacking a NEXT child. Decide the next physical action. 5. Inspect the inbox and refile every remaining item. 6. Review habits only for behavior that still matters. 7. Archive completed projects after preserving conclusions and links. The review is a reasoning process. The custom command reduces navigation; it cannot make the decisions. ### Debugging an absent item Start at the source. Is the buffer saved? Is the file in `org-agenda-files`? Is the timestamp active (`<...>`) rather than inactive (`[...]`)? Is the TODO keyword recognized by the file's current keyword sequence? Is the item excluded by a skip function, restriction lock, narrowing, or filter? Refresh with `r`. If a custom view hides it, test a built-in global TODO or search view. ### Scaling deliberately Agenda parsing cost grows with content, not merely file count. A single enormous archive can be worse than many small active files. Remove archives and reference libraries from scope. Avoid hooks that perform network calls or expensive parsing whenever Org opens a file. Benchmark a built-in view under `emacs -Q` with a minimal configuration, then add customization. ### Exercises - **Basic:** Explain the source, selector, presentation, and write-back behavior of the weekly Agenda. - **Practical:** Build separate “today,” “waiting,” and “research” views instead of one universal dashboard. - **Advanced:** Measure a view with and without archives, then record the evidence and chosen boundary. ## 29. Deep practice: Capture and Refile as information architecture Capture templates should minimize decisions at interruption time without discarding context needed later. Refile targets should reflect destinations a reviewer can understand. ### Template anatomy in detail ```elisp ("m" "Meeting" entry (file+headline "~/org/inbox.org" "Meetings") "* MEETING %^{Title} %^g\n%U\n:PROPERTIES:\n:PEOPLE: %^{People}\n:END:\n\n%?\n\n** Decisions\n\n** Actions\n" :empty-lines 1) ``` `"m"` is the selection key. `"Meeting"` is the menu description. `entry` means the captured object is an Org heading. `file+headline` chooses an existing named heading inside a file. `%^{Title}` and `%^{People}` prompt the user. `%^g` asks for tags using completion. `%U` records capture time. `%?` positions point. `:empty-lines 1` maintains separation around the new entry. Targets have different failure modes. `file` is robust but produces a flat stream. `file+headline` fails if the heading is renamed. `file+olp` expresses a path. `file+olp+datetree` is ideal for chronology. Function targets can compute destinations but become code requiring tests. ### Capturing reading notes ```elisp ("r" "Reading note" entry (file "~/org/inbox.org") "* READ %^{Title} :reading:\n:PROPERTIES:\n:AUTHOR: %^{Author}\n:URL: %^{URL}\n:CREATED: %U\n:END:\n\n%?\n\n** Claims\n\n** Questions\n") ``` This template captures provenance before interpretation. It does not pretend a URL is a citation record; scholarly work should later attach a BibTeX key. “Claims” and “Questions” prompt active reading. After review, refile the note under a research map or convert its conclusion into a durable note. ### Bookmarks and observations A bookmark template should preserve title, link, capture time, and why it matters. Without the last field, a bookmark collection becomes an unsearchable replacement for browser history. Quick observations can be almost structure-free; requiring five properties defeats quick capture. ### Refile target design Broad targets feel flexible but produce huge completion lists. Restrict destinations to stable organizing headings. For example, let `projects.org` accept levels 1–3 and `notes.org` accept top-level maps: ```elisp (setq org-refile-targets '(("~/org/projects.org" :maxlevel . 3) ("~/org/notes.org" :level . 1))) ``` This explicit form is portable only if paths are valid on each machine. Build paths from `org-directory` when synchronizing configuration across operating systems. Refile verifies structure, not semantics. Moving a TODO beneath a DONE project may hide it from a custom selector; moving a note under a tagged parent may change inherited tags. After refile, inspect the target and refresh Agenda. ### Review cadence and failure recovery An inbox review can be daily for tasks and weekly for reference notes. Separate inboxes are justified when their urgency differs. If captures fail during an interruption, preserve the text first in a plain scratch file; debug later. If a template is fragile, simplify its target before adding more Lisp. ### Exercises - **Basic:** Annotate each component of one existing capture template. - **Practical:** Build one meeting and one reading template with different review destinations. - **Advanced:** Test renaming every target heading and document which templates break. ## 30. Deep practice: tables, formulas, clocks, and operational reports Org tables reward small, transparent models. Formula debugging becomes manageable when each derived column has one meaning. ### References and formulas Suppose a consulting report tracks quantity, rate, and tax: ```org #+name: invoice-lines | Description | Hours | Rate | Subtotal | Tax | Total | |-------------------+-------+------+----------+-----+-------| | Architecture | 3.5 | 120 | | .1 | | | Deployment review | 2 | 120 | | .1 | | |-------------------+-------+------+----------+-----+-------| | Total | | | | | | #+TBLFM: $4=$2*$3;%.2f::$6=$4*(1+$5);%.2f::@>$6=vsum(@2$6..@-1$6);%.2f ``` `$4` and `$6` compute per-row values. `@>$6` refers to the last-row total cell. `@-1` means the row above the current last row in this context. Formatting directives retain two decimal places. Recalculate and manually verify a sample: a syntactically valid formula can still encode the wrong business rule. Remote references and named tables can build dashboards, but hidden dependencies make documents harder to move. Keep the source table near its consumer or document every dependency. For financial, regulated, or high-volume work, use a tested spreadsheet/database and import a summary. ### Clock data as an event log Each CLOCK line is an event interval. Reports aggregate those intervals by outline structure. If a task moves between projects, its historical clocks move with it; decide whether that matches reporting needs. If client billing needs immutable assignment, store a CLIENT property at the task and preserve snapshots in released reports. Effort is an estimate, not a budget enforcement mechanism. Compare `EFFORT` with `CLOCKSUM` to calibrate future planning. Do not retroactively edit estimates to make performance look accurate. ### Incident report example ```org * DONE Restore image service :PROPERTIES: :SERVICE: images :SEVERITY: SEV2 :EFFORT: 2:00 :END: :LOGBOOK: CLOCK: [2026-09-01 Tue 14:07]--[2026-09-01 Tue 15:42] => 1:35 :END: ** Timeline - [2026-09-01 Tue 14:07] Alert received. - [2026-09-01 Tue 14:18] Disk saturation confirmed. - [2026-09-01 Tue 15:20] Queue drained. ** Root cause ... ** Follow-up *** TODO Add saturation test DEADLINE: <2026-09-08 Tue> ``` Inactive timestamps preserve history without adding every incident event to Agenda. The follow-up is a real TODO with deadline and therefore does appear. ### Habit interpretation The consistency graph visualizes scheduled history, not motivation or health. Use repeater semantics that reflect the behavior: “every calendar Monday” differs from “one week after completion.” Archive a habit when measurement no longer changes behavior. Preserve relevant conclusions rather than an eternal graph. ### Exercises - **Basic:** Explain the difference among cell, row, column, and range references. - **Practical:** Build an invoice or study-hours table and validate one row manually. - **Advanced:** Create a clock report whose grouping remains correct after tasks are refiled. ## 31. Deep practice: Babel projects and security reviews A credible executable document specifies inputs, environment, computation, outputs, and interpretation. Leaving any one implicit weakens reproduction. ### A complete small analysis ```org #+TITLE: Queue Latency Analysis #+PROPERTY: header-args:python :session none :results replace * Environment Python 3.13; pandas 2.3; matplotlib 3.10. Raw input checksum recorded below. #+name: checksum #+begin_src shell :results output verbatim :exports both sha256sum data/latency.csv #+end_src * Summary #+name: latency-summary #+begin_src python :results value table :exports both import csv with open("data/latency.csv", newline="") as handle: rows = list(csv.DictReader(handle)) values = [float(row["latency_ms"]) for row in rows] return [["count", len(values)], ["mean_ms", round(sum(values) / len(values), 2)], ["max_ms", max(values)]] #+end_src * Figure #+begin_src python :results file graphics :file figures/latency.png :exports results import csv import matplotlib.pyplot as plt with open("data/latency.csv", newline="") as handle: values = [float(row["latency_ms"]) for row in csv.DictReader(handle)] plt.hist(values, bins=20) plt.xlabel("Latency (ms)") plt.ylabel("Requests") plt.savefig("figures/latency.png", dpi=160, bbox_inches="tight") return "figures/latency.png" #+end_src * Interpretation The mean alone hides the observed tail; the histogram shows ... ``` The blocks intentionally read immutable input rather than share a session. The checksum identifies the input. Version declarations identify the environment. Generated figure paths are relative. Interpretation remains human-authored and is not silently regenerated. ### Variables and result types `:results output` captures printed standard output; `:results value` serializes the language's returned value. Confusing them creates blank or oddly formatted results. `:results replace` replaces an earlier result; `append` and `prepend` preserve prior text and can accidentally create misleading history. `:var` can receive literal values, tables, named results, or block references. Make coercion visible. Org tables do not carry rich numeric types; strings, empty cells, and headers need deliberate handling in the target language. ### Sessions and reproducibility Sessions are appropriate for exploratory work requiring an expensive interpreter or interactive database connection. Before publication, restart the session and run blocks in document order. Better, convert the final analysis to isolated blocks whose inputs are explicit. A result that works only because a variable was defined interactively yesterday is not reproducible. ### Noweb and tangling tradeoffs Noweb makes concepts composable: small named blocks can generate a larger program. Overuse scatters executable order across the document. Readers should be able to trace every `<>`. Tangle output should carry a generated-file notice where the language permits it, and contributors must know which Org source owns it. Do not edit tangled output and source independently. Decide one source of truth. In CI, regenerate and fail if the working tree changes; this catches stale generated code. ### Threat model by operation | Operation | Capability | Representative risk | |---|---|---| | Execute shell/Python/JS | User-level process | data deletion or exfiltration | | Execute Emacs Lisp | Full Emacs process access | reading buffers, credentials, filesystem | | Tangle | Write declared files | overwrite executable/configuration files | | Export with Babel | Execute during document build | malicious code in apparently passive document | | Local variables | Alter buffer behavior/evaluate Lisp | code execution on visit/approval | | Link handlers | Invoke programs/custom functions | unsafe external action | Confirmation is one layer, not a sandbox. A trusted file can be compromised through Git, downloaded includes, or modified data. Review diffs before executing. Run automation with least privilege and no production credentials. Network-isolate builds that do not need network access. ### CI pattern A CI build should use a known Emacs image, a lock or exact package revisions, read-only raw inputs, writable output directory, and minimal secrets. Load a build file that enables only required languages. Fail on error and retain logs. Compare produced reports or checksums where determinism is expected. Never solve CI prompts by disabling all confirmation in a general-purpose user profile; scope the policy to the controlled job. ### Exercises - **Basic:** Explain why output and value results differ. - **Practical:** Re-run an analysis from a fresh Emacs and interpreter, then record every missing dependency. - **Advanced:** Threat-model an Org repository from clone through export and propose least-privilege controls. ## 32. Deep practice: export, publishing, and book production Export succeeds reliably when content, structure, and presentation are separated. Org holds semantic content; export settings select representation; CSS or LaTeX controls typography; the build environment supplies external programs. ### Backend-neutral source first Use headings, paragraphs, lists, named figures, citations, and tables wherever possible. Backend-specific fragments are escape hatches. A raw LaTeX block will disappear or degrade in HTML; a raw HTML block will not help PDF. When two outputs matter, test both early. Cross-references should target named elements or stable IDs. Captions describe figures independently of layout. Relative asset paths let a project move. Avoid absolute paths from one workstation in a manuscript intended for CI or collaborators. ### PDF pipeline diagnosis PDF export is a chain: ```text Org parse → LaTeX generation → TeX engine → bibliography processor → PDF ``` First export `.tex` without compiling and inspect it. If Org fails, reduce the source to the smallest failing construct. If TeX fails, read the `.log` near the first actual error, not only the final “fatal” line. Missing fonts, packages, executables, image formats, shell-escape policy, and bibliography tools are external environment problems even when triggered by Org. Choose `pdflatex`, `xelatex`, or `lualatex` based on fonts and publisher requirements. Record the choice in build configuration. High-quality math previews and final PDF may use different pipelines; a good preview does not prove the final build. ### HTML for a readable site Semantic headings produce navigation and accessible document structure. A restrained stylesheet should set readable measure, line height, code overflow, table scrolling, focus states, and responsive images. Do not use HTML in the Org source merely to arrange columns. Test keyboard navigation, heading order, alt/caption content, narrow screens, and dark-mode contrast if supported. For a large web book, exporting one page per chapter may improve loading and URLs. `org-publish` can map a source tree recursively, but navigation among pages needs templates, preamble/postamble, sitemap, or a separate site layer. One long page offers easy search but slower load and less precise analytics. Choose based on audience and maintenance. ### Incremental publishing correctness Incremental timestamps save time but do not know every external dependency. Changing a shared CSS file is handled through the asset project, but changing an included file, macro, or exporter code may require a forced rebuild. Production publishing should have a clean-build option and compare output before deployment. Never publish directly into the only copy of hand-edited files. Treat `public/` as generated output. Deployment credentials should be supplied by the deployment environment, not stored in `org-publish-project-alist` or the source repository. ### Miniature book workflow ```text book/ ├── book.org ├── chapters/ │ ├── 01-model.org │ ├── 02-practice.org │ └── 03-operations.org ├── figures/ ├── data/ ├── references.bib ├── build.el └── output/ ``` 1. `book.org` declares title, author, options, bibliography, and ordered includes. 2. Each chapter owns prose and local footnotes; stable IDs support cross-links. 3. Figures are source-controlled when hand-authored and regenerated when computational. 4. `references.bib` has stable citation keys. 5. `build.el` sets project-relative paths and exports HTML/PDF under a clean profile. 6. CI runs both targets and uploads logs/artifacts. 7. Editorial review reads rendered outputs, not just Org source. 8. A release tag records the complete reproducible state. ### Citation quality Syntax correctness does not guarantee bibliographic quality. Normalize author names, dates, DOI/URL fields, and entry types. Keep citation keys stable after publication. CSL produces cross-format style flexibility; BibLaTeX offers deep LaTeX integration. Collaborator and publisher constraints may decide the processor. ### Exercises - **Basic:** Trace the HTML and PDF pipelines and name their external dependencies. - **Practical:** Build one chapter to both formats and fix every backend warning you understand. - **Advanced:** Create a clean, repeatable book build that detects stale generated figures. ## 33. Deep practice: synchronization, backup, and recovery engineering Availability, history, backup, and confidentiality are separate goals. One tool rarely supplies all four. ### A three-layer design **Working replication** keeps files available on current devices through Syncthing, WebDAV, or a cloud drive. **Version history** records intentional states through Git or filesystem snapshots. **Backup** stores recoverable, preferably encrypted copies on a separate failure domain, including an offsite copy. If ransomware, accidental deletion, or a faulty sync client can immediately propagate to every copy, replication has not provided backup. If the encryption key exists only on the failed laptop, encrypted backup has not provided recovery. ### Git workflow for personal Org Commit after coherent reviews rather than every keystroke. Use descriptive messages such as “Record database migration decision” rather than “update notes.” Pull before editing on a second device; push after completing the session. Inspect `git status` and diffs before commit, particularly because timestamps and drawers can change mechanically. Avoid repositories that combine private notes with public publishing source unless access boundaries are unmistakable. Git history preserves deleted secrets. Removing a credential from the latest file does not remove it from old commits, forks, caches, or remote hosts; rotate the credential first and then perform deliberate history remediation. ### Conflict protocol 1. Stop synchronization on affected devices. 2. Copy every conflicting version to a recovery directory. 3. Identify the common base from Git or backup. 4. Merge structurally: preserve complete subtrees, drawers, and timestamps. 5. Check duplicate IDs and repeated entries. 6. Open the merged file in Org, cycle visibility, run link checks, and refresh Agenda. 7. Commit the resolution, then resume one sync path at a time. Line-based automatic merging may put a property drawer beneath the wrong heading while producing syntactically valid text. Structural review matters. ### Restore testing A backup is a claim until restored. Quarterly, restore to a clean temporary location; verify file counts and checksums; open representative Org files; resolve IDs; display attachments; build one export; and confirm GPG decryption using documented recovery material. Record duration and failures outside the backup set. ### Mobile conflict minimization Mobile apps may reorder metadata, support only subsets of TODO repeaters, or rewrite files. Begin with a copy of two representative files. Disable simultaneous desktop editing. Observe diffs after every mobile action: checkbox toggle, reschedule, property edit, note creation, and attachment. Adopt the app only if its transformations are acceptable and recoverable. ### Exercises - **Basic:** Explain why synchronized copies are not sufficient backup. - **Practical:** Restore your sample Org directory to another location and open it without changing configuration. - **Advanced:** Conduct a tabletop exercise for lost laptop, compromised cloud account, and corrupted sync database. ## 34. Deep practice: troubleshooting by controlled experiments Good debugging changes one variable at a time. Org problems often cross four layers: Org syntax, Emacs configuration, an external package, and an operating-system program. ### Minimal reproduction template Create `/tmp/org-repro.org` or an equivalent safe temporary file: ```org * TODO Minimal task SCHEDULED: <2026-09-02 Wed> #+begin_src python :results output print("test") #+end_src ``` Start `emacs -Q`, open the file, and reproduce. `-Q` omits personal and site initialization, but it still uses bundled Org and depends on external Python if the block is tested. If the failure disappears, load only the smallest relevant settings. If it remains, capture exact command, backtrace, Emacs/Org versions, OS, and source. ### Lisp validation An unbalanced parenthesis usually surfaces while loading configuration. Use `M-x check-parens` in the Lisp buffer. Evaluate one top-level form with `C-M-x` (`eval-defun`) or place point after it and use `C-x C-e`. A variable may be set before its defining package loads; `C-h v` reveals whether it exists and its current value. `M-x locate-library` shows which physical `org.el` or extension Emacs will load. ### Keybinding diagnosis If the documented key does something else, run `C-h k` followed by the key in the exact context. Major and minor mode maps, local maps, terminal translation, and distributions may override it. Invoke the command by `M-x` to separate “command broken” from “binding replaced.” Do not fix a binding conflict by copying a large map from another configuration. ### Export isolation Copy the smallest failing subtree into a fresh file with only required keywords. Disable Babel export temporarily if execution is unrelated. Export to the intermediate format—HTML or `.tex`—and inspect it. Run the external compiler directly to obtain its native error. This division tells you whether Org produced incorrect intermediate output or a downstream tool rejected correct output. ### Performance profiling Use `M-x profiler-start`, choose CPU, reproduce the slow operation once, then `M-x profiler-report` and stop profiling. Interpret inclusive time carefully: a top-level Org command may simply call an expensive user hook. Compare against `emacs -Q` and a smaller source set. Record file sizes, Agenda scope, and package versions so a future change can be measured. ### Asking for help well A useful report contains a one-sentence expected behavior, actual behavior, exact versions, minimal Org text, minimal Lisp, reproduction steps, backtrace, and whether `emacs -Q` changes it. Screenshots rarely replace text errors. When an extension is involved, report to its tracker only after confirming the problem requires that extension. ### Exercises - **Basic:** Use `C-h k`, `C-h f`, and `C-h v` to investigate one Org action. - **Practical:** Intentionally break a capture target and reduce the error to a minimal configuration. - **Advanced:** Profile a slow Agenda view and distinguish parsing cost from package hooks. ## 35. Capstone: build, operate, and review a complete Org system The capstone combines the book's primitives without requiring external packages. ### Day 1: initialize Create the six-file personal tree from Chapter 21. Add only `org-directory`, an explicit Agenda file list, and global bindings for Agenda and Capture. Put the directory in a private Git repository. Make the first commit before adding content. ### Day 2: define structure In `projects.org`, create one heading per current outcome, with a short success criterion. Add child tasks and mark exactly one actionable item NEXT. In `areas.org`, create recurring responsibilities such as finance, health, home, and system maintenance. In `notes.org`, create top-level maps rather than a deep empty taxonomy. ### Day 3: add input and review Install task, note, and journal capture templates. Capture ten realistic items while working. At day's end, clarify and refile them. Record which template fields were unused; remove them immediately. ### Day 4: introduce time honestly Schedule only work intended for a specific day. Add deadlines only where consequences exist. Create one repeater for genuine recurring administration. Open weekly Agenda and confirm every displayed line earns attention. ### Day 5: metadata and identity Add OWNER or AREA properties only where a query needs them. Define a small tag list. Generate IDs for two durable cross-file notes and link them from a project decision. Inspect the raw text to ensure it remains comprehensible. ### Day 6: evidence and computation Create a small table of project estimates. Clock one focused session. Add one non-destructive Babel block that summarizes the table. Keep evaluation confirmation enabled and commit the result separately so the generated change is visible. ### Day 7: publish and recover Export a project report to HTML. Add a local stylesheet outside the Org source. Clone or restore the repository into another directory, configure no special packages, and verify that core files, links, Agenda, and export still work. Record missing attachments or environment assumptions. ### Review questions 1. Can every task be found from its project or Agenda? 2. Does the inbox reach zero through real decisions rather than mass deletion? 3. Are schedules and deadlines semantically distinct? 4. Can a new reader understand properties and tags from context? 5. Does every ID support a real durable link? 6. Can Babel blocks run from a clean process with declared dependencies? 7. Can the system be restored without the original workstation? 8. Which configuration line can be removed? ### Optional second month Choose one extension experiment. For visual comfort, try org-modern and verify no file changes. For many small notes, compare Denote with vanilla naming. For backlink-heavy research, pilot org-roam in a separate copy. For advanced queries, test org-ql on a bounded corpus. Define success and rollback before installation. ### Capstone deliverable The result is not an impressive `init.el`. It is a working directory with trustworthy source files, a short understandable configuration, one computed view, one capture/review loop, one executable report, a published artifact, and a tested restore. That is enough foundation for years of deliberate growth. ## 36. Emacs Lisp literacy for Org users Org configuration becomes safer when you can read the small subset of Lisp it uses. Lisp expressions are lists enclosed in parentheses. The first element is normally a function; remaining elements are arguments. ```elisp (setq org-directory "~/org/") ``` `setq` is a special form that assigns the value on the right to the variable on the left. Strings use quotes. Symbols normally evaluate as variables, so literal data is quoted: ```elisp '(agenda todo tags) ``` The leading quote means “use this list as data; do not call `agenda` as a function.” The equivalent explicit form is `(quote (agenda todo tags))`. Association lists pair keys and values: ```elisp '(("work" . ?w) ("home" . ?h)) ``` `?w` is the character `w`. A dotted pair is a two-part cell; Org uses these throughout configuration. ### Functions and lambdas Define a named function when behavior deserves a stable name and documentation: ```elisp (defun my-org-open-inbox () "Visit the primary Org inbox." (interactive) (find-file (expand-file-name "inbox.org" org-directory))) ``` `interactive` makes the function callable through `M-x`. Without it, Lisp can call the function but users cannot invoke it as a command. The docstring appears in `C-h f`. A lambda is an anonymous function: ```elisp (mapcar (lambda (name) (expand-file-name name org-directory)) '("inbox.org" "projects.org")) ``` `mapcar` calls the lambda for every filename and returns a list. Use a lambda for short local transformations; name a function when it needs tests, reuse, or explanation. ### Hooks and timing A hook runs functions at a defined event: ```elisp (add-hook 'org-mode-hook #'visual-line-mode) ``` Quote the hook symbol because it is data. `#'` marks a function reference. Do not call the function in `add-hook`: `#'visual-line-mode` is correct, while `(visual-line-mode)` would run immediately and pass its result. Package configuration may need to wait until a library loads: ```elisp (with-eval-after-load 'org (setq org-hide-emphasis-markers t)) ``` This avoids forcing Org to load during startup. `use-package` can express similar timing: ```elisp (use-package org :ensure nil :custom (org-hide-emphasis-markers t) :hook (org-mode . visual-line-mode)) ``` `:ensure nil` records that Org is built in and should not be installed by this declaration. `:custom` assigns through the Customize mechanism. `:hook` adds the function to `org-mode-hook`. The plain Lisp form remains important because error messages and manuals use underlying symbols. ### Paths and portability Avoid concatenating path separators by hand. Use `expand-file-name`: ```elisp (defconst my-org-projects-file (expand-file-name "projects.org" org-directory)) ``` This is portable across Windows and Unix-like systems. Environment-specific paths can live in a small machine-local file excluded from public configuration. Never commit credentials as Lisp variables. ### Debugging configuration `check-parens` finds mismatched delimiters. `eval-defun` evaluates the top-level form at point. `pp-eval-expression` prints a readable result. `macroexpand-1` helps explain macros such as `use-package`, although its expansion can be large. `describe-variable` shows current and default values plus customization type; prefer it over copying an online value whose semantics changed. Keep configuration in thematic sections, but avoid functions named “setup everything.” A deep module hides complexity behind a stable interface; a giant initialization function merely hides causality. When an Org command breaks, you should be able to disable one section and retest. ### Exercises - **Basic:** Explain every token in one `setq` and one `add-hook` expression. - **Practical:** Write an interactive command that opens your journal. - **Advanced:** Rewrite a `use-package` declaration as plain Lisp and compare load timing. ## 37. Installation, upgrades, and reproducible package state Emacs contains built-in libraries, installed packages, and libraries found through `load-path`. Org is unusual because a bundled version may coexist with a separately installed version. Loading part of each is a common source of incompatible-function errors. ### Beginner baseline Use the Org bundled with stable Emacs. Confirm: ```text M-x emacs-version M-x org-version M-x locate-library RET org RET ``` The first two identify releases. The last reveals the loaded library path. If behavior differs from the Org 9.8 manual, check whether a distribution or external package shadows bundled Org. ### `package.el` `package.el` is Emacs' built-in package manager. `M-x list-packages` refreshes and displays configured archives. GNU ELPA hosts GNU packages; NonGNU ELPA hosts free packages that are not assigned to GNU. MELPA is a community archive with broad coverage and frequently built snapshots. Repository origin does not guarantee quality—inspect ownership, license, releases, dependencies, and maintenance. Do not call `package-refresh-contents` on every startup. It introduces network delay and failure into opening the editor. Refresh interactively or during a deliberate update. ### `package-vc` `package-vc-install` installs packages from version control. It is useful for packages absent from an archive or for testing a specific revision. Following a moving branch reduces reproducibility. Record the URL and revision; update deliberately; be prepared to revert. ### Upgrading Org separately Upgrade only for a needed fix or feature. Read the official installation page and `ORG-NEWS`. Org's official instructions for Emacs 30 describe isolated batch upgrade approaches designed to prevent the running bundled Org from contaminating installation. Do not evaluate an arbitrary decade-old bootstrap snippet. After upgrade: 1. Restart Emacs completely. 2. Verify `org-version` and `locate-library`. 3. Byte-recompile dependent packages if required. 4. Test Capture, Agenda, Babel, and export in a copy of real data. 5. Keep a rollback path to the bundled version. ### Reproducible configuration A package list alone does not preserve versions. Archive contents change. For a personal setup, record Emacs and Org versions plus important package releases in a lock note or reproducible environment. For CI, pin the container or package revisions. For long-lived Org documents, preserve readable source so data remains accessible even when the customized environment cannot be reconstructed. ### Old advice to retire or qualify - `