Org has in-buffer completions. Unlike minibuffer completions, which are useful for quick command interactions, Org's in-buffer completions are more suitable for content creation in Org documents. Type one or more letters and invoke the hot key to complete the text in-place. Depending on the context and the keys, Org offers different types of completions. No minibuffer is involved. Such mode-specific hot keys have become an integral part of Emacs and Org provides several shortcuts.

M-TAB

Complete word at point.

• At the beginning of an empty headline, complete TODO keywords.
• After \, complete TeX symbols supported by the exporter.
• After : in a headline, complete tags. Org deduces the list of tags from the TAGS in-buffer option (see Setting Tags), the variable org-tag-alist, or from all tags used in the current buffer.
• After : and not in a headline, complete property keys. The list of keys is constructed dynamically from all keys used in the current buffer.
• After [[, complete link abbreviations (see Link Abbreviations).
• After [[*, complete headlines in the current buffer so that they can be used in search links like: [[*find this headline]]
• After #+, complete the special keywords like TYP_TODO or file-specific OPTIONS. After option keyword is complete, pressing M-TAB again inserts example settings for this keyword.
• After STARTUP keyword, complete startup items.
• When point is anywhere else, complete dictionary words using Ispell.

With just a few keystrokes, it is possible to insert empty structural blocks, such as #+BEGIN_SRC … #+END_SRC, or to wrap existing text in such a block.

C-c C-\, (org-insert-structure-template)

Prompt for a type of block structure, and insert the block at point. If the region is active, it is wrapped in the block. First prompts the user for keys, which are used to look up a structure type from the variable below. If the key is TAB, RET, or SPC, the user is prompted to enter a block type.

Available structure types are defined in org-structure-template-alist, see the docstring for adding or changing values.

Org Tempo expands snippets to structures defined in org-structure-template-alist and org-tempo-keywords-alist. For example, < s TAB creates a code block. Enable it by customizing org-modules or add (require 'org-tempo) to your Emacs init file(note: For more information, please refer to the commentary section in org-tempo.el.).

Single keystrokes can execute custom commands in an Org file when point is on a headline. Without the extra burden of a meta or modifier key, Speed Keys can speed navigation or execute custom commands. Besides faster navigation, Speed Keys may come in handy on small mobile devices that do not have full keyboards. Speed Keys may also work on TTY devices known for their problems when entering Emacs key chords.

By default, Org has Speed Keys disabled. To activate Speed Keys, set the variable org-use-speed-commands to a non-nil value. To trigger a Speed Key, point must be at the beginning of an Org headline, before any of the stars.

Org comes with a pre-defined list of Speed Keys. To add or modify Speed Keys, customize the option org-speed-commands. For more details, see the variable's docstring. With Speed Keys activated, M-x org-speed-command-help, or ? when point is at the beginning of an Org headline, shows currently active Speed Keys, including the user-defined ones.

Org's outline, with its stars and lack of indents, can look cluttered in short documents. For book-like long documents, the effect is not as noticeable. Org provides an alternate stars and indentation scheme, as shown on the right in the following table. It displays only one star and indents text to line up with the heading:

* Top level headline             |    * Top level headline
** Second level                  |      * Second level
*** Third level                  |        * Third level
some text                        |          some text
*** Third level                  |        * Third level
more text                        |          more text
* Another top level headline     |    * Another top level headline

Org can achieve this in two ways, (1) by just displaying the buffer in this way without changing it, or (2) by actually indenting every line in the desired amount with hard spaces and hiding leading stars.

#+STARTUP: indent
#+STARTUP: noindent

(setq org-adapt-indentation t
      org-hide-leading-stars t
      org-odd-levels-only t)

#+STARTUP: hidestars
#+STARTUP: showstars

#+STARTUP: odd
#+STARTUP: oddeven

When in an Org buffer and the region is active, some commands will apply to all the subtrees in the active region. For example, hitting C-c C-s when multiple headlines are within the active region will successively prompt you for a new schedule date and time. To disable this, set the option org-loop-over-headlines-in-active-region to non-t, activate the region and run the command normally.

org-agenda-loop-over-headlines-in-active-region is the equivalent option of the agenda buffer, where you can also use bulk editing of selected entries.

Not all commands can loop in the active region and what subtrees or headlines are considered can be refined: see the docstrings of these options for more details.

The Org Num minor mode, toggled with M-x org-num-mode, displays outline numbering on top of headlines. It also updates it automatically upon changes to the structure of the document.

By default, all headlines are numbered. You can limit numbering to specific headlines according to their level, tags, COMMENT keyword, or UNNUMBERED property. Set org-num-max-level, org-num-skip-tags, org-num-skip-commented, org-num-skip-unnumbered, or org-num-skip-footnotes accordingly.

If org-num-skip-footnotes is non-nil, footnotes sections (see Creating Footnotes) are not numbered either.

You can control how the numbering is displayed by setting org-num-face and org-num-format-function.

You can also turn this mode globally for all Org files by setting the option org-startup-numerated to t, or locally on a file by using #+startup: num.

The C-c C-c key in Org serves many purposes depending on the context. It is probably the most over-worked, multipurpose key combination in Org. Its uses are well documented throughout this manual, but here is a consolidated list for easy reference.

• If column view (see Column View) is on, exit column view.
• If any highlights shown in the buffer from the creation of a sparse tree, or from clock display, remove such highlights.
• If point is in one of the special KEYWORD lines, scan the buffer for these lines and update the information. Also reset the Org file cache used to temporarily store the contents of URLs used as values for keywords like SETUPFILE.
• If point is inside a table, realign the table.
• If point is on a TBLFM keyword, re-apply the formulas to the entire table.
• If the current buffer is a capture buffer, close the note and file it. With a prefix argument, also jump to the target location after saving the note.

• If point is on a <>, update radio targets and corresponding links in this buffer.
• If point is on a property line or at the start or end of a property drawer, offer property commands.
• If point is at a footnote reference, go to the corresponding definition, and vice versa.
• If point is on a statistics cookie, update it.
• If point is in a plain list item with a checkbox, toggle the status of the checkbox.
• If point is on a numbered item in a plain list, renumber the ordered list.
• If point is on the #+BEGIN line of a dynamic block, the block is updated.
• If point is at a timestamp, fix the day name in the timestamp.

In-buffer settings start with #+, followed by a keyword, a colon, one or more spaces, and then a word for each setting. Org accepts multiple settings on the same line. Org also accepts multiple lines for a keyword. This manual describes these settings throughout. A summary follows here.

C-c C-c activates any changes to the in-buffer settings. Closing and reopening the Org file in Emacs also activates the changes.

#+ARCHIVE: %s_done::

Sets the archive location of the agenda file. The corresponding variable is org-archive-location.

#+CATEGORY

Sets the category of the agenda file, which applies to the entire document.

#+COLUMNS: %25ITEM ...

Set the default format for columns view. This format applies when columns view is invoked in locations where no COLUMNS property applies.

#+CONSTANTS: name1=value1 ...

Set file-local values for constants that table formulas can use. This line sets the local variable org-table-formula-constants-local. The global version of this variable is org-table-formula-constants.

#+FILETAGS: :tag1:tag2:tag3:

Set tags that all entries in the file inherit from, including the top-level entries.

#+LINK: linkword replace

Each line specifies one abbreviation for one link. Use multiple LINK keywords for more, see Link Abbreviations. The corresponding variable is org-link-abbrev-alist.

#+PRIORITIES: highest lowest default

This line sets the limits and the default for the priorities. All three must be either letters A–Z or numbers 0–64. The highest priority must have a lower ASCII number than the lowest priority.

#+PROPERTY: Property_Name Value

This line sets a default inheritance value for entries in the current buffer, most useful for specifying the allowed values of a property.

#+SETUPFILE: file

The setup file or a URL pointing to such file is for additional in-buffer settings. Org loads this file and parses it for any settings in it when Org opens the main file. If URL is specified, the contents are downloaded and stored in a temporary file cache. C-c C-c on the settings line re-parses and re-loads the file, and also resets the temporary file cache.

Org also parses and loads in-buffer settings from the setup file during normal exporting process. Org parses the in-buffer settings as if it was included in the containing Org buffer. The rest of the contents of setup file is ignored.

To visit the setup file—not a URL—use C-c ' while point is on the line with the setup file name.

#+STARTUP:

Startup options Org uses when first visiting a file.

The first set of options deals with the initial visibility of the outline tree. The corresponding variable for global default settings is org-startup-folded with a default value of showeverything.

Dynamic virtual indentation is controlled by the variable org-startup-indented~(note: Note that Org Indent mode also sets the ~wrap-prefix property, such that Visual Line mode (or purely setting word-wrap) wraps long lines, including headlines, correctly indented.).

Dynamic virtual numeration of headlines is controlled by the variable org-startup-numerated.

Aligns tables consistently upon visiting a file. The corresponding variable is org-startup-align-all-tables with nil as default value.

Shrink table columns with a width cookie. The corresponding variable is org-startup-shrink-all-tables with nil as default value.

When visiting a file, inline images can be automatically displayed. The corresponding variable is org-startup-with-inline-images, with a default value nil to avoid delays when visiting a file.

Bracket links in Org buffers are displayed hiding the link path and brackets. For example, [[https://orgmode.org][Org Website]] is, by default, displayed as "Org Website", hiding the link itself and just displaying its description. Alternatively, the links can be displayed in full. The corresponding variable is org-link-descriptive.

Logging the closing and reopening of TODO items and clock intervals can be configured using these options (see variables org-log-done, org-log-note-clock-out, and org-log-repeat).

Here are the options for hiding leading stars in outline headings, and for indenting outlines. The corresponding variables are org-hide-leading-stars and org-odd-levels-only, both with a default setting nil (meaning showstars and oddeven).

To turn on custom format overlays over timestamps (variables org-display-custom-times and org-timestamp-custom-formats), use:

The following options influence the table spreadsheet (variable constants-unit-system).

To influence footnote settings, use the following keywords. The corresponding variables are org-footnote-define-inline, org-footnote-auto-label, and org-footnote-auto-adjust.

To hide blocks or drawers on startup, use these keywords. The corresponding variables are org-hide-block-startup and org-hide-drawer-startup.

The display of entities as UTF-8 characters is governed by the variable org-pretty-entities and the keywords

#+TAGS: TAG1(c1) TAG2(c2)

These lines (several such lines are allowed) specify the valid tags in this file, and (potentially) the corresponding fast tag selection keys. The corresponding variable is org-tag-alist.

#+TODO:, #+SEQ_TODO:, #+TYP_TODO:

These lines set the TODO keywords and their interpretation in the current file. The corresponding variable is org-todo-keywords.

Org, as an Emacs mode, makes use of Elisp regular expressions for searching, matching and filtering. Elisp regular expressions have a somewhat different syntax then some common standards. Most notably, alternation is indicated using \| and matching groups are denoted by \(...\). For example the string home\|work matches either home or work.

For more information, see Regular Expressions in Emacs.

A reference document providing a formal description of Org's syntax is available as a draft on Worg, initially written by Nicolas Goaziou. It defines Org's core internal concepts such as "headlines", "sections", "affiliated keywords", "(greater) elements" and "objects". Each part of an Org document belongs to one of the previous categories.

To explore the abstract structure of an Org buffer, run this in a buffer:

M-: (org-element-parse-buffer) <RET>

It outputs a list containing the buffer's content represented as an abstract structure. The export engine relies on the information stored in this list. Most interactive commands—e.g., for structure editing—also rely on the syntactic meaning of the surrounding context.

You can probe the syntax of your documents with the command

M-x org-lint <RET>

It runs a number of checks to find common mistakes. It then displays their location in a dedicated buffer, along with a description and a "trust level", since false-positive are possible. From there, you can operate on the reports with the following keys:

C-c C-x I in an Org file tries to open a suitable section of the Org manual depending on the syntax at point. For example, using it on a headline displays "Document Structure" section.

q closes the Info window.

You may sometimes want to write text that looks like Org syntax, but should really read as plain text. Org may use a specific escape character in some situations, i.e., a backslash in macros (see Macro Replacement) and links (see Link Format), or a comma in source and example blocks (see Literal Examples). In the general case, however, we suggest using the zero width space. You can insert one with any of the following:

C-x 8 <RET> zero width space <RET>
C-x 8 <RET> 200B <RET>

For example, in order to write [[#1_002c2][1,2]] as-is in your document, you may write instead

[X[1,2]]

where X denotes the zero width space character.

Unlike plain text, running code comes with risk. Each source code block, in terms of risk, is equivalent to an executable file. Org therefore puts a few confirmation prompts by default. This is to alert the casual user from accidentally running untrusted code.

For users who do not run code blocks or write code regularly, Org's default settings should suffice. However, some users may want to tweak the prompts for fewer interruptions. To weigh the risks of automatic execution of code blocks, here are some details about code evaluation.

Org evaluates code in the following circumstances:

Source code blocks

Org evaluates source code blocks in an Org file during export. Org also evaluates a source code block with the C-c C-c key chord. Users exporting or running code blocks must load files only from trusted sources. Be wary of customizing variables that remove or alter default security measures.

When t, Org prompts the user for confirmation before executing each code block. When nil, Org executes code blocks without prompting the user for confirmation. When this option is set to a custom function, Org invokes the function with these two arguments: the source code language and the body of the code block. The custom function must return either a t or nil, which determines if the user is prompted. Each source code language can be handled separately through this function argument.

For example, here is how to execute ditaa code blocks without prompting:

(defun my-org-confirm-babel-evaluate (lang body)
  (not (string= lang "ditaa")))  ;don't ask for ditaa
(setq org-confirm-babel-evaluate #'my-org-confirm-babel-evaluate)

Following shell and elisp links

Org has two link types that can directly evaluate code (see External Links). Because such code is not visible, these links have a potential risk. Org therefore prompts the user when it encounters such links. The customization variables are:

Function that prompts the user before executing a shell link.

Function that prompts the user before executing an Emacs Lisp link.

Formulas in tables

Formulas in tables (see The Spreadsheet) are code that is evaluated either by the Calc interpreter, or by the Emacs Lisp interpreter.

Org's compatibility and the level of interaction with other Emacs packages are documented here.

(add-hook 'org-mode-hook
          (lambda () (imenu-add-to-menubar "Imenu")))

(add-hook 'org-mode-hook 'turn-off-filladapt-mode)

(define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree)

;; Make windmove work in Org mode:
(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)

(add-hook 'org-mode-hook
          (lambda ()
            (setq-local yas/trigger-key [tab])
            (define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand)))

(defun yas/org-very-safe-expand ()
  (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))

(add-hook 'org-mode-hook
          (lambda ()
            (make-variable-buffer-local 'yas/trigger-key)
            (setq yas/trigger-key [tab])
            (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
            (define-key yas/keymap [tab] 'yas/next-field)))

Org provides alternative key bindings for TTY and modern mobile devices that cannot perform movement commands on point and key bindings with modifier keys. Some of these workarounds may be more cumbersome than necessary. Users should look into customizing these further based on their usage needs. For example, the normal S-<cursor> for editing timestamp might be better with C-c . chord.

Org protocol is a tool to trigger custom actions in Emacs from external applications. Any application that supports calling external programs with an URL as argument may be used with this functionality. For example, you can configure bookmarks in your web browser to send a link to the current page to Org and create a note from it using capture (see Capture). You can also create a bookmark that tells Emacs to open the local source file of a remote website you are browsing.

In order to use Org protocol from an application, you need to register org-protocol:// as a valid scheme-handler. External calls are passed to Emacs through the emacsclient command, so you also need to ensure an Emacs server is running. More precisely, when the application calls

emacsclient "org-protocol://PROTOCOL?key1=val1&key2=val2"

Emacs calls the handler associated to PROTOCOL with argument (:key1 val1 :key2 val2).

Org protocol comes with three predefined protocols, detailed in the following sections. Configure org-protocol-protocol-alist to define your own.

emacsclient "org-protocol://store-link?url=URL&title=TITLE"

[[#url][TITLE]]

javascript:location.href='org-protocol://store-link?' +
      new URLSearchParams({url:location.href, title:document.title});void(0);

javascript:location.href='org-protocol://store-link?url='+
      encodeURIComponent(location.href);void(0);

emacsclient "org-protocol://capture?template=X&url=URL&title=TITLE&body=BODY"

javascript:location.href='org-protocol://capture?' +
      new URLSearchParams({
            template: 'x', url: window.location.href,
            title: document.title, body: window.getSelection()});
      void(0);

javascript:location.href='org-protocol://capture?template=x'+
      '&url='+encodeURIComponent(window.location.href)+
      '&title='+encodeURIComponent(document.title)+
      '&body='+encodeURIComponent(window.getSelection());void(0);

%:link          The URL
%:description   The webpage title
%:annotation    Equivalent to [[%:link][%:description]]
%i              The selected text

javascript:location.href='org-protocol://open-source?url='+
      encodeURIComponent(location.href);void(0)

(setq org-protocol-project-alist
      '(("Worg"
         :base-url "https://orgmode.org/worg/"
         :working-directory "/home/user/worg/"
         :online-suffix ".html"
         :working-suffix ".org")))

(setq org-protocol-project-alist
      '(("example.com"
         :base-url "https://example.com/"
         :working-directory "/home/user/example/"
         :online-suffix ".php"
         :working-suffix ".php"
         :rewrites (("example.com/print/" . "products.php")
                    ("example.com/$" . "index.php")))))

Org Crypt encrypts the text of an entry, but not the headline, or properties. Behind the scene, it uses the Emacs EasyPG Library to encrypt and decrypt files, and EasyPG needs a correct GnuPG setup.

Any text below a headline that has a crypt tag is automatically encrypted when the file is saved. To use a different tag, customize the org-crypt-tag-matcher setting.

Here is a suggestion for Org Crypt settings in Emacs init file:

(require 'org-crypt)
(org-crypt-use-before-save-magic)
(setq org-tags-exclude-from-inheritance '("crypt"))

(setq org-crypt-key nil)
;; GPG key to use for encryption.
;; nil means  use symmetric encryption unconditionally.
;; "" means use symmetric encryption unless heading sets CRYPTKEY property.

(setq auto-save-default nil)
;; Auto-saving does not cooperate with org-crypt.el: so you need to
;; turn it off if you plan to use org-crypt.el quite often.  Otherwise,
;; you'll get an (annoying) message each time you start Org.

;; To turn it off only locally, you can insert this:
;;
;; # -*- buffer-auto-save-file-name: nil; -*-

It's possible to use different keys for different headings by specifying the respective key as property CRYPTKEY, e.g.:

* Totally secret :crypt:
  :PROPERTIES:
  :CRYPTKEY: 0x0123456789012345678901234567890123456789
  :END:

Note that the CRYPTKEY property is only effective when org-crypt-key is non-nil. If org-crypt-key is nil, Org uses symmetric encryption unconditionally.

Excluding the crypt tag from inheritance prevents already encrypted text from being encrypted again.

Org Mobile is a protocol for synchronizing Org files between Emacs and other applications, e.g., on mobile devices. It enables offline-views and capture support for an Org mode system that is rooted on a "real" computer. The external application can also record changes to existing entries.

This appendix describes Org's support for agenda view formats compatible with Org Mobile. It also describes synchronizing changes, such as to notes, between the mobile application and the computer.

To change tags and TODO states in the mobile application, first customize the variables org-todo-keywords, org-tag-alist and org-tag-persistent-alist. These should cover all the important tags and TODO keywords, even if Org files use only some of them. Though the mobile application is expected to support in-buffer settings, it is required to understand TODO states sets (see Setting up keywords for individual files) and mutually exclusive tags (see Setting Tags) only for those set in these variables.

(setq org-mobile-directory "~/orgmobile/")

(setq org-mobile-directory "/davs:user@remote.host:/org/webdav/")

Org mode supports drag and drop (DnD) of files. By default, Org asks the user what must be done with the dropped file: attach it, insert file: link, or open the file. Customize org-yank-dnd-method to set the default DnD action.

When DnD method is "attach", Org mode first consults DnD metadata to decide the attach method. For example, when file/files are dragged from a file manager, Org may attach by copying or by moving.

If Org cannot figure out which attachment method to use from the metadata, it defaults to org-yank-dnd-default-attach-method (note: By default, org-yank-dnd-default-attach-method is set to nil – use the same value as org-attach-method (cp by default).)

Starting from Emacs 29, Org mode supports yank-media command to yank images from the clipboard, files from a file manager and tables copied from LibreOffice Calc documents.

When yanking images from clipboard, Org saves the image on disk and inserts the image link to Org buffer. Images can be saved as attachments to heading (default), to a globally defined directory, or to a directory returned by a function call. The save location is controlled by org-yank-image-save-method.

The yanked images are saved under automatically generated name. You can customize org-yank-image-file-name-function to make Org query the image names or change the naming scheme.

When yanking files copied from a file manager, Org respects the value of org-yank-dnd-method. Image files pasted this way also respect the value of org-yank-image-save-method when the action to perform is attach.

Tables copied from LibreOffice Calc documents are yanked as Org tables.

When repeat-mode is turned on, headline motion commands, link and block navigation commands by only pressing a single key. For example, instead of typing C-c C-n repeatedly, you can just type C-c C-n n n n p u ... to move to different headlines. When a key not in the map is pressed, it exits repeat-mode and the command corresponding to the key is executed (see the Emacs user manual for more details).

By default, the following commands are made repeatable in separate keymaps.

org-navigation-repeat-map:

org-block-navigation-repeat-map:

org-link-navigation-repeat-map:

1. 51

   Org Indent mode also sets wrap-prefix correctly for indenting and wrapping long lines of headlines or text. This minor mode also handles Visual Line mode and directly applied settings through word-wrap.

   Backrefs: 1

2. 52

   This works, but requires extra effort. Org Indent mode is more convenient for most applications.

   Backrefs: 1

3. 53

   For a server to host files, consider using a WebDAV server, such as Nextcloud. Additional help is at this FAQ entry.

   Backrefs: 1

4. 54

   While creating the agendas, Org mode forces ID properties on all referenced entries, so that these entries can be uniquely identified if Org Mobile flags them for further action. To avoid setting properties configure the variable org-mobile-force-id-on-agenda-items to nil. Org mode then relies on outline paths, assuming they are unique.

   Backrefs: 1