Org Beyond the Basics
The earlier chapters treat Org as a closed world: you open a file, edit it, and run commands inside Emacs. Real work rarely stays that tidy. You read web pages in a browser and want to file them as tasks, you keep passwords next to project notes, you check your list on a phone, you paste screenshots, and you run Org inside a terminal or alongside packages that claim the same keys.
This chapter covers the points where Org meets the rest of your environment. It begins with the question that matters most once Org files can run code (what can execute, and how to control it), then moves through encryption, external access, mobile synchronization, files and images, other Emacs packages, and terminal use. The examples were run with Org 9.8.13, in batch Emacs or through a test Emacs server, and the outputs shown are the real ones. Where a step needs a browser or a clipboard, the text says what was run instead.
Code evaluation and trust
An Org file looks like a document, but several of its parts are programs. A source block is code in some language; a table formula is Calc or Emacs Lisp; certain link types run a shell command or a Lisp form when you follow them. Opening a file from someone else is therefore closer to running a script than to reading a text file, and Org asks for confirmation by default for exactly this reason.
The table below lists the places where an Org file can make Emacs do something on your behalf, together with the control that governs each one.
| What runs | When | Control |
|---|---|---|
| Source blocks | C-c C-c on the block, or during export | org-confirm-babel-evaluate, the :eval header argument, org-export-use-babel |
shell: links | when you follow the link | org-link-shell-confirm-function, org-link-shell-skip-confirm-regexp |
elisp: links | when you follow the link | org-link-elisp-confirm-function, org-link-elisp-skip-confirm-regexp |
| Table formulas | on recalculation | none specific: treat formulas as code you have read |
Remote #+SETUPFILE and #+INCLUDE | on export or setup | org-resource-download-policy, org-safe-remote-resources |
Source blocks
org-confirm-babel-evaluate decides whether Org asks before it runs a block. Its default is t, so every evaluation prompts. Setting it to nil removes all prompts, which is convenient but means that any file you open can run arbitrary code the moment you press C-c C-c or export it.
A better middle ground is a function. Org calls it with 2 arguments, the language and the body of the block, and asks for confirmation only when the function returns non-nil. The function runs in the Org buffer, so it can also look at buffer-file-name. The following configuration trusts Emacs Lisp blocks only in files under one directory that you control:
(defvar my-trusted-org-directory (expand-file-name "~/org/"))
(defun my-org-confirm-babel-evaluate (lang _body)
"Ask for confirmation unless an Emacs Lisp block lives in my trusted directory."
(not (and (member lang '("emacs-lisp" "elisp"))
buffer-file-name
(file-in-directory-p buffer-file-name my-trusted-org-directory))))
(setq org-confirm-babel-evaluate #'my-org-confirm-babel-evaluate)
To test it, the same block was placed in trusted/note.org and untrusted/note.org, with the trusted directory pointing at the first. Org evaluated the first block silently and inserted the result:
#+begin_src emacs-lisp
(+ 1 2)
#+end_src
#+RESULTS:
: 3
For the second file it asked Evaluate this emacs-lisp code block on your system? (yes or no) and, since the batch session could not answer, nothing ran.
Org protects this variable against file-local overrides. Its safe-local-variable predicate accepts only t, so a file cannot quietly switch confirmation off for itself through a -*- ... -*- line or a local-variables section.
The picture has 3 further controls:
- The
:evalheader argument sets the policy per block or per subtree.never(orno) forbids evaluation,queryalways asks,never-export(orno-export) allows interactive runs but not export-time runs, andquery-exportasks only during export. Without:eval, Org falls back toorg-confirm-babel-evaluate. Working with Source Code explains header arguments in full. org-babel-no-eval-on-ctrl-c-ctrl-c, when non-nil, removes block evaluation fromC-c C-caltogether. You can still evaluate blocks withC-c C-v e.org-export-use-babel, whennil, stops export from evaluating code and from obeying header arguments. Use it with care, because it also affects how blocks appear in the output.
Links that run code
Org has 2 link types whose target is code: shell: runs a shell command and elisp: evaluates a Lisp form. The description of such a link can say anything, so the visible text tells you nothing about what will run. Both org-link-shell-confirm-function and org-link-elisp-confirm-function default to yes-or-no-p, which makes you type a full yes. You can switch them to y-or-n-p for a lighter prompt, or exempt specific commands through the two skip-confirm regexps. Setting the functions to nil removes the protection completely.
Remote resources
The #+SETUPFILE and #+INCLUDE keywords can point at a URL. org-resource-download-policy controls whether Org downloads such resources: prompt (the default) asks before fetching anything that is not considered safe, safe fetches only safe resources, t fetches everything, and nil fetches nothing. A resource is safe when it matches one of the regexps in org-safe-remote-resources, which is empty by default.
Encrypting entries with Org Crypt
Some notes belong next to the project they describe but must not sit on disk in plain text: an API token, the admin password of a router, the details of a contract. Encrypting the whole file would make it unsearchable and awkward to edit. Org Crypt takes a finer approach: it encrypts the body of individual entries and leaves the headline, tags and properties readable, so the outline, the agenda and searches still work.
Org Crypt relies on EasyPG, the GnuPG interface built into Emacs, so it needs a working GnuPG installation. It selects entries with a tag, crypt by default (org-crypt-tag-matcher holds the match string, so you can use any tag or a more complex match).
Setting it up
The following configuration enables automatic encryption on save:
(require 'org-crypt)
(org-crypt-use-before-save-magic)
(setq org-tags-exclude-from-inheritance '("crypt"))
(setq org-crypt-key "you@example.com")
Each line has a specific purpose:
org-crypt-use-before-save-magicaddsorg-encrypt-entriestobefore-save-hookin every Org buffer. Each save then encrypts every entry that matches the tag.- Excluding
cryptfrom tag inheritance matters because a child of an encrypted entry would otherwise match too, and Org would try to encrypt text that is already part of an encrypted body. If you already setorg-tags-exclude-from-inheritance, add"crypt"to your existing list instead of replacing it. org-crypt-keychooses the recipient. Its 3 kinds of value behave differently, as described below.
The key selection in org-crypt-key-for-heading works like this:
org-crypt-key | Result |
|---|---|
a string such as "you@example.com" | public-key encryption to the matching keys in your keyring |
"" (the default) | matches no key, so Org looks at epa-file-encrypt-to and otherwise falls back to symmetric (passphrase) encryption |
nil | always symmetric encryption, and the CRYPTKEY property is ignored |
A heading can override the key with a CRYPTKEY property, which is useful when one entry is meant for a colleague who has a different key. As the table states, this override works only while org-crypt-key is non-nil.
What the file looks like
Here is a small file before saving:
#+title: Accounts
* Router admin :crypt:
User: admin
Password: correct-horse-battery-staple
* Shopping list
- milk
After a save with the configuration above (using a throwaway GnuPG key), the file on disk and the buffer both contain this:
#+title: Accounts
* Router admin :crypt:
-----BEGIN PGP MESSAGE-----
hF4DQ46f6qdLzD4SAQdAZDnhRV4lni1JE56onURsFrCpjQClXKjmwkU6G2ps0SYw
jQQtVtIZ8U/oCtu23vCxsBMxSCF/p2+aYB4/G+LH5MfeqeRNX1m2ggVsDY00bDF0
0nABjKSPZ5J2FGmm6RKzqcmVipuNBD8c0/yOatfkOd/YAkiNPnnXMAP9vroYagld
MwcR3IXHckuaYn9RvitN1/6Xh0K7dLYgrR18gtdxIEdFEvtQA1oT1DC6ZSDYocC5
2HBjAcLt2TJDVhOPcspUw8vj
=XgAA
-----END PGP MESSAGE-----
* Shopping list
- milk
The headline and its tag remain visible, and the untagged entry is untouched. Running M-x org-decrypt-entry with point on the heading restored the original 2 lines in the buffer.
Daily use
The commands below have no default key:
org-decrypt-entrydecrypts the entry at point. Org Crypt also adds it toorg-fold-reveal-start-hook, so revealing a folded entry withC-c C-rtries to decrypt it.org-decrypt-entriesdecrypts every matching entry in the buffer.org-encrypt-entryandorg-encrypt-entriesdo the reverse by hand. With the save hook installed you rarely need them.
The commentary in org-crypt.el suggests binding decryption to a key of your choice:
(with-eval-after-load 'org
(define-key org-mode-map (kbd "C-c C-/") #'org-decrypt-entry))
Auto-save is the weak point. While an entry is decrypted in the buffer, an auto-save file could write the plain text to disk. org-crypt-disable-auto-save controls what happens when you decrypt: ask (the default) asks whether to turn off auto-save-mode for the buffer, t turns it off without asking, encrypt keeps auto-save but re-encrypts tagged entries before each auto-save, and nil does nothing and accepts the risk.
stateDiagram-v2
[*] --> Plain: tag the entry with crypt
Plain --> Encrypted: save runs before-save-hook
Encrypted --> Plain: org-decrypt-entry or C-c C-r
Plain --> Plain: edit (auto-save per org-crypt-disable-auto-save)
Figure 18.1: A tagged entry is plain text only while you work on it in the buffer; every save returns it to its encrypted form.
Calling Org from outside: org-protocol
Many useful moments happen outside Emacs. You find an article in a browser and want it in your reading list, or you are reading a published page and want to fix a typo in its source. org-protocol lets any program that can open a URL trigger an Org action. It defines a URL scheme, org-protocol://, and a set of handlers that Emacs runs when it receives such a URL.
The mechanism uses the Emacs server. A browser bookmark, a script or a desktop shortcut runs emacsclient with an org-protocol:// URL as its argument. org-protocol advises server-visit-files, the function the server uses to open files sent by emacsclient, so the server inspects each “file name” before it opens anything. When the name starts with org-protocol:/ followed by a known sub-protocol, the matching handler receives the decoded parameters instead.
sequenceDiagram
participant B as Browser bookmark
participant O as OS URL handler
participant C as emacsclient
participant S as Emacs server
participant P as org-protocol
participant K as org-capture
B->>O: org-protocol capture URL
O->>C: URL as a file argument
C->>S: file name list
S->>P: server-visit-files advice checks each name
P->>K: template key, link, title, selected text
K->>S: entry filed, client released
Figure 18.2: An org-protocol URL travels as a file name through emacsclient, and the advice on the server diverts it to a handler before any file is opened.
Setting it up
You need 3 things in place:
-
Load the library and start the server in your Emacs configuration:
(require 'org-protocol) (require 'server) (unless (server-running-p) (server-start)) -
Register
org-protocol://with your operating system so that it callsemacsclientwith the URL. How you do this depends on the desktop environment and the browser, and Org does not do it for you. -
Test from a shell before you involve a browser:
emacsclient "org-protocol://store-link?url=https%3A%2F%2Forgmode.org%2F&title=Org%20Mode"
Parameters use the familiar key=value&key=value form, and values must be URL-encoded. Org decodes + as a space, so the browser function URLSearchParams produces suitable query strings. Older guides build the string with encodeURIComponent, which also works.
store-link: remember a page
The store-link handler adds a link to org-stored-links, the list that org-insert-link offers, and pushes the URL onto the kill ring. Sending
org-protocol://store-link?url=https%3A%2F%2Forgmode.org%2Fmanual%2FProtocols.html&title=Protocols%20(The%20Org%20Manual)
produced the message ‘M-x org-insert-link’ to insert new Org link, ‘C-y’ to insert "https://orgmode.org/manual/Protocols.html" and left these values behind:
stored: ("https://orgmode.org/manual/Protocols.html" "Protocols (The Org Manual)")
kill-ring: "https://orgmode.org/manual/Protocols.html"
In an Org buffer, C-c C-l then offers the stored link with the page title as its description. A bookmark that sends the current page looks like this:
javascript:location.href='org-protocol://store-link?' + new URLSearchParams({url: location.href, title: document.title}); void(0);
capture: file a page as a note
The capture handler starts org-capture with data from the URL. Its parameters are template (a capture template key), url, title and body; if you omit template, Org uses org-protocol-default-template-key. Inside the template, the handler makes these escapes available:
| Escape | Value |
|---|---|
%:link | the URL |
%:description | the page title |
%:annotation | a complete Org link built from the two |
%i | the body parameter, usually the selected text |
Here is a template for web clippings. :immediate-finish files the entry without showing the capture buffer, which suits a one-click bookmark:
(setq org-capture-templates
'(("w" "Web page" entry (file+headline "~/org/inbox.org" "Inbox")
"* %:description\n:PROPERTIES:\n:SOURCE: %:link\n:END:\n%i\n"
:immediate-finish t)))
The URL org-protocol://capture?template=w&url=https%3A%2F%2Forgmode.org%2Fmanual%2FOrg-Crypt.html&title=Org+Crypt&body=Org+Crypt+encrypts+the+text+of+an+entry. turned an inbox containing only * Inbox into this:
* Inbox
** Org Crypt
:PROPERTIES:
:SOURCE: https://orgmode.org/manual/Org-Crypt.html
:END:
Org Crypt encrypts the text of an entry.
The matching bookmark sends the selection as the body:
javascript:location.href='org-protocol://capture?' + new URLSearchParams({template: 'w', url: location.href, title: document.title, body: window.getSelection()}); void(0);
Capture templates themselves are the subject of Capture, Refile, Archive and Attachments.
open-source: from a published page back to its source
If you publish Org files as a website (see Publishing and Citations), the open-source handler takes you from a page in the browser to the Org file that produced it. org-protocol-project-alist describes each site: Org removes :base-url from the URL, replaces :online-suffix with :working-suffix, and prepends :working-directory.
(setq org-protocol-project-alist
'(("Notes site"
:base-url "https://notes.example.com/"
:working-directory "/home/user/site/"
:online-suffix ".html"
:working-suffix ".org")))
With a working directory in the test folder, the URL org-protocol://open-source?url=https%3A%2F%2Fnotes.example.com%2Fworg%2Findex.html resolved to .../site/worg/index.org, which the server then opened like any file sent by emacsclient. When a site rewrites URLs on the server so that the mapping fails, add a :rewrites list of (REGEXP . RELATIVE-PATH) pairs; Org consults it only when no existing file matches. The commands org-protocol-create and org-protocol-create-for-org build an entry interactively, the second from a project in org-publish-project-alist.
Writing your own handler
org-protocol-protocol-alist registers additional sub-protocols. Each entry names the protocol and a function that receives the parameters as a property list. If the function returns nil, the server opens nothing; a string return value is treated as a file name to visit.
(defun my-org-protocol-echo (info)
(message "echo handler got: %S" info)
nil)
(setq org-protocol-protocol-alist
'(("echo" :protocol "echo" :function my-org-protocol-echo)))
org-protocol://echo?a=1&b=two+words printed echo handler got: (:a "1" :b "two words"). A handler can also set :kill-client t, which releases emacsclient at once; the built-in capture handler does this so that a cancelled capture does not leave a waiting client behind.
Org on a phone: Org Mobile
Org Mobile is a protocol for exchanging Org files with another application, typically a phone app, through a shared directory. The computer remains the home of your system: the phone receives copies of your files and agenda views to read offline, records captures and simple edits, and the computer merges these changes on its next synchronization. Org implements the computer side in org-mobile.el; the phone side is a separate application that speaks the same protocol.
flowchart LR
A["Org files in org-directory"] -->|"org-mobile-push: copies, agendas.org, index.org"| S["staging area (org-mobile-directory)"]
S -->|"download changed files"| M["mobile app"]
M -->|"captures and edits in mobileorg.org"| S
S -->|"org-mobile-pull: move entries"| I["org-mobile-inbox-for-pull"]
I -->|"apply edits, tag FLAGGED"| A
Figure 18.3: Org Mobile is a round trip through one staging directory: push publishes copies, pull collects what the phone wrote and merges it.
Configuration
The staging area is a directory that both sides can reach. If you can mount it locally, point org-mobile-directory at the mount; through TRAMP it can also be a remote path such as a WebDAV location.
(setq org-directory "~/org/")
(setq org-mobile-directory "~/orgmobile/")
(setq org-mobile-inbox-for-pull "~/org/from-mobile.org")
org-mobile-files lists what to push. Its default, (org-agenda-files), takes all agenda files; you can add more files or directories. Files are stored with paths relative to org-directory, so they should all live under it. Because the app understands only the TODO keyword sets and the tags that it learns from your global settings, define them in org-todo-keywords, org-tag-alist and org-tag-persistent-alist, even if individual files also use in-buffer settings.
Pushing
M-x org-mobile-push copies the files, writes an agenda file, writes an index, and records checksums so that the app downloads only what changed. For a test directory with one agenda file, the staging area afterwards contained:
agendas.org
checksums.dat
index.org
mobileorg.org
tasks.org
The index carries the global settings the app needs:
#+READONLY
#+TODO: TODO NEXT | DONE
#+TAGS: work home
#+ALLPRIORITIES: A B C
* [[file:agendas.org][Agenda Views]]
* [[file:tasks.org][tasks.org]]
The push also changed the source file. Because org-mobile-force-id-on-agenda-items is t by default, every agenda item received an ID property, which later lets Org find the entry that an edit on the phone refers to:
* TODO Renew passport
SCHEDULED: <2026-11-20 Fri>
:PROPERTIES:
:ID: b65d3eb1-7181-444f-8c1f-0f4724b7e2e5
:END:
Which agenda views go into agendas.org depends on org-mobile-agendas: all (the default) includes the standard and your custom views, default only the weekly agenda and the global TODO list, custom only your own, and a list of strings selects views by their dispatcher keys. The views themselves are covered in Agenda Views.
Pulling
The app writes everything it records into mobileorg.org in the staging area. M-x org-mobile-pull moves those entries into the file named by org-mobile-inbox-for-pull (which should be outside the staging area), empties mobileorg.org, and then applies edits to your files. To simulate a phone capture, one entry was written into mobileorg.org before pulling; afterwards the inbox contained
* Call the dentist about Tuesday
[2026-11-19 Thu 09:12]
and mobileorg.org was empty. Simple changes such as a new TODO state, new tags, or edited headline and body text are applied directly. Entries that need your attention receive the FLAGGED tag, and conflicts are marked with an error message in the inbox. org-mobile-force-mobile-change decides whether the phone’s version wins when both sides changed the same entry.
To work through flagged entries, press ? in the agenda dispatcher. In the resulting view, ? on an item shows the full flagged note and copies it to the kill ring; pressing ? twice removes the FLAGGED tag and the note, which marks the entry as handled.
Encryption
If the staging area is on a server you do not fully trust, set org-mobile-use-encryption to t and put the shared password in org-mobile-encryption-password (or leave it empty, and Org asks once per session). The same password must be entered in the app. Org encrypts the files with AES-256 through the openssl program, so OpenSSL must be installed. File names stay visible on every machine, and the password can briefly appear in the process list while Org runs the encryption command.
Files and images: drag and drop and yank-media
Attaching a screenshot to a note should not require saving it somewhere, typing a path and writing a link. Org handles files dropped on a buffer and, from Emacs 29, the yank-media command, which pastes rich clipboard content such as images.
When you drop a file onto an Org buffer, org-yank-dnd-method decides what happens: attach makes it an attachment of the current entry, file-link inserts a file: link, open visits the file, and ask (the default) lets you choose each time. For attachments, Org first uses the drag metadata (copy or move) and otherwise falls back to org-yank-dnd-default-attach-method; when that is nil, org-attach-method decides.
M-x yank-media covers 3 kinds of clipboard content:
- Images: Org writes the image to disk and inserts a link.
org-yank-image-save-methodchooses where:attach(the default) stores it as an attachment of the current heading, a directory name stores it there, and a function returns the directory to use.org-yank-image-file-name-functionnames the file; the default produces names likeclipboard-20261119T091200.123456, andorg-yank-image-read-filenameasks for a name instead. - Files copied in a file manager, which follow
org-yank-dnd-method. - Tables copied from LibreOffice Calc, which arrive as Org tables.
The clipboard cannot be reached from batch Emacs, so the following results come from calling Org’s image handler directly with a fake PNG and a fixed file name. With org-yank-image-save-method set to "images/", Org wrote images/whiteboard.png and inserted:
* Whiteboard photo
[[file:images/whiteboard.png]]
With the default attach, Org created an ID for the heading, moved the image into the attachment directory data/d6/5b9b7d-da0f-4752-8af8-472f42b91a31/, and inserted an attachment: link:
* Whiteboard photo :ATTACH:
:PROPERTIES:
:ID: d65b9b7d-da0f-4752-8af8-472f42b91a31
:END:
[[attachment:whiteboard.png][whiteboard.png]]
Attachments are explained in Capture, Refile, Archive and Attachments, and how inline images are displayed is part of Markup for Rich Contents.
Living with other packages
Org binds many keys and changes how editing commands behave, so it inevitably meets other packages that want the same keys or the same text. The manual records which packages Org works with and which ones clash with it. The cases below are those you are most likely to meet.
Packages Org builds on
-
Calc performs the arithmetic behind table formulas (see The Spreadsheet and Plotting).
-
constants.el, an external package, lets formulas use named physical constants and unit prefixes. Org uses it when the functionconstants-getis available. -
CDLaTeX, also external, speeds up typing LaTeX fragments (Markup for Rich Contents).
-
Imenu builds a menu of headlines. Enable it with a hook;
org-imenu-depth(default 2) limits the levels included:(add-hook 'org-mode-hook (lambda () (imenu-add-to-menubar "Imenu"))) -
Speedbar can browse into Org files, and
<in the Speedbar frame restricts agenda commands to the selected file or subtree. -
table.eltables, which support cells spanning several rows or columns, are recognized and exported. You cannot edit them directly in the Org buffer:C-c '(org-edit-special) opens one in a separate buffer, andC-c ~(org-table-create-with-table.el) inserts a new one or converts an existing table between the two formats.
Shift-selection, CUA mode and windmove
Emacs uses shifted cursor keys to select text, while Org uses S-<left>, S-<right>, S-<up> and S-<down> to change TODO states, priorities, timestamps and list bullets. org-support-shift-select resolves the conflict in three steps:
| Value | Behavior |
|---|---|
nil (default) | shifted cursor keys run Org commands in special contexts and signal an error elsewhere |
t | outside special contexts they select text; in a list item, bullet cycling works only with point on the bullet |
always | they select text in headlines, property lines, list items and tables as well; use C-c C-t, C-c , and similar commands instead |
CUA mode and windmove also want the shifted cursor keys. If you prefer to give them the keys, set org-replace-disputed-keys to t before Org is loaded. Org then moves its own bindings according to org-disputed-keys:
| Default key | Replacement |
|---|---|
S-<up> | M-p |
S-<down> | M-n |
S-<left> | M-- |
S-<right> | M-+ |
C-S-<left> | M-S-- |
C-S-<right> | M-S-+ |
If you would rather keep Org’s keys and use windmove only where Org has nothing to do, attach windmove to the “final” hooks. Org runs these hooks when a shifted cursor key is pressed outside any special context:
(add-hook 'org-shiftup-final-hook #'windmove-up)
(add-hook 'org-shiftleft-final-hook #'windmove-left)
(add-hook 'org-shiftdown-final-hook #'windmove-down)
(add-hook 'org-shiftright-final-hook #'windmove-right)
Other known conflicts
- YASnippet: Org binds
TABas[tab]rather than"\t", which takes precedence over YASnippet’s trigger. The manual gives 2 workarounds: setting YASnippet’s trigger key to[tab]locally in Org buffers, or adding a non-intrusive expansion function toorg-tab-first-hook. Both depend on YASnippet internals, so check them against the version you use; they were not evaluated for this book. - Viper uses
C-c /, which hidesorg-sparse-tree. Bind the command to another key, or override the key inviper-vi-global-user-map. filladapt.elinterferes with Org’s own filling of paragraphs and list items; turn it off in Org buffers withturn-off-filladapt-modeonorg-mode-hook.- Ecomplete stops completing addresses in message headers when Orgtbl mode is active. Turn on Orgtbl mode by hand once the headers are written, instead of from a hook (see The Table Editor for Orgtbl mode).
Using Org on a terminal
In a text terminal, many key combinations that Org relies on never reach Emacs: the terminal may send nothing for M-<up> or S-<return>, or send something Emacs cannot tell apart from a plain key. Org therefore defines additional bindings that use only ordinary keys. They are installed when Org is loaded in a session where display-graphic-p returns nil, or whenever org-use-extra-keys is non-nil (set it before Org loads, for instance if you start a graphical Emacs but also use emacsclient -t).
The table below was checked by asking Org 9.8.13 in a non-graphical batch session which command each key runs (C-u TAB, a prefix argument, was read from the manual). Speed keys (single letters at the start of a headline, see Getting Started) are listed where org-speed-commands defines one for the same command.
| Graphical key | Terminal alternative | Speed key | Command |
|---|---|---|---|
S-TAB | C-u TAB | C | org-shifttab (C-u TAB is org-cycle with a prefix argument) |
M-<left> | C-c C-x l, ESC <left> | l | org-metaleft |
M-<right> | C-c C-x r, ESC <right> | r | org-metaright |
M-<up> | C-c C-x u, ESC <up> | U | org-metaup |
M-<down> | ESC <down> | D | org-metadown |
M-S-<left> | C-c C-x L | L | org-shiftmetaleft |
M-S-<right> | C-c C-x R | R | org-shiftmetaright |
M-S-<up> | C-c C-x U | org-shiftmetaup | |
M-S-<down> | C-c C-x D | org-shiftmetadown | |
M-RET | C-c C-x m, ESC RET | org-meta-return | |
M-S-RET | C-c C-x M | org-insert-todo-heading | |
S-<left> | C-c <left> | org-shiftleft | |
S-<right> | C-c <right> | org-shiftright | |
S-<up> | C-c <up> | org-shiftup | |
S-<down> | C-c <down> | org-shiftdown | |
C-S-<left> | C-c C-x <left> | org-shiftcontrolleft | |
C-S-<right> | C-c C-x <right> | org-shiftcontrolright | |
C-c C-, | C-c C-x s | org-insert-structure-template |
In 2 rows, this table differs from the one in the manual. The manual lists C-c C-x d for M-<down> and C-c C-x c for S-RET, but org-keys.el later binds these keys again: C-c C-x d runs org-insert-drawer and C-c C-x c runs org-clone-subtree-with-time-shift, and the later bindings win. On a terminal, use ESC <down> for M-<down>. S-RET (org-table-copy-down) has no working alternative, so bind one yourself if you copy table cells down often. The manual also lists the speed keys U and D against M-S-<up> and M-S-<down>, but org-speed-commands maps them to org-metaup and org-metadown, which is how the table above shows them.
The ESC alternatives are explicit bindings in org-keys.el (for example, ESC <left> runs org-metaleft and ESC RET runs org-meta-return), so they do not depend on the terminal sending Meta combinations. Some contexts also offer a prompt-based alternative: on a timestamp, C-c . lets you type a new date instead of nudging it with shifted cursor keys.
Repeating navigation commands
The Emacs minor mode repeat-mode lets you repeat a command by pressing only its last key. Org defines repeat maps for its motion commands, so with repeat-mode on, C-c C-n n n p u moves down 3 visible headings, back up 1, and then to the parent. Any key outside the map ends the repetition and runs normally.
(repeat-mode 1)
| Repeat map | Command | Key | Repeat key |
|---|---|---|---|
org-navigation-repeat-map | org-next-visible-heading | C-c C-n | n |
org-previous-visible-heading | C-c C-p | p | |
org-forward-heading-same-level | C-c C-f | f | |
org-backward-heading-same-level | C-c C-b | b | |
org-up-heading | C-c C-u | u | |
org-block-navigation-repeat-map | org-next-block | C-c M-f | f |
org-previous-block | C-c M-b | b | |
org-link-navigation-repeat-map | org-next-link | C-c C-x C-n | n |
org-previous-link | C-c C-x C-p | p |
Choosing what to adopt
None of these integrations is required, and each one adds a dependency: Org Crypt needs GnuPG and careful handling of auto-save, org-protocol needs a running server and an OS-level URL handler, and Org Mobile needs a shared directory and a compatible app. A reasonable order is to settle your evaluation policy first, because it protects you from the moment you open someone else’s file, then add org-protocol capture if much of your input comes from a browser, and only then consider encryption and mobile access for the specific notes that need them. Putting It Together shows how capture from the browser fits into a complete task system.
Further reading
- Code Evaluation Security
- Interaction, with Cooperation and Conflicts
- TTY Keys
- Protocols: The store-link protocol, The capture protocol, The open-source protocol
- Org Crypt
- Org Mobile: Setting up the staging area, Pushing to the mobile application, Pulling from the mobile application
- Drag and Drop & yank-media
- Repeating commands
- Source: lisp/org-crypt.el, lisp/org-protocol.el, lisp/org-mobile.el, lisp/org-keys.el