This manual is for Org version 9.8.
Copyright © 2004–2026 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.”
(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and modify this GNU manual.”
yank-mediaOrg mode is an authoring tool and a TODO list manager for GNU Emacs. It relies on a lightweight plain-text markup language used in files with the ‘.org’ extension.
Authoring Org files is best supported by Emacs, but you can view, understand, and change them with any text editor.
As an authoring tool, Org helps you write structured documents and provides exporting facilities. Org files can also be used for literate programming and reproducible research. As a TODO list manager, Org helps you organize your tasks in a flexible way, from daily needs to detailed project planning, allowing logging, multiple views of your tasks, exporting your agendas, etc.
Org mode is implemented on top of Outline mode, which makes it possible to keep the content of large files well-structured. Visibility cycling and structure editing help you work with the tree. Tables are easily created with a built-in table editor. Plain text URL-like links connect to websites, emails, Usenet messages, BBDB entries, and any files related to the projects.
Org develops organizational tasks around note files that contain lists or information about projects as plain text. Project planning and task management make use of metadata, which is part of an outline node. Based on this data, specific entries can be extracted via queries to create dynamic agenda views that also integrate the Emacs calendar and diary. Org can be used to implement many different project planning schemes, such as David Allen’s GTD system.
Org files can serve as a single-source authoring system with export to many different formats such as HTML, LaTeX, Open Document, and Markdown. New export backends can be derived from existing ones, or defined from scratch.
Org files can include source code blocks, which makes Org uniquely suited for authoring technical documents with code examples. Org source code blocks are fully functional; they can be evaluated in place and their results can be captured in the file. This makes it possible to create a single-file reproducible research compendium.
Org keeps simple things simple. When first fired up, it should feel like a straightforward, easy-to-use outliner. Complexity is not imposed, but a large amount of functionality is available when needed. Org is a toolbox. Many users actually run only a—very personal—fraction of Org’s capabilities, and know that there is more whenever they need it.
All of this is achieved with strictly plain text files, the most portable and future-proof file format. Org runs in Emacs. Emacs is one of the most widely ported programs, so that Org mode is available on every major platform.
There is a website for Org which provides links to the newest version of Org, as well as additional information, frequently asked questions (FAQ), links to tutorials, etc. This page is located at https://orgmode.org.
An earlier version (7.3) of this manual was available as a paperback book from the Network Theory Ltd. publishing company, which closed in 2009.
Org is included in distributions of GNU Emacs, so you probably do not need to install it. Most users will simply activate Org and begin exploring its features.
If, for one reason or another, you want to install Org on top of the pre-packaged version, you can use the Emacs package system or clone Org’s Git repository. We strongly recommend sticking to a single installation method.
When installing Org on top of the pre-packaged version, please note that Org stable versions are meant to be fully compatible with the last three stable versions of Emacs but not with older Emacsen.
Some Org components also depend on third-party packages available through package archives. Org is only guaranteed to be compatible with the latest stable versions of these third-party packages.
Recent Emacs distributions include a packaging system which lets you install Elisp libraries. You can install Org from the “package menu”, with M-x list-packages. See Package Menu.
Important: You need to do this in a session where no ‘.org’ file has been visited, i.e., where no Org built-in functions have been loaded. Otherwise, autoloaded Org functions will mess up the installation.
To avoid interference with the built-in Org mode, you can use the command line (you need Emacs 30 or later):
emacs -Q -batch -eval "(progn (package-refresh-contents) (package-upgrade 'org))"
This approach has the advantage of isolating the upgrade process from a running Emacs session, ensuring that version conflicts cannot arise.
You can clone Org’s repository and install Org like this:
$ cd ~/src/ $ git clone https://https.git.savannah.nongnu.org/git/org-mode.git $ # alternatively, you can use mirror $ # git clone https://git.sr.ht/~bzg/org-mode $ cd org-mode/ $ make autoloads
Note that in this case, ‘make autoloads’ is mandatory: it defines Org’s version in ‘org-version.el’ and Org’s autoloads in ‘org-loaddefs.el’.
Make sure you set the load path correctly in your Emacs init file:
(add-to-list 'load-path "~/src/org-mode/lisp")
You can also compile with ‘make’, generate the documentation with ‘make doc’, create a local configuration with ‘make config’, and install Org with ‘make install’. Please run ‘make help’ to get the list of compilation/installation options.
For more detailed explanations on Org’s build system, please check the Org Build System page on Worg.
Org’s repository used to contain the ‘contrib/’ directory for add-ons contributed by others. As of Org 9.5, the directory has been moved to the dedicated org-contrib repository, which you can install separately as a package from NonGNU ELPA.
There are many valuable packages maintained outside the Org repository. Worg has a list of org-contrib and external packages; it is certainly not exhaustive.
Org mode buffers need Font Lock to be turned on: this is the default in Emacs1.
There are compatibility issues between Org mode and some other Elisp packages (see Packages that conflict with Org mode). Please take the time to check the list.
For a better experience, the three Org commands org-store-link,
org-capture and org-agenda ought to be accessible anywhere in
Emacs, not just in Org buffers. To that effect, you need to bind them
to globally available keys, like the ones reserved for users (see
(elisp)Key Binding Conventions). Here are suggested bindings;
please modify the keys to your own liking in your personal init file.
(global-set-key (kbd "C-c l") #'org-store-link) (global-set-key (kbd "C-c a") #'org-agenda) (global-set-key (kbd "C-c c") #'org-capture)
Files with the ‘.org’ extension use Org mode by default. To turn on Org mode in a file that does not have the extension ‘.org’, make the first line of a file look like this:
MY PROJECTS -*- mode: org; -*-
which selects Org mode for this buffer no matter what the file’s name
is. See also the variable org-insert-mode-line-in-empty-file.
Many commands in Org work on the region if the region is active. To make use of this, you need to have Transient Mark mode turned on, which is the default. If you do not like it, you can create an active region by using the mouse to select a region, or pressing C-SPC twice before moving point.
If you find problems with Org, or if you have questions, remarks, or ideas about it, please send an email to the Org mailing list mailto:emacs-orgmode@gnu.org. You can subscribe to the list from this web page. If you are not a member of the mailing list, your mail will be passed to the list after a moderator approves it2. We ask you to read and respect the GNU Kind Communications Guidelines when sending messages on this mailing list. Please allow up to one month for a response and follow up if no response is received on the bug report.
For bug reports, please first try to reproduce the bug with the latest version of Org available—if you are running an outdated version, it is quite possible that the bug has been fixed already. If the bug persists, prepare a report and provide as much information as possible, including the version information of Emacs (M-x emacs-version) and Org (M-x org-version), as well as the Org-related setup in the Emacs init file. The easiest way to do this is to use the command
M-x org-submit-bug-report <RET>
which puts all this information into an Emacs mail buffer so that you only need to add your description. If you are not sending the email from within Emacs, please copy and paste the content into your email program.
Sometimes you might face a problem due to an error in your Emacs or Org mode setup. Before reporting a bug, it is very helpful to start Emacs with minimal customizations and to reproduce the problem. Doing so often helps you determine if the problem is with your customization or with Org mode itself. You can start a typical minimal session with a command like the example below.
$ emacs -Q -l /path/to/minimal-org.el
However, if you are using Org mode as distributed with Emacs, a minimal setup is not necessary. In that case it is sufficient to start Emacs as ‘emacs -Q’. The ‘minimal-org.el’ setup file can have contents as shown below.
;;; Minimal setup to load latest `org-mode'.
;; Activate debugging.
(setq debug-on-error t
debug-on-signal nil
debug-on-quit nil)
;; Add latest Org mode to load path.
(add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp"))
If you are using the Org mode version from the Git repository, you can start a minimal session using ‘make’.
# Bare Emacs make repro # or pass extra arguments make repro REPRO_ARGS="-l /path/to/minimal/config.el /tmp/bug.org"
If an error occurs, a “backtrace” can be very useful—see below for instructions on how to create one. Often a small example file helps, along with clear information about:
If you experience degraded performance, you can record a “profile” and share it on the Org mailing list. See below for instructions on how to record a useful profile.
Thank you for helping to improve this program.
If working with Org produces an error with a message you do not understand, you may have hit a bug. The best way to report this is by providing, in addition to what was mentioned above, a backtrace. This is information from the built-in debugger about where and how the error occurred. Here is how to produce a useful backtrace:
C-u M-x org-reload <RET>
or, from the menu: Org → Refresh/Reload → Reload Org uncompiled.
M-x toggle-debug-on-error <RET>
or, from the menu: Options → Enter Debugger on Error.
Sometimes, Org becomes slow for no apparent reason. Such slowdown is often caused by interaction between third-party packages and Org mode. However, identifying the root cause is not always straightforward.
Emacs is able to record performance statistics, which can then be used to find out which functions are taking the most time to execute. To record the statistics, one can use a profiler. To use the Emacs profiler, we recommend the following steps:
M-x profiler-stop <RET>
M-x profiler-start <RET> cpu <RET>
M-x profiler-report <RET>
This command will display a summary of the commands and functions
that have been executed between profiler-start and
profiler-report invocations, with the command taking the most
time displayed on top.
The ‘<TAB>’ key can be used to fold and unfold lines in the profiler buffer. The child items revealed upon unfolding are the functions and commands called by the unfolded parent.
The root causes are often buried deep inside child items in
the profiler. You can press ‘B’ (profiler-report-render-reversed-calltree)
to quickly reveal the actual function/command that takes the most
time to run.
Pressing ‘C’ profiler-report-render-calltree will recover the
original view.
To save the data, issue
M-x profiler-report-write-profile <RET> /path/to/profile-file-to-be-saved <RET>
Then, you can attach the saved file to your email to the Org mailing list, along with details about what you did to trigger the slowdown.
Note that the saved statistics will only contain the function names and how long their execution takes. No private data will be recorded.
Org uses various syntactic elements: TODO keywords, tags, property names, keywords, blocks, etc. In this manual we use the following conventions:
TODO keywords are written with all capitals, even if they are user-defined.
Tags are case-sensitive. User-defined tags are usually written in lowercase; built-in tags with special meaning are written as they should appear in the document, usually with all capitals.
User-defined properties are capitalized; built-in properties with special meaning are written with all capitals.
Keywords and blocks are written in uppercase to enhance their readability, but you can use lowercase in your Org files.
The manual lists both the keys and the corresponding commands for
accessing functionality. Org mode often uses the same key for
different functions, depending on context. The command that is bound
to such keys has a generic name, like org-metaright. In the manual,
we will, wherever possible, give the function that is internally
called by the generic command. For example, in the chapter on
document structure, M-RIGHT will be listed to call
org-do-demote, while in the chapter on tables, it will be listed to
call org-table-move-column-right.
Org is an outliner. Outlines allow a document to be organized in
a hierarchical structure, which, at least for me, is the best
representation of notes and thoughts. An overview of this structure
is achieved by folding, i.e., hiding large parts of the document to
show only the general document structure and the parts currently being
worked on. Org greatly simplifies the use of outlines by compressing
the show and hide functionality into a single command, org-cycle,
which is bound to the TAB key.
Headlines define the structure of an outline tree. Org headlines start on the left margin3 with one or more stars followed by a space. For example:
* First (top) level headline
** Second level
*** Third level
some text
*** Third level
more text
* Another first (top) level headline
The name defined in org-footnote-section is reserved. Do not use it
as a title for your own headings.
Some people find the many stars too noisy and would prefer an outline that has whitespace followed by a single star as headline markers. This can be achieved using the Org Indent minor mode. See A Cleaner Outline View for more information.
Headlines are not numbered. However, you may want to dynamically number some, or all, of them. See Dynamic Headline Numbering.
An empty line after the end of a subtree is considered part of it and
is hidden when the subtree is folded. However, if you leave at least
two empty lines, one empty line remains visible after folding the
subtree, in order to structure the collapsed view. See the variable
org-cycle-separator-lines to modify this behavior.
Outlines make it possible to hide parts of the text in the buffer. Org uses just two commands, bound to TAB and S-TAB, to change the visibility in the buffer.
org-cycle) ¶Subtree cycling: Rotate current subtree among the states
,-> FOLDED -> CHILDREN -> SUBTREE --. '-----------------------------------'
Point must be on a headline for this to work4.
org-global-cycle), C-u TAB ¶Global cycling: Rotate the entire buffer among the states
,-> OVERVIEW -> CONTENTS -> SHOW ALL --. '--------------------------------------'
When S-TAB is called with a numeric prefix argument N, view contents only up to headlines of level N.
Note that inside tables (see Tables), S-TAB jumps to the previous field instead.
You can run global cycling using TAB only if point is at
the very beginning of the buffer, but not on a headline, and
org-cycle-global-at-bob is set to a non-nil value.
org-cycle-set-startup-visibility) ¶Switch back to the startup visibility of the buffer (see Initial visibility).
org-fold-show-all) ¶Show all, including drawers.
org-reveal) ¶Reveal context around point, showing the current entry, the following heading, and the hierarchy above. It is useful for working near a location that has been exposed by a sparse tree command (see Sparse Trees) or an agenda command (see Commands in the Agenda Buffer). With a prefix argument, show, on each level, all sibling headings. With a double prefix argument, also show the entire subtree of the parent.
org-show-branches) ¶Expose all the headings of the subtree, but not their bodies.
org-fold-show-children) ¶Expose all direct children of the subtree. With a numeric prefix argument N, expose all children down to level N.
org-tree-to-indirect-buffer) ¶Show the current subtree in an indirect buffer5. With a numeric prefix argument N, go up to level N and then take that tree. If N is negative, then go up that many levels. With a C-u prefix, do not remove the previously used indirect buffer.
org-copy-visible) ¶Copy the visible text in the region into the kill ring.
When Emacs first visits an Org file, the global state is set to
showeverything, i.e., all file content is visible6. This can be configured through the
variable org-startup-folded, or on a per-file basis by adding one of
the following lines anywhere in the buffer:
#+STARTUP: overview #+STARTUP: content #+STARTUP: showall #+STARTUP: show2levels #+STARTUP: show3levels #+STARTUP: show4levels #+STARTUP: show5levels #+STARTUP: showeverything
Furthermore, any entries with a ‘VISIBILITY’ property (see Properties and Columns) get their visibility adapted accordingly. Allowed values for this property are ‘folded’, ‘children’, ‘content’, and ‘all’.
org-cycle-set-startup-visibility) ¶Switch back to the startup visibility of the buffer, i.e., whatever is requested by startup options and ‘VISIBILITY’ properties in individual entries.
Sometimes you may inadvertently edit an invisible part of the buffer
and be confused about what has been edited and how to undo the mistake.
By default, Org prevents such edits for a limited set of user
commands. Users can control which commands are affected by
customizing org-fold-catch-invisible-edits-commands.
The strategy used to decide if a given edit is dangerous is controlled
by org-fold-catch-invisible-edits. See the docstring of this option
for the available strategies. Set the option to nil to disable
catching invisible edits completely.
The following commands jump to other headlines in the buffer.
org-next-visible-heading) ¶Next heading.
org-previous-visible-heading) ¶Previous heading.
org-forward-heading-same-level) ¶Next heading same level.
org-backward-heading-same-level) ¶Previous heading same level.
outline-up-heading) ¶Backward to higher level heading.
org-goto) ¶Jump to a different place without changing the current outline visibility. Shows the document structure in a temporary buffer, where you can use the following keys to find your destination:
| TAB | Cycle visibility. |
| DOWN / UP | Next/previous visible headline. |
| RET | Select this location. |
| / | Do a Sparse-tree search |
The following keys work if you turn off org-goto-auto-isearch.
| n / p | Next/previous visible headline. |
| f / b | Next/previous headline same level. |
| u | One level up. |
| 0 … 9 | Digit argument. |
| q | Quit. |
See also the variable org-goto-interface.
org-meta-return) ¶Insert a new heading, item, or row.
If the command is used at the beginning of a line, and if there is a heading or a plain list item (see Plain Lists) at point, the new heading/item is created before the current line. When used at the beginning of a regular line of text, turn that line into a heading.
When this command is used in the middle of a line, the line is split
and the rest of the line becomes the new item or headline. If you
do not want the line to be split, customize
org-M-RET-may-split-line.
Calling the command with a C-u prefix unconditionally inserts a new heading at the end of the current subtree, thus preserving its contents. With a double C-u C-u prefix, the new heading is created at the end of the parent subtree instead.
org-insert-heading-respect-content) ¶Insert a new heading at the end of the current subtree.
org-insert-todo-heading) ¶Insert new TODO entry with same level as current heading. See also
the variable org-treat-insert-todo-heading-as-state-change.
org-insert-todo-heading-respect-content) ¶Insert new TODO entry with same level as current heading. Like C-RET, the new headline is inserted after the current subtree.
org-cycle) ¶In a new entry with no text yet, the first TAB demotes the entry to become a child of the previous one. The next TAB makes it a parent, and so on, all the way to top level. Yet another TAB, and you are back to the initial level.
org-do-promote), M-RIGHT (org-do-demote) ¶Promote or demote current heading by one level.
When there is an active region—i.e., when Transient Mark mode is active—promotion and demotion work on all headlines in the region. To select a region of headlines, it is best to set mark at the beginning of the first headline, and point at the line just after the last headline to change.
org-promote-subtree) ¶Promote the current subtree by one level.
org-demote-subtree) ¶Demote the current subtree by one level.
org-move-subtree-up) ¶Move subtree up, i.e., swap with previous subtree of same level.
org-move-subtree-down) ¶Move subtree down, i.e., swap with next subtree of same level.
org-mark-subtree) ¶Mark the subtree at point. Hitting it repeatedly marks subsequent subtrees of the same level as the marked subtree.
org-cut-subtree) ¶Kill subtree, i.e., remove it from the buffer but save in kill ring. With a numeric prefix argument N, kill N sequential subtrees.
org-copy-subtree) ¶Copy subtree to kill ring. With a numeric prefix argument N, copy the N sequential subtrees.
org-paste-subtree) ¶Yank subtree from kill ring. This does modify the level of the subtree to make sure the tree fits in nicely at the yank position. The yank level can also be specified with a numeric prefix argument, or by yanking after a headline marker like ‘****’. With C-u prefix, force inserting as a sibling. With C-u C-u prefix argument, force inserting as a child.
org-yank) ¶Depending on the variables org-yank-adjusted-subtrees and
org-yank-folded-subtrees, Org’s internal yank command pastes
subtrees folded and in a clever way, using the same command as
C-c C-x C-y. With the default settings, no level
adjustment takes place, but the yanked tree is folded unless doing
so would swallow text previously visible. Any prefix argument to
this command forces a normal yank to be executed, with the prefix
passed along. A good way to force a normal yank is C-u C-y. If you use yank-pop after a yank, it yanks previous kill
items plainly, without adjustment and folding.
org-clone-subtree-with-time-shift) ¶Clone a subtree by making a number of sibling copies of it. You are
prompted for the number of copies to make, and you can also specify
whether any timestamps in the entry should be shifted. This can be
useful, for example, to create a number of tasks related to a series
of lectures to prepare. For more details, see the docstring of the
command org-clone-subtree-with-time-shift.
org-refile) ¶Refile entry or region to a different location. See Refile and Copy.
org-sort) ¶Sort same-level entries. When there is an active region, all entries in the region are sorted. Otherwise, the children of the current headline are sorted. The command prompts for the sorting method, which can be alphabetically, numerically, by time—first timestamp with active preferred, creation time, scheduled time, deadline time—by priority, by TODO keyword—in the sequence the keywords have been defined in the setup—or by the value of a property. Reverse sorting is possible as well. You can also supply your own function to extract the sorting key. With a C-u prefix, sorting is case-sensitive.
org-narrow-to-subtree) ¶Narrow buffer to current subtree.
org-narrow-to-block) ¶Narrow buffer to current block.
widen) ¶Widen buffer to remove narrowing.
org-toggle-heading) ¶Turn a normal line or plain list item into a headline—so that it becomes a subheading at its location. Also turn a headline into a normal line by removing the stars. If there is an active region, turn all lines in the region into headlines. If the first line in the region was an item, turn only the item lines into headlines. Finally, if the first line is a headline, remove the stars from all headlines in the region.
Note that when point is inside a table (see Tables), the Meta-Cursor keys have different functionality.
An important feature of Org mode is the ability to construct sparse trees for selected information in an outline tree, so that the entire document is folded as much as possible, but the selected information is made visible along with the headline structure above it7. Just try it out and you will see immediately how it works.
Org mode contains several commands creating such trees, all of which can be accessed through a dispatcher:
org-sparse-tree) ¶This prompts for an extra key to select a sparse-tree creating command.
org-occur) ¶Prompts for a regexp (see Regular Expressions) and shows a sparse tree with all matches. If the match is in a headline, the headline is made visible. If the match is in the body of an entry, the headline and body are made visible. In order to provide minimal context, also the full hierarchy of headlines above the match is shown, as well as the headline following the match. Each match is also highlighted; the highlights disappear when the buffer is changed by an editing command, or by pressing C-c C-c8. When called with a C-u prefix argument, previous highlights are kept, so several calls to this command can be stacked.
next-error) ¶Jump to the next sparse tree match in this buffer.
previous-error) ¶Jump to the previous sparse tree match in this buffer.
For frequently used sparse trees for specific search strings, you can
use the variable org-agenda-custom-commands to define fast keyboard
access to specific sparse trees. These commands will then be
accessible through the agenda dispatcher (see The Agenda Dispatcher).
For example:
(setq org-agenda-custom-commands
'(("f" occur-tree "FIXME")))
defines the key f as a shortcut for creating a sparse tree matching the string ‘FIXME’.
The other sparse tree commands select headings based on TODO keywords, tags, or properties and are discussed later in this manual.
To print a sparse tree, you can use the Emacs command
ps-print-buffer-with-faces, which does not print invisible parts of
the document. Or you can use the command C-c C-e C-v to
export only the visible part of the document and print the resulting
file.
Within an entry of the outline tree, hand-formatted lists can provide additional structure. They also provide a way to create lists of checkboxes (see Checkboxes). Org supports editing such lists, and every exporter (see Exporting) can parse and format them.
Org knows ordered lists, unordered lists, and description lists.
Items belonging to the same list must have the same indentation on the first line. In particular, if an ordered list reaches number ‘10.’, then the 2-digit numbers must be written left-aligned with the other numbers in the list. An item ends before the next line that has an indentation less than or equal to its bullet/number.
A list ends whenever every item has ended, which means before any line with an indentation less than or equal to that of the top-level items. It also ends before two blank lines. In that case, all items are closed. Here is an example:
* Lord of the Rings
My favorite scenes are (in this order)
1. The attack of the Rohirrim
2. Eowyn's fight with the witch king
+ this was already my favorite scene in the book
+ I really like Miranda Otto.
3. Peter Jackson being shot by Legolas
- on DVD only
He makes a really funny face when it happens.
8. [@8] <favorite scenes 4 to 8 are skipped for brevity>
But in the end, no individual scenes matter but the film as a whole.
Important actors in this film are:
- Elijah Wood :: He plays Frodo
- Sean Astin :: He plays Sam, Frodo's friend. I still remember him
very well from his role as Mikey Walsh in /The Goonies/.
Org supports these lists by tuning filling and wrapping commands to deal with them correctly, and by exporting them properly (see Exporting). Since indentation is what governs the structure of these lists, many structural constructs like ‘#+BEGIN_’ blocks can be indented to signal that they belong to a particular item.
If you find that using a different bullet for a sub-list—than that
used for the current list-level—improves readability, customize the
variable org-list-demote-modify-bullet. To get a greater difference
of indentation between items and their sub-items, customize
org-list-indent-offset.
The following commands act on items when point is in the first line of
an item—the line with the bullet or number. Some of them imply the
application of automatic rules to keep list structure intact. If some
of these actions get in your way, configure org-list-automatic-rules
to disable them individually.
org-cycle) ¶Items can be folded just like headline levels. Normally this works
only if point is on a plain list item. For more details, see the
variable org-cycle-include-plain-lists. If this variable is set
to integrate, plain list items are treated like low-level
headlines. The level of an item is then given by the indentation of
the bullet/number. Items are always subordinate to real headlines,
however; the hierarchies remain completely separated. In a new item
with no text yet, the first TAB demotes the item to
become a child of the previous one. Subsequent TABs move
the item to meaningful levels in the list and eventually get it back
to its initial position.
org-insert-item) ¶Insert new item at current level. With a prefix argument, force a new heading (see Structure Editing). If this command is used in the middle of an item, that item is split in two, and the second part becomes the new item13. If this command is executed before the item’s body, the new item is created before the current one.
Insert a new item with a checkbox (see Checkboxes).
Jump to the previous/next item in the current list, but only if
org-support-shift-select is off14.
If not, you can still use paragraph jumping commands like
C-UP and C-DOWN to quite similar effect.
Move the item including sub-items up/down15, i.e., swap with previous/next item of same indentation. If the list is ordered, renumbering is automatic.
Decrease/increase the indentation of an item, leaving children alone.
Decrease/increase the indentation of the item, including sub-items. Initially, the item tree is selected based on current indentation. When these commands are executed several times in direct succession, the initially selected region is used, even if the new indentation would imply a different hierarchy. To use the new hierarchy, break the command chain by moving point.
As a special case, using this command on the very first item of
a list moves the whole list. This behavior can be disabled by
configuring org-list-automatic-rules. The global indentation of
a list has no influence on the text after the list.
If there is a checkbox (see Checkboxes) in the item line, toggle the state of the checkbox. In any case, verify bullets and indentation consistency in the whole list.
Cycle the entire list level through the different itemize/enumerate
bullets (‘-’, ‘+’, ‘*’, ‘1.’, ‘1)’) or a subset of them, depending
on org-plain-list-ordered-item-terminator, the type of list, and
its indentation. With a numeric prefix argument N, select the Nth
bullet from this list. If there is an active region when calling
this, all lines are converted to list items. With a prefix
argument, the selected text is changed into a single item. If the
first line already was a list item, any item marker is removed from
the list. Finally, even without an active region, a normal line is
converted into a list item.
Turn a plain list item into a headline—so that it becomes a subheading at its location. See Structure Editing for a detailed explanation.
Turn the whole plain list into a subtree of the current heading. Checkboxes (see Checkboxes) become ‘TODO’ or ‘DONE’ keywords when unchecked or checked, respectively.
This command also cycles bullet styles when point is on the bullet
or anywhere in an item line, with details depending on
org-support-shift-select.
Sort the plain list. Prompt for the sorting method: numerically, alphabetically, by time, or by custom function.
Sometimes you want to keep information associated with an entry, but you do not normally want to see it. For this, Org mode has drawers. They can contain anything but a headline and another drawer. Drawers look like this:
** This is a headline Still outside the drawer :DRAWERNAME: This is inside the drawer. :END: After the drawer.
You can interactively insert a drawer at point by calling
org-insert-drawer, which is bound to C-c C-x d. With an
active region, this command puts the region inside the drawer. With a
prefix argument, this command calls non-interactive function
org-insert-property-drawer, which creates a ‘PROPERTIES’ drawer
right below the current headline. Org mode uses this special drawer
for storing properties (see Properties and Columns). You cannot use
it for anything else.
Completion over drawer keywords is also possible using M-TAB16.
Visibility cycling (see Visibility Cycling) on the headline hides and shows the entry, but keeps the drawer collapsed to a single line. In order to look inside the drawer, you need to move point to the drawer line and press TAB there.
You can also arrange for state change notes (see Tracking TODO state changes) and clock times (see Clocking Work Time) to be stored in a ‘LOGBOOK’ drawer. If you want to store a quick note there, similarly to state changes, use
Add a time-stamped note to the ‘LOGBOOK’ drawer.
Org mode uses ‘#+BEGIN’ … ‘#+END’ blocks for various purposes, from
including source code examples (see Literal Examples) to capturing
time logging information (see Clocking Work Time). These blocks can
be folded and unfolded by pressing TAB in the ‘#+BEGIN’
line. You can also get all blocks folded at startup by configuring
the variable org-hide-block-startup or on a per-file basis by using
#+STARTUP: hideblocks #+STARTUP: nohideblocks
Org comes with a fast and intuitive table editor. Spreadsheet-like calculations are supported using the Emacs Calc package (see GNU Emacs Calculator Manual).
Org makes it easy to format tables in plain ASCII. Any line with ‘|’ as the first non-whitespace character is considered part of a table. ‘|’ is also the column separator17. Moreover, a line starting with ‘|-’ is a horizontal rule. It separates rows explicitly. Rows before the first horizontal rule are header lines. A table might look like this:
| Name | Phone | Age | |-------+-------+-----| | Peter | 1234 | 17 | | Anna | 4321 | 25 |
A table is re-aligned automatically each time you press TAB, RET, or C-c C-c inside the table. TAB also moves to the next field—RET to the next row—and creates new table rows at the end of the table or before horizontal lines. The indentation of the table is set by the first line. Horizontal rules are automatically expanded on every re-align to span the whole table width. So, to create the above table, you would only type
|Name|Phone|Age| |-
and then press TAB to align the table and start filling in fields. Even faster would be to type ‘|Name|Phone|Age’ followed by C-c RET.
When typing text into a field, Org treats DEL,
Backspace, and all character keys in a special way, so that
inserting and deleting avoid shifting other fields. Also, when
typing immediately after point was moved into a new field with
TAB, S-TAB or RET, the field is
automatically made blank. If this behavior is too unpredictable for
you, configure the option org-table-auto-blank-field.
org-table-create-or-convert-from-region) ¶Convert the active region to table. If every line contains at least one TAB character, the function assumes that the material is tab separated. If every line contains a comma, comma-separated values (CSV) are assumed. If not, lines are split at whitespace into fields. You can use a prefix argument to force a specific separator: C-u forces CSV, C-u C-u forces TAB, C-u C-u C-u prompts for a regular expression to match the separator, and a numeric argument N indicates that at least N consecutive spaces, or alternatively a TAB will be the separator.
If there is no active region, this command creates an empty Org table. But it is easier just to start typing, like | N a m e | P h o n e | A g e RET | - TAB.
org-table-align) ¶Re-align the table without moving point.
org-table-next-field) ¶Re-align the table, move to the next field. Creates a new row if necessary.
Blank the current table field or active region.
org-table-previous-field) ¶Re-align, move to previous field.
org-table-next-row) ¶Re-align the table and move down to next row. Creates a new row if necessary. At the beginning or end of a line, RET still inserts a new line, so it can be used to split a table.
org-table-beginning-of-field) ¶Move to beginning of the current table field, or onto the previous field.
org-table-end-of-field) ¶Move to end of the current table field, or onto the next field.
org-table-move-column-left) ¶Move the current column left.
org-table-move-column-right) ¶Move the current column right.
org-table-delete-column) ¶Kill the current column.
org-table-insert-column) ¶Insert a new column at point position. Move the current column and all cells to the right of this column to the right.
org-table-move-row-up) ¶Move the current row up.
org-table-move-row-down) ¶Move the current row down.
org-table-kill-row) ¶Kill the current row or horizontal line.
org-table-move-cell-up) ¶Move cell up by swapping with adjacent cell.
org-table-move-cell-down) ¶Move cell down by swapping with adjacent cell.
org-table-move-cell-left) ¶Move cell left by swapping with adjacent cell.
org-table-move-cell-right) ¶Move cell right by swapping with adjacent cell.
org-table-insert-row) ¶Insert a new row above the current row. With a prefix argument, the line is created below the current one.
org-table-insert-hline) ¶Insert a horizontal line below current row. With a prefix argument, the line is created above the current line.
org-table-hline-and-move) ¶Insert a horizontal line below current row, and move point into the row below that line.
org-table-sort-lines) ¶Sort the table lines in the region. The position of point indicates the column to be used for sorting, and the range of lines is the range between the nearest horizontal separator lines, or the entire table. If point is before the first column, you are prompted for the sorting column. If there is an active region, the mark specifies the first line and the sorting column, while point should be in the last line to be included into the sorting. The command prompts for the sorting type, alphabetically, numerically, or by time. You can sort in normal or reverse order. You can also supply your own key extraction and comparison functions. When called with a prefix argument, alphabetic sorting is case-sensitive.
org-table-copy-region) ¶Copy a rectangular region from a table to a special clipboard. Point and mark determine edge fields of the rectangle. If there is no active region, copy just the current field. The process ignores horizontal separator lines.
org-table-cut-region) ¶Copy a rectangular region from a table to a special clipboard, and blank all fields in the rectangle. So this is the “cut” operation.
org-table-paste-rectangle) ¶Paste a rectangular region into a table. The upper left corner ends up in the current field. All involved fields are overwritten. If the rectangle does not fit into the present table, the table is enlarged as needed. The process ignores horizontal separator lines.
org-table-wrap-region) ¶Split the current field at point position and move the rest to the line below. If there is an active region, and both point and mark are in the same column, the text in the column is wrapped to minimum width for the given number of lines. A numeric prefix argument may be used to change the number of desired lines. If there is no region, but you specify a prefix argument, the current field is made blank, and the content is appended to the field above.
org-table-sum) ¶Sum the numbers in the current column, or in the rectangle defined by the active region. The result is shown in the echo area and can be inserted with C-y.
org-table-copy-down) ¶When the current field is empty, copy from the first non-empty field above. When it is not empty, copy the current field down to the next row and move point along with it.
Depending on the variable org-table-copy-increment, integer and
time stamp field values, as well as fields prefixed or suffixed with
a whole number, can be incremented during copy. Also, a 0 prefix
argument temporarily disables the increment.
This key is also used by shift-selection and related modes (see Packages that conflict with Org mode).
org-table-edit-field) ¶Edit the current field in a separate window. This is useful for fields that are not fully visible (see Column Width and Alignment). When called with a C-u prefix, just make the full field visible, so that it can be edited in place. When called with two C-u prefixes, make the editor window follow point through the table and always show the current field. The follow mode exits automatically when point leaves the table, or when you repeat this command with C-u C-u C-c `.
Import a file as a table. The table should be TAB- or whitespace-separated. Use, for example, to import a spreadsheet table or data from a database, because these programs generally can write TAB-separated text files. This command works by inserting the file into the buffer and then converting the region to a table. Any prefix argument is passed on to the converter, which uses it to determine the separator.
org-table-create-or-convert-from-region) ¶Tables can also be imported by pasting tabular text into the Org buffer, selecting the pasted text with C-x C-x and then using the C-c | command (see Creation and conversion).
Export the table, by default as a TAB-separated file. Use for data
exchange with, for example, spreadsheet or database programs. The
format used to export the file can be configured in the variable
org-table-export-default-format. You may also use properties
‘TABLE_EXPORT_FILE’ and ‘TABLE_EXPORT_FORMAT’ to specify the file
name and the format for table export in a subtree. Org supports
quite general formats for exported tables. The exporter format is
the same as the format used by Orgtbl radio tables, see Translator functions, for a detailed description.
Turn on the display of the first data row of the table at point in
the window header line when this first row is not visible anymore in
the buffer. You can activate this minor mode by default by setting
the option org-table-header-line-p to t.
Transpose the table at point and eliminate hlines.
The width of columns is automatically determined by the table editor. The alignment of a column is determined automatically from the fraction of number-like versus non-number fields in the column.
Editing a field may modify the alignment of the table. Moving
a contiguous row or column—i.e., using TAB or
RET—automatically re-aligns it. If you want to disable
this behavior, set org-table-automatic-realign to nil. In any
case, you can always align manually a table:
org-table-align) ¶Align the current table.
Setting the option org-startup-align-all-tables re-aligns all tables
in a file upon visiting it. You can also set this option on
a per-file basis with:
#+STARTUP: align #+STARTUP: noalign
Sometimes a single field or a few fields need to carry more text, leading to inconveniently wide columns. Maybe you want to hide away several columns or display them with a fixed width, regardless of content, as shown in the following example.
|---+---------------------+--------| |---+-------…+…| | | <6> | | | | <6> …|…| | 1 | one | some | ----\ | 1 | one …|…| | 2 | two | boring | ----/ | 2 | two …|…| | 3 | This is a long text | column | | 3 | This i…|…| |---+---------------------+--------| |---+-------…+…|
To set the width of a column, one field anywhere in the column may contain just the string ‘<N>’ where N specifies the width as a number of characters. You control displayed width of columns with the following tools:
org-table-toggle-column-width) ¶Shrink or expand current column.
If a width cookie specifies a width W for the column, shrinking it displays the first W visible characters only. Otherwise, the column is shrunk to a single character.
When called before the first column or after the last one, ask for a list of column ranges to operate on.
org-table-shrink) ¶Shrink all columns with a column width. Expand the others.
org-table-expand) ¶Expand all columns.
To see the full text of a shrunk field, hold the mouse over it:
a tooltip window then shows the full contents of the field.
Alternatively, C-h . (display-local-help) reveals them,
too. For convenience, any change near the shrunk part of a column
expands it.
Setting the option org-startup-shrink-all-tables shrinks all columns
containing a width cookie in a file the moment it is visited. You can
also set this option on a per-file basis with:
#+STARTUP: shrink
If you would like to overrule the automatic alignment of number-rich columns to the right and of string-rich columns to the left, you can use ‘<r>’, ‘<c>’ or ‘<l>’ in a similar fashion. You may also combine alignment and field width like this: ‘<r10>’.
Lines which only contain these formatting cookies are removed automatically upon exporting the document.
When Org exports tables, it does so by default without vertical lines because that is visually more satisfying in general. Occasionally, however, vertical lines can be useful to structure a table into groups of columns, much like horizontal lines can do for groups of rows. In order to specify column groups, you can use a special row where the first field contains only ‘/’. The further fields can either contain ‘<’ to indicate that this column should start a group, ‘>’ to indicate the end of a column, or ‘<>’ (no space between ‘<’ and ‘>’) to make a column a group of its own. Upon export, boundaries between column groups are marked with vertical lines. Here is an example:
| N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) | |---+-----+-----+-----+---------+------------| | / | < | | > | < | > | | 1 | 1 | 1 | 1 | 1 | 1 | | 2 | 4 | 8 | 16 | 1.4142 | 1.1892 | | 3 | 9 | 27 | 81 | 1.7321 | 1.3161 | |---+-----+-----+-----+---------+------------| #+TBLFM: $2=$1^2::$3=$1^3::$4=$1^4::$5=sqrt($1)::$6=sqrt(sqrt(($1)))
It is also sufficient to just insert the column group starters after every vertical line you would like to have:
| N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) | |---+-----+-----+-----+---------+------------| | / | < | | | < | |
If you like the intuitive way the Org table editor works, you might also want to use it in other modes like Text mode or Mail mode. The minor mode Orgtbl mode makes this possible. You can always toggle the mode with M-x orgtbl-mode. To turn it on by default, for example in Message mode, use
(add-hook 'message-mode-hook #'turn-on-orgtbl)
Furthermore, with some special setup, it is possible to maintain tables in arbitrary syntax with Orgtbl mode. For example, it is possible to construct LaTeX tables with the underlying ease and power of Orgtbl mode, including spreadsheet capabilities. For details, see Tables in Arbitrary Syntax.
The table editor makes use of the Emacs Calc package to implement spreadsheet-like capabilities. It can also evaluate Emacs Lisp forms to derive fields from other fields. While fully featured, Org’s implementation is not identical to other spreadsheets. For example, Org knows the concept of a column formula that will be applied to all non-header fields in a column without having to copy the formula to each relevant field. There is also a formula debugger, and a formula editor with features for highlighting fields in the table corresponding to the references at point in the formula, moving these references by arrow keys.
To compute fields in the table from other fields, formulas must reference other fields or ranges. In Org, fields can be referenced by name, by absolute coordinates, and by relative coordinates. To find out what the coordinates of a field are, press C-c ? in that field, or press C-c } to toggle the display of a grid.
Formulas can reference the value of another field in two ways. Like in any other spreadsheet, you may reference fields with a letter/number combination like ‘B3’, meaning the second field in the third row. However, Org prefers to use another, more general representation that looks like this:18
@ROW$COLUMN
Column specifications can be absolute like ‘$1’, ‘$2’, …, ‘$N’, or relative to the current column, i.e., the column of the field which is being computed, like ‘$+1’ or ‘$-2’. ‘$<’ and ‘$>’ are immutable references to the first and last column, respectively, and you can use ‘$>>>’ to indicate the third column from the right.
The row specification only counts data lines and ignores horizontal separator lines, or “hlines”. Like with columns, you can use absolute row numbers ‘@1’, ‘@2’, …, ‘@N’, and row numbers relative to the current row like ‘@+3’ or ‘@-1’. ‘@<’ and ‘@>’ are immutable references to the first and last row in the table, respectively. You may also specify the row relative to one of the hlines: ‘@I’ refers to the first hline, ‘@II’ to the second, etc. ‘@-I’ refers to the first such line above the current line, ‘@+I’ to the first such line below the current line. You can also write ‘@III+2’ which is the second data line after the third hline in the table.
‘@0’ and ‘$0’ refer to the current row and column, respectively, i.e., to the row/column for the field being computed. Also, if you omit either the column or the row part of the reference, the current row/column is implied.
Org’s references with unsigned numbers are fixed references in the sense that if you use the same reference in the formula for two different fields, the same field is referenced each time. Org’s references with signed numbers are floating references because the same reference operator can reference different fields depending on the field being calculated by the formula.
Here are a few examples:
| ‘@2$3’ | 2nd row, 3rd column (same as ‘C2’) |
| ‘$5’ | column 5 in the current row (same as ‘E&’) |
| ‘@2’ | current column, row 2 |
| ‘@-1$-3’ | field one row up, three columns to the left |
| ‘@-I$2’ | field just under hline above current row, column 2 |
| ‘@>$5’ | field in the last row, in column 5 |
You may reference a rectangular range of fields by specifying two field references connected by two dots ‘..’. The ends are included in the range. If both fields are in the current row, you may simply use ‘$2..$7’, but if at least one field is in a different row, you need to use the general ‘@ROW$COLUMN’ format at least for the first field, i.e., the reference must start with ‘@’ in order to be interpreted correctly. Examples:
| ‘$1..$3’ | first three fields in the current row |
| ‘$P..$Q’ | range, using column names (see Advanced features) |
| ‘$<<<..$>>’ | start in third column, continue to the last but one |
| ‘@2$1..@4$3’ | nine fields between these two fields (same as ‘A2..C4’) |
| ‘@-1$-2..@-1’ | 3 fields in the row above, starting from 2 columns on the left |
| ‘@I..II’ | between first and second hline, short for ‘@I..@II’ |
Range references return a vector of values that can be fed into Calc vector functions. Empty fields in ranges are normally suppressed, so that the vector contains only the non-empty fields. For other options with the mode switches ‘E’, ‘N’ and examples, see Formula syntax for Calc.
One of the very first actions during evaluation of Calc formulas and
Lisp formulas is to substitute ‘@#’ and ‘$#’ in the formula with the
row or column number of the field where the current result will go to.
The traditional Lisp formula equivalents are org-table-current-dline
and org-table-current-column. Examples:
Insert column number on odd rows, set field to empty on even rows.
Copy text or values of each row of column 1 of the table named FOO into column 2 of the current table.
Insert the doubled value of each column of row 1 of the table named FOO into row 3 of the current table.
For the second and third examples, table FOO must have at least as many rows or columns as the current table. Note that this is inefficient19 for a large number of rows.
‘$name’ is interpreted as the name of a column, parameter or constant.
Constants are defined globally through the variable
org-table-formula-constants, and locally—for the file—through
a line like this example:
#+CONSTANTS: c=299792458. pi=3.14 eps=2.4e-6
Also, properties (see Properties and Columns) can be used as constants in table formulas: for a property ‘Xyz’ use the name ‘$PROP_Xyz’, and the property will be searched in the current outline entry and in the hierarchy above it. If you have the ‘constants.el’ package, it will also be used to resolve constants, including natural constants like ‘$h’ for Planck’s constant, and units like ‘$km’ for kilometers20. Column names and parameters can be specified in special table lines. These are described below, see Advanced features. All names must start with a letter, and further consist of letters and numbers.
You may also reference constants, fields and ranges from a different table, either in the current file or even in a different file. The syntax is
remote(NAME,REF)
where NAME can be the name of a table in the current file as set by a ‘#+NAME:’ line before the table. It can also be the ID of an entry, even in a different file, and the reference then refers to the first table in that entry. REF is an absolute field or range reference as described above for example ‘@3$3’ or ‘$somename’, valid in the referenced table.
When NAME has the format ‘@ROW$COLUMN’, it is substituted with the name or ID found in this field of the current table. For example ‘remote($1, @@>$2)’ ⇒ ‘remote(year_2013, @@>$1)’. The format ‘B3’ is not supported because it cannot be distinguished from a plain table name or ID.
A formula can be any algebraic expression understood by the Emacs Calc
package. Note that Calc has the non-standard convention that ‘/’ has
lower precedence than ‘*’, so that ‘a/b*c’ is interpreted as
‘(a/(b*c))’. Before evaluation by calc-eval (see Calling Calc from
Your Lisp Programs), variable substitution takes place according to
the rules described above.
The range vectors can be directly fed into the Calc vector functions
like vmean and vsum.
A formula can contain an optional mode string after a semicolon. This
string consists of flags to influence Calc and other modes during
execution. By default, Org uses the standard Calc modes (precision
12, angular units degrees, fraction and symbolic modes off). The
display format, however, has been changed to ‘(float 8)’ to keep
tables compact. The default settings can be configured using the
variable org-calc-default-modes.
Set the internal Calc calculation precision to 20 digits.
Normal, scientific, engineering or fixed format of the result of Calc passed back to Org. Calc formatting is unlimited in precision as long as the Calc calculation precision is greater.
Degree and radian angle modes of Calc.
Fraction and symbolic modes of Calc.
Units simplification mode of Calc. Calc is also a symbolic calculator and is capable of working with values having a unit, represented with numerals followed by a unit string in Org table cells. This mode instructs Calc to simplify the units in the computed expression before returning the result.
Duration computations in Calc or Lisp, Durations and time values.
If and how to consider empty fields. Without ‘E’ empty fields in range references are suppressed so that the Calc vector or Lisp list contains only the non-empty fields. With ‘E’ the empty fields are kept. For empty fields in ranges or empty field references the value ‘nan’ (not a number) is used in Calc formulas and the empty string is used for Lisp formulas. Add ‘N’ to use 0 instead for both formula types. For the value of a field the mode ‘N’ has higher precedence than ‘E’.
Interpret all fields as numbers, use 0 for non-numbers. See the next section to see how this is essential for computations with Lisp formulas. In Calc formulas it is used only occasionally because there number strings are already interpreted as numbers without ‘N’.
Literal, for Lisp formulas only. See the next section.
You may also provide a format specifier (similar to printf)21
to reformat the Calc result after it has been passed back to Org
instead of letting Calc handle the formatting. A few examples:
| ‘$1+$2’ | Sum of first and second field |
| ‘$1+$2;%.2f’ | Same, format result to two decimals |
| ‘exp($2)+exp($1)’ | Math functions can be used |
| ‘$0;%.1f’ | Reformat current cell to 1 decimal |
| ‘($3-32)*5/9’ | Fahrenheit to Celsius conversion |
| ‘$c/$1/$cm’ | Hertz to centimeter conversion using ‘constants.el’ |
| ‘tan($1);Dp3s1’ | Compute in degrees, precision 3, display SCI 1 |
| ‘sin($1);Dp3%.1e’ | Same, but use format specifier for display |
| ‘vmean($2..$7)’ | Compute column range mean, using vector function |
| ‘vmean($2..$7);EN’ | Same, but treat empty fields as 0 |
| ‘taylor($3,x=7,2)’ | Taylor series of $3, at x=7, second degree |
Calc also contains a complete set of logical operations (see Logical Operations). For example
‘"teen"’ if age ‘$1’ is less than 20, else the Org table result field is set to empty with the empty string.
Sum of the first two columns. When at least one of the input fields is empty, the Org table result field is set to empty. ‘E’ is required to not convert empty fields to 0. ‘f-1’ is an optional Calc format string similar to ‘%.1f’ but leaves empty results empty.
Mean value of a range unless there is any empty field. Every field
in the range that is empty is replaced by ‘nan’ which lets ‘vmean’
return ‘nan’. Then ‘typeof =’ 12= detects the ‘nan’ from vmean
and the Org table result field is set to empty. Use this when the
sample set is expected to never have missing values.
Mean value of a range with empty fields skipped. Every field in the range that is empty is skipped. When all fields in the range are empty the mean value is not defined and the Org table result field is set to empty. Use this when the sample set can have a variable size.
To complete the previous example: Mean value of a range with empty fields counting as samples with value 0. Use this only when incomplete sample sets should be padded with 0 to the full size.
You can add your own Calc functions defined in Emacs Lisp with
defmath and use them in formula syntax for Calc.
It is also possible to write a formula in Emacs Lisp. This can be useful for string manipulation and control structures, if Calc’s functionality is not enough.
A formula is evaluated as a Lisp form when it starts with a
single-quote followed by an opening parenthesis. Cell table
references are interpolated into the Lisp form before execution. The
evaluation should return either a string or a number. Evaluation
modes and a format string (similar to printf)22 used to render
the returned values can be specified after a semicolon.
By default, references are interpolated as literal Lisp strings: the field content is replaced in the Lisp form stripped of leading and trailing white space and surrounded in double-quotes. For example:
'(concat $1 $2)
concatenates the content of columns 1 and column 2.
When the ‘N’ flag is used, all referenced elements are parsed as numbers and interpolated as Lisp numbers, without quotes. Fields that cannot be parsed as numbers are interpolated as zeros. For example:
'(+ $1 $2);N
adds columns 1 and 2, equivalent to Calc’s ‘$1+$2’. Ranges are inserted as space-separated fields, so they can be embedded in list or vector syntax. For example:
'(apply '+ '($1..$4));N
computes the sum of columns 1 to 4, like Calc’s ‘vsum($1..$4)’.
When the ‘L’ flag is used, all fields are interpolated literally: the cell content is replaced in the Lisp form stripped of leading and trailing white space and without quotes. If a reference is intended to be interpreted as a string by the Lisp form, the reference operator itself should be enclosed in double-quotes, like ‘"$3"’. The ‘L’ flag is useful when strings and numbers are used in the same Lisp form. For example:
'(substring "$1" $2 $3);L
extracts the part of the string in column 1 between the character positions specified in the integers in column 2 and 3, and it is easier to read than the equivalent:
'(substring $1 (string-to-number $2) (string-to-number $3))
When the formula itself contains ‘;’ symbol, Org mode may incorrectly interpret everything past ‘;’ as format specifier:
'(concat $1 ";")
You can put an extra trailing ‘;’ to indicate that all the earlier instances of ‘;’ belong to the formula itself:
'(concat $1 ";");
If you want to compute time values use the ‘T’, ‘t’, or ‘U’ flag, either in Calc formulas or Elisp formulas:
| Task 1 | Task 2 | Total | |---------+----------+----------| | 2:12 | 1:47 | 03:59:00 | | 2:12 | 1:47 | 03:59 | | 3:02:20 | -2:07:00 | 0.92 | #+TBLFM: @2$3=$1+$2;T::@3$3=$1+$2;U::@4$3=$1+$2;t
Input duration values must be of the form ‘HH:MM[:SS]’, where seconds
are optional. With the ‘T’ flag, computed durations are displayed as
‘HH:MM:SS’ (see the first formula above). With the ‘U’ flag, seconds
are omitted so that the result is only ‘HH:MM’ (see second formula
above). Zero-padding of the hours field depends upon the value of the
variable org-table-duration-hour-zero-padding.
With the ‘t’ flag, computed durations are displayed according to the
value of the option org-table-duration-custom-format, which defaults
to hours and displays the result as a fraction of hours (see the
third formula in the example above).
Negative duration values can be manipulated as well, and integers are considered as seconds in addition and subtraction.
To assign a formula to a particular field, type it directly into the field, preceded by ‘:=’, for example ‘vsum(@II..III)’. When you press TAB or RET or C-c C-c with point still in the field, the formula is stored as the formula for this field, evaluated, and the current field is replaced with the result.
Formulas are stored in a special ‘TBLFM’ keyword located directly below the table. If you type the equation in the fourth field of the third data line in the table, the formula looks like ‘@3$4=$1+$2’. When inserting/deleting/swapping column and rows with the appropriate commands, absolute references (but not relative ones) in stored formulas are modified in order to still reference the same field. To avoid this from happening, in particular in range references, anchor ranges at the table borders (using ‘@<’, ‘@>’, ‘$<’, ‘$>’), or at hlines using the ‘@I’ notation. Automatic adaptation of field references does not happen if you edit the table structure with normal editing commands—you must fix the formulas yourself.
Instead of typing an equation into the field, you may also use the following command
org-table-eval-formula) ¶Install a new formula for the current field. The command prompts for a formula with default taken from the ‘TBLFM’ keyword, applies it to the current field, and stores it.
The left-hand side of a formula can also be a special expression in order to assign the formula to a number of different fields. There is no keyboard shortcut to enter such range formulas. To add them, use the formula editor (see Editing and debugging formulas) or edit the ‘TBLFM’ keyword directly.
Column formula, valid for the entire column. This is so common that Org treats these formulas in a special way, see Column formulas.
Row formula, applies to all fields in the specified row. ‘@>=’ means the last row.
Range formula, applies to all fields in the given rectangular range. This can also be used to assign a formula to some but not all fields in a row.
Named field, see Advanced features.
When you assign a formula to a simple column reference like ‘$3=’, the same formula is used in all fields of that column, with the following very convenient exceptions: (i) If the table contains horizontal separator hlines with rows above and below, everything before the first such hline is considered part of the table header and is not modified by column formulas. Therefore, a header is mandatory when you use column formulas and want to add hlines to group rows, like for example to separate a total row at the bottom from the summand rows above. (ii) Fields that already get a value from a field/range formula are left alone by column formulas. These conditions make column formulas very easy to use.
To assign a formula to a column, type it directly into any field in the column, preceded by an equal sign, like ‘=$1+$2’. When you press TAB or RET or C-c C-c with point still in the field, the formula is stored as the formula for the current column, evaluated and the current field replaced with the result. If the field contains only ‘=’, the previously stored formula for this column is used. For each column, Org only remembers the most recently used formula. In the ‘TBLFM’ keyword, column formulas look like ‘$4=$1+$2’. The left-hand side of a column formula cannot be the name of column, it must be the numeric column reference or ‘$>’.
Instead of typing an equation into the field, you may also use the following command:
org-table-eval-formula) ¶Install a new formula for the current column and replace current field with the result of the formula. The command prompts for a formula, with default taken from the ‘TBLFM’ keyword, applies it to the current field and stores it. With a numeric prefix argument, e.g., C-5 C-c =, the command applies it to that many consecutive fields in the current column.
Org has three predefined Emacs Lisp functions for lookups in tables.
Searches for the first element S in list S-LIST for which
(PREDICATE VAL S)
is non-nil; returns the value from the corresponding position in
list R-LIST. The default PREDICATE is
equal. Note that the parameters VAL and S
are passed to PREDICATE in the same order as the
corresponding parameters are in the call to org-lookup-first,
where VAL precedes S-LIST. If
R-LIST is nil, the matching element S of
S-LIST is returned.
Similar to org-lookup-first above, but searches for the last
element for which PREDICATE is non-nil.
Similar to org-lookup-first, but searches for all elements for
which PREDICATE is non-nil, and returns all
corresponding values. This function cannot be used by itself in
a formula, because it returns a list of values. However, powerful
lookups can be built when this function is combined with other Emacs
Lisp functions.
If the ranges used in these functions contain empty fields, the ‘E’ mode for the formula should usually be specified: otherwise empty fields are not included in S-LIST and/or R-LIST which can, for example, result in an incorrect mapping from an element of S-LIST to the corresponding element of R-LIST.
These three functions can be used to implement associative arrays, count matching cells, rank results, group data, etc. For practical examples see this tutorial on Worg.
You can edit individual formulas in the minibuffer or directly in the
field. Org can also prepare a special buffer with all active formulas
of a table. When offering a formula for editing, Org converts
references to the standard format (like ‘B3’ or ‘D&’) if possible. If
you prefer to only work with the internal format (like ‘@3$2’ or
‘$4’), configure the variable org-table-use-standard-references.
org-table-eval-formula) ¶Edit the formula associated with the current column/field in the minibuffer. See Column formulas, and Field and range formulas.
org-table-eval-formula) ¶Re-insert the active formula (either a field formula, or a column formula) into the current field, so that you can edit it directly in the field. The advantage over editing in the minibuffer is that you can use the command C-c ?.
org-table-field-info) ¶While editing a formula in a table field, highlight the field(s) referenced by the reference at point position in the formula.
org-table-toggle-coordinate-overlays) ¶Toggle the display of row and column numbers for a table, using overlays. These are updated each time the table is aligned; you can force it with C-c C-c.
org-table-toggle-formula-debugger) ¶Toggle the formula debugger on and off. See below.
org-table-edit-formulas) ¶Edit all formulas for the current table in a special buffer, where the formulas are displayed one per line. If the current field has an active formula, point in the formula editor marks it. While inside the special buffer, Org automatically highlights any field or range reference at point position. You may edit, remove and add formulas, and use the following commands:
org-table-fedit-finish) ¶Exit the formula editor and store the modified formulas. With C-u prefix, also apply the new formulas to the entire table.
org-table-fedit-abort) ¶Exit the formula editor without installing changes.
org-table-fedit-toggle-ref-type) ¶Toggle all references in the formula editor between standard (like ‘B3’) and internal (like ‘@3$2’).
org-table-fedit-lisp-indent) ¶Pretty-print or indent Lisp formula at point. When in a line containing a Lisp formula, format the formula according to Emacs Lisp rules. Another TAB collapses the formula back again. In the open formula, TAB re-indents just like in Emacs Lisp mode.
lisp-complete-symbol) ¶Complete Lisp symbols, just like in Emacs Lisp mode.
Shift the reference at point. For example, if the reference is ‘B3’ and you press S-RIGHT, it becomes ‘C3’. This also works for relative references and for hline references.
org-table-fedit-line-up) ¶Move the test line for column formulas up in the Org buffer.
org-table-fedit-line-down) ¶Move the test line for column formulas down in the Org buffer.
org-table-fedit-scroll-up) ¶Scroll up the window displaying the table.
org-table-fedit-scroll-down) ¶Scroll down the window displaying the table.
Turn the coordinate grid in the table on and off.
Making a table field blank does not remove the formula associated with the field, because that is stored in a different line—the ‘TBLFM’ keyword line. During the next recalculation, the field will be filled again. To remove a formula from a field, you have to give an empty reply when prompted for the formula, or to edit the ‘TBLFM’ keyword.
You may edit the ‘TBLFM’ keyword directly and re-apply the changed equations with C-c C-c in that line or with the normal recalculation commands in the table.
You may apply the formula temporarily. This is useful when you want to switch the formula applied to the table. Place multiple ‘TBLFM’ keywords right after the table, and then press C-c C-c on the formula to apply. Here is an example:
| x | y | |---+---| | 1 | | | 2 | | #+TBLFM: $2=$1*1 #+TBLFM: $2=$1*2
Pressing C-c C-c in the line of ‘#+TBLFM: $2=$1*2’ yields:
| x | y | |---+---| | 1 | 2 | | 2 | 4 | #+TBLFM: $2=$1*1 #+TBLFM: $2=$1*2
If you recalculate this table, with C-u C-c *, for example, you get the following result from applying only the first ‘TBLFM’ keyword.
| x | y | |---+---| | 1 | 1 | | 2 | 2 | #+TBLFM: $2=$1*1 #+TBLFM: $2=$1*2
When the evaluation of a formula leads to an error, the field content becomes the string ‘#ERROR’. If you want to see what is going on during variable substitution and calculation in order to find a bug, turn on formula debugging in the Tbl menu and repeat the calculation, for example by pressing C-u C-u C-c = RET in a field. Detailed information is displayed.
Recalculation of a table is normally not automatic, but needs to be triggered by a command. To make recalculation at least semi-automatic, see Advanced features.
In order to recalculate a line of a table or the entire table, use the following commands:
org-table-recalculate) ¶Recalculate the current row by first applying the stored column formulas from left to right, and all field/range formulas in the current row.
Recompute the entire table, line by line. Any lines before the first hline are left alone, assuming that these are part of the table header.
org-table-iterate) ¶Iterate the table by recomputing it until no further changes occur. This may be necessary if some computed fields use the value of other fields that are computed later in the calculation sequence.
Recompute all tables in the current buffer.
Iterate all tables in the current buffer, in order to converge table-to-table dependencies.
If you want the recalculation of fields to happen automatically, or if you want to be able to assign names23 to fields and columns, you need to reserve the first column of the table for special marking characters.
org-table-rotate-recalc-marks) ¶Rotate the calculation mark in first column through the states ‘#’, ‘*’, ‘!’, ‘$’. When there is an active region, change all marks in the region.
Here is an example of a table that collects exam results of students and makes use of these features:
|---+---------+--------+--------+--------+-------+------| | | Student | Prob 1 | Prob 2 | Prob 3 | Total | Note | |---+---------+--------+--------+--------+-------+------| | ! | | P1 | P2 | P3 | Tot | | | # | Maximum | 10 | 15 | 25 | 50 | 10.0 | | ^ | | m1 | m2 | m3 | mt | | |---+---------+--------+--------+--------+-------+------| | # | Peter | 10 | 8 | 23 | 41 | 8.2 | | # | Sam | 2 | 4 | 3 | 9 | 1.8 | |---+---------+--------+--------+--------+-------+------| | | Average | | | | 25.0 | | | ^ | | | | | at | | | $ | max=50 | | | | | | |---+---------+--------+--------+--------+-------+------| #+TBLFM: $6=vsum($P1..$P3)::$7=10*$Tot/$max;%.1f::$at=vmean(@-II..@-I);%.1f
Important: Please note that for these special tables, recalculating the table with C-u C-c * only affects rows that are marked ‘#’ or ‘*’, and fields that have a formula assigned to the field itself. The column formulas are not applied in rows with empty first field.
The marking characters have the following meaning:
The fields in this line define names for the columns, so that you may refer to a column as ‘$Tot’ instead of ‘$6’.
This row defines names for the fields above the row. With such a definition, any formula in the table may use ‘$m1’ to refer to the value ‘10’. Also, if you assign a formula to a names field, it is stored as ‘$name = ...’.
Similar to ‘^’, but defines names for the fields in the row below.
Fields in this row can define parameters for formulas. For example, if a field in a ‘$’ row contains ‘max=50’, then formulas in this table can refer to the value 50 using ‘$max’. Parameters work exactly like constants, only that they can be defined on a per-table basis.
Fields in this row are automatically recalculated when pressing TAB or RET or S-TAB in this row. Also, this row is selected for a global recalculation with C-u C-c *. Unmarked lines are left alone by this command.
Selects this line for global recalculation with C-u C-c *, but not for automatic recalculation. Use this when automatic recalculation slows down editing too much.
Do not export this line. Useful for lines that contain the narrowing ‘<N>’ markers or column group markers.
Finally, just to whet your appetite for what can be done with the fantastic Calc package, here is a table that computes the Taylor series of degree n at location x for a couple of functions.
|---+-------------+---+-----+--------------------------------------| | | Func | n | x | Result | |---+-------------+---+-----+--------------------------------------| | # | exp(x) | 1 | x | 1 + x | | # | exp(x) | 2 | x | 1 + x + x^2 / 2 | | # | exp(x) | 3 | x | 1 + x + x^2 / 2 + x^3 / 6 | | # | x^2+sqrt(x) | 2 | x=0 | x*(0.5 / 0) + x^2 (2 - 0.25 / 0) / 2 | | # | x^2+sqrt(x) | 2 | x=1 | 2 + 2.5 x - 2.5 + 0.875 (x - 1)^2 | | * | tan(x) | 3 | x | 0.0175 x + 1.77e-6 x^3 | |---+-------------+---+-----+--------------------------------------| #+TBLFM: $5=taylor($2,$4,$3);n3
Org Plot can produce graphs of information stored in Org tables, either graphically or in ASCII art.
Org Plot can produce 2D and 3D graphs of information stored in Org tables using Gnuplot and Gnuplot mode. To see this in action, ensure that you have both Gnuplot and Gnuplot mode installed on your system, then call C-c " g or M-x org-plot/gnuplot on the following table.
#+PLOT: title:"Citas" ind:1 deps:(3) type:2d with:histograms set:"yrange [0:]" | Sede | Max cites | H-index | |-----------+-----------+---------| | Chile | 257.72 | 21.39 | | Leeds | 165.77 | 19.68 | | Sao Paolo | 71.00 | 11.50 | | Stockholm | 134.19 | 14.33 | | Morelia | 257.56 | 17.67 |
Org Plot supports a range of plot types, and provides the ability to add more. For example, a radar plot can be generated like so:
#+PLOT: title:"An evaluation of plaintext document formats" transpose:yes type:radar min:0 max:4 | Format | Fine-grained-control | Initial Effort | Syntax simplicity | Editor Support | Integrations | Ease-of-referencing | Versatility | |-------------------+----------------------+----------------+-------------------+----------------+--------------+---------------------+-------------| | Word | 2 | 4 | 4 | 2 | 3 | 2 | 2 | | LaTeX | 4 | 1 | 1 | 3 | 2 | 4 | 3 | | Org Mode | 4 | 2 | 3.5 | 1 | 4 | 4 | 4 | | Markdown | 1 | 3 | 3 | 4 | 3 | 3 | 1 | | Markdown + Pandoc | 2.5 | 2.5 | 2.5 | 3 | 3 | 3 | 2 |
Notice that Org Plot is smart enough to apply the table’s headers as labels. Further control over the labels, type, content, and appearance of plots can be exercised through the ‘PLOT’ keyword preceding a table. See below for a complete list of Org Plot options. For more information and examples see the Org Plot tutorial.
Specify any Gnuplot option to be set when graphing.
Specify the title of the plot.
Specify which column of the table to use as the ‘x’ axis.
Specify which column of the table to use as the ‘x’ axis as a time value.
Specify the columns to graph as a Lisp style list, surrounded by parentheses and separated by spaces for example ‘dep:(3 4)’ to graph the third and fourth columns. Defaults to graphing all other columns aside from the ‘ind’ column.
When ‘y’, ‘yes’, or ‘t’ attempt to transpose the table data before plotting. Also recognizes the shorthand option ‘trans’.
Specify the type of the plot, by default one of ‘2d’, ‘3d’, ‘radar’, or ‘grid’.
Available types can be customized with org-plot/preset-plot-types.
Specify a ‘with’ option to be inserted for every column being plotted, e.g., ‘lines’, ‘points’, ‘boxes’, ‘impulses’. Defaults to ‘lines’.
If you want to plot to a file, specify ‘"path/to/desired/output-file"’.
List of labels to be used for the ‘deps’. Defaults to the column headers if they exist.
Specify an entire line to be inserted in the Gnuplot script.
When plotting ‘3d’ or ‘grid’ types, set this to ‘t’ to graph a flat mapping rather than a ‘3d’ slope.
Provides a minimum axis value that may be used by a plot type. Implicitly assumes the ‘y’ axis is being referred to. You can explicitly provide a value for the ‘x’ or ‘y’ axis with ‘xmin’ and ‘ymin’.
Provides a maximum axis value that may be used by a plot type. Implicitly assumes the ‘y’ axis is being referred to. You can explicitly provide a value for the ‘x’ or ‘y’ axis with ‘xmax’ and ‘ymax’.
Provides a desired number of axis ticks to display, that may be used
by a plot type. If none is given a plot type that requires ticks
will use org--plot/sensible-tick-num to try to determine a good
value.
Specify format of Org mode timestamps as they will be parsed by Gnuplot. Defaults to ‘%Y-%m-%d-%H:%M:%S’.
If you want total control, you can specify a script file—place the file name between double-quotes—which will be used to plot. Before plotting, every instance of ‘$datafile’ in the specified script will be replaced with the path to the generated data file. Note: even if you set this option, you may still want to specify the plot type, as that can impact the content of the data file.
While point is on a column, typing C-c " a or M-x orgtbl-ascii-plot create a new column containing an ASCII-art bars plot. The plot is implemented through a regular column formula. When the source column changes, the bar plot may be updated by refreshing the table, for example typing C-u C-c *.
| Sede | Max cites | | |---------------+-----------+--------------| | Chile | 257.72 | WWWWWWWWWWWW | | Leeds | 165.77 | WWWWWWWh | | Sao Paolo | 71.00 | WWW; | | Stockholm | 134.19 | WWWWWW: | | Morelia | 257.56 | WWWWWWWWWWWH | | Rochefourchat | 0.00 | | #+TBLFM: $3='(orgtbl-ascii-draw $2 0.0 257.72 12)
The formula is an Elisp call.
Draw an ASCII bar in a table.
VALUE is the value to plot.
MIN is the value displayed as an empty bar. MAX is the value filling all the WIDTH. Source values outside this range are displayed as ‘too small’ or ‘too large’.
WIDTH is the number of characters of the bar plot. It defaults to ‘12’.
Like HTML, Org provides support for links inside a file, external links to other files, Usenet articles, emails, and much more.
Org recognizes plain URIs, possibly wrapped within angle brackets24, and activates them as clickable links.
The general link format, however, looks like this:
[[LINK][DESCRIPTION]]
or alternatively
[[LINK]]
Some ‘\’, ‘[’ and ‘]’ characters in the LINK part need to be “escaped”, i.e., preceded by another ‘\’ character. More specifically, only the following characters must be escaped:
Functions inserting links (see Handling Links) properly escape
ambiguous characters. You only need to bother about the rules above
when inserting directly, or yanking, a URI within square brackets.
When in doubt, you may use the function org-link-escape, which turns
a link string into its escaped form.
Once a link in the buffer is complete, with all brackets present, Org
changes the display so that ‘DESCRIPTION’ is displayed instead of
‘[[LINK][DESCRIPTION]]’ and ‘LINK’ is displayed instead of ‘[[LINK]]’.
Links are highlighted in the org-link face, which, by default, is an
underlined face.
You can directly edit the visible part of a link. This can be either the LINK part, if there is no description, or the DESCRIPTION part otherwise. To also edit the invisible LINK part, use C-c C-l with point on the link (see Handling Links).
If you place point at the beginning or just behind the end of the
displayed text and press BS, you remove
the—invisible—bracket at that location25. This makes the link
incomplete and the internals are again displayed as plain text.
Inserting the missing bracket hides the link internals again. To show
the internal structure of all links, use the menu: Org →
Hyperlinks → Literal links, customize org-link-descriptive, or use
the ‘literallinks’ startup option.
A link that does not look like a URL—i.e., does not start with a known scheme or a file name—refers to the current document. You can follow it with C-c C-o when point is on the link, or with a mouse click (see Handling Links).
Org provides several refinements to internal navigation within a document. Most notably, a construct like ‘[[#my-custom-id]]’ specifically targets the entry with the ‘CUSTOM_ID’ property set to ‘my-custom-id’. Also, an internal link looking like ‘[[*Some section]]’ points to a headline with the name ‘Some section’26.
When the link does not belong to any of the cases above, Org looks for a dedicated target: the same string in double angular brackets, like ‘<<My Target>>’.
If no dedicated target exists, the link tries to match the exact name of an element within the buffer. Naming is done, unsurprisingly, with the ‘NAME’ keyword, which has to be put in the line before the element it refers to, as in the following example
#+NAME: My Target | a | table | |----+------------| | of | four cells |
Ultimately, if none of the above succeeds, Org searches for a headline
that is exactly the link text but may also include a TODO keyword and
tags, or initiates a plain text search, according to the value of
org-link-search-must-match-exact-headline.
Note that you must make sure custom IDs, dedicated targets, and names are unique throughout the document. Org provides a linter to assist you in the process, if needed. See Org Syntax.
During export, internal links are used to mark objects and assign them a number. Marked objects are then referenced by links pointing to them. In particular, links without a description appear as the number assigned to the marked object27. In the following excerpt from an Org buffer
1. one item 2. <<target>>another item Here we refer to item [[target]].
The last sentence will appear as ‘Here we refer to item 2’ when exported.
In non-Org files, the search looks for the words in the link text. In the above example, the search would be for ‘target’.
Following a link pushes a mark onto Org’s own mark ring. You can return to the previous position with C-c &. Using this command several times in direct succession goes back to positions recorded earlier.
Org can automatically turn any occurrences of certain target names in normal text into a link. So without explicitly creating a link, the text connects to the target radioing its position. Radio targets are enclosed by triple angular brackets. For example, a target ‘<<<My Target>>>’ causes each occurrence of ‘my target’ in normal text to become activated as a link. The Org file is scanned automatically for radio targets only when the file is first loaded into Emacs. To update the target list during editing, press C-c C-c with point on or at a target.
Org supports links to files, websites, Usenet and email messages, BBDB database entries and links to both IRC conversations and their logs. External links are URL-like locators. They start with a short identifying string followed by a colon. There can be no space after the colon.
Here is the full set of built-in link types:
File links. File name may be remote, absolute, or relative.
As a special case, the “file” prefix may be omitted if the file name is complete, e.g., it starts with ‘./’ or ‘/’.
Same as file links but for files and folders attached to the current node (see Attachments). Attachment links are intended to behave exactly as file links but for files relative to the attachment directory.
Link to a BBDB record, with possible regexp completion.
Link to a document opened with DocView mode. You may specify a page number.
Link to an electronic resource, through its handle.
Execute an Elisp command upon activation.
Link to messages or folders from a given Emacs MUA.
Display documentation of a symbol in ‘*Help*’ buffer.
Web links.
Link to a specific headline by its ID property, in an Org file.
Link to an Info manual, or to a specific node.
Link to an IRC channel.
Link to message composition.
Usenet links.
Execute a shell command upon activation.
Link to short documentation summary for an Emacs Lisp function group. 28
For more information, see Name Help and Documentation Groups.
For ‘file:’ and ‘id:’ links, you can additionally specify a line number, or a text search string, separated by ‘::’. In Org files, you may link to a headline name, a custom ID, or a code reference instead.
The following table illustrates the link types above, along with their options:
| Link Type | Example |
|---|---|
| http | ‘http://orgmode.org/’ |
| https | ‘https://orgmode.org/’ |
| doi | ‘doi:10.1000/182’ |
| file | ‘file:/home/dominik/images/jupiter.jpg’ |
| ‘/home/dominik/images/jupiter.jpg’ (same as above) | |
| ‘file:papers/last.pdf’ | |
| ‘./papers/last.pdf’ (same as above) | |
| ‘file:/ssh:me@some.where:papers/last.pdf’ (remote) | |
| ‘/ssh:me@some.where:papers/last.pdf’ (same as above) | |
| ‘file:sometextfile::NNN’ (jump to line number) | |
| ‘file:projects.org’ | |
| ‘file:projects.org::some words’ (text search)29 | |
| ‘file:projects.org::*task title’ (headline search) | |
| ‘file:projects.org::#custom-id’ (headline search) | |
| attachment | ‘attachment:projects.org’ |
| ‘attachment:projects.org::some words’ (text search) | |
| docview | ‘docview:papers/last.pdf::NNN’ |
| id | ‘id:B7423F4D-2E8A-471B-8810-C40F074717E9’ |
| ‘id:B7423F4D-2E8A-471B-8810-C40F074717E9::*task’ (headline search) | |
| news | ‘news:comp.emacs’ |
| mailto | ‘mailto:adent@galaxy.net’ |
| mhe | ‘mhe:folder’ (folder link) |
| ‘mhe:folder#id’ (message link) | |
| rmail | ‘rmail:folder’ (folder link) |
| ‘rmail:folder#id’ (message link) | |
| gnus | ‘gnus:group’ (group link) |
| ‘gnus:group#id’ (article link) | |
| bbdb | ‘bbdb:R.*Stallman’ (record with regexp) |
| irc | ‘irc:/irc.com/#emacs/bob’ |
| help | ‘help:org-store-link’ |
| info | ‘info:org#External links’ |
| shortdoc | ‘shortdoc:text-properties’ |
| ‘shortdoc:text-properties::#get-pos-property’ | |
| shell | ‘shell:ls *.org’ (synchronous), ‘shell:inkscape&’ (asynchronous) |
| elisp | ‘elisp:(find-file "Elisp.org")’ (Elisp form to evaluate) |
| ‘elisp:org-agenda’ (interactive Elisp command) |
On top of these built-in link types, additional ones are available through the ‘org-contrib’ repository (see Installation). For example, these links to VM or Wanderlust messages are available when you load the corresponding libraries from the ‘org-contrib