This manual is for Org-mode (version 4.67).
Copyright © 2004, 2005, 2006, 2007, 2008 Free Software Foundation
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 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 freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development.”
--- The Detailed Node Listing ---
Introduction
Document Structure
Archiving
Tables
The spreadsheet
Hyperlinks
Internal links
Remember
TODO items
Extended use of TODO keywords
Timestamps
Creating timestamps
Progress Logging
Tags
Agenda Views
The built-in agenda views
Presentation and sorting
Custom agenda views
Embedded LaTeX
Exporting
HTML export
Text interpretation by the exporter
Publishing
Configuration
Sample configuration
Miscellaneous
Interaction with other packages
Extensions, Hooks and Hacking
Tables in arbitrary syntax
Org-mode is a mode for keeping notes, maintaining ToDo lists, and doing project planning with a fast and effective plain-text system.
Org-mode develops organizational tasks around NOTES files that contain lists or information about projects as plain text. 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 to work with the tree. Tables are easily created with a built-in table editor. Org-mode supports ToDo items, deadlines, time stamps, and scheduling. It dynamically compiles entries into an agenda that utilizes and smoothly integrates much of the Emacs calendar and diary. Plain text URL-like links connect to websites, emails, Usenet messages, BBDB entries, and any files related to the projects. For printing and sharing of notes, an Org-mode file can be exported as a structured ASCII file, as HTML, or (todo and agenda items only) as an iCalendar file. It can also serve as a publishing tool for a set of linked webpages.
An important design aspect that distinguishes Org-mode from for example Planner/Muse is that it encourages to store every piece of information only once. In Planner, you have project pages, day pages and possibly other files, duplicating some information such as tasks. In Org-mode, you only have notes files. In your notes you mark entries as tasks, label them with tags and timestamps. All necessary lists like a schedule for the day, the agenda for a meeting, tasks lists selected by tags etc are created dynamically when you need them.
Org-mode 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 you need it. Org-mode can be used on different levels and in different ways, for example as:
• outline extension with visibility cycling and structure editing • ASCII system and table editor for taking structured notes • ASCII table editor with spreadsheet-like capabilities • TODO list editor • full agenda and planner with deadlines and work scheduling • environment to implement David Allen's GTD system • simple hypertext system, with HTML export • publishing tool to create a set of interlinked webpages
Org-mode's automatic, context sensitive table editor with spreadsheet capabilities can be integrated into any major mode by activating the minor Orgtbl-mode. Using a translation step, it can be used to maintain tables in arbitray file types, for example in LaTeX.
There is a website for Org-mode which provides links to the newest version of Org-mode, as well as additional information, frequently asked questions (FAQ), links to tutorials etc. This page is located at http://orgmode.org/.
Important: If Org-mode is part of the Emacs distribution or an XEmacs package, please skip this section and go directly to Activation.
If you have downloaded Org-mode from the Web, you must take the following steps to install it: Go into the Org-mode distribution directory and edit the top section of the file Makefile. You must set the name of the Emacs binary (likely either emacs or xemacs), and the paths to the directories where local Lisp and Info files are kept. If you don't have access to the system-wide directories, create your own two directories for these files, enter them into the Makefile, and make sure Emacs finds the Lisp files by adding the following line to .emacs:
(setq load-path (cons "~/path/to/lispdir" load-path))
XEmacs users now need to install the file noutline.el from the xemacs subdirectory of the Org-mode distribution. Use the command:
make install-noutline
Now byte-compile and install the Lisp files with the shell commands:
make
make install
If you want to install the info documentation, use this command:
make install-info
Then add to .emacs:
;; This line only if org-mode is not part of the X/Emacs distribution.
(require 'org-install)
Add the following lines to your .emacs file. The last two lines define global keys for the commands org-store-link and org-agenda - please choose suitable keys yourself.
;; The following lines are always needed. Choose your own keys.
(add-to-list 'auto-mode-alist '("\\.org$" . org-mode))
(define-key global-map "\C-cl" 'org-store-link)
(define-key global-map "\C-ca" 'org-agenda)
Furthermore, you must activate font-lock-mode in org-mode
buffers, because significant functionality depends on font-locking being
active. You can do this with either one of the following two lines
(XEmacs user must use the second option):
(global-font-lock-mode 1) ; for all buffers
(add-hook 'org-mode-hook 'turn-on-font-lock) ; org-mode buffers only
With this setup, all files with extension `.org' will be put into Org-mode. As an alternative, make the first line of a file look like this:
MY PROJECTS -*- mode: org; -*-
which will select Org-mode for this buffer no matter what
the file's name is. See also the variable
org-insert-mode-line-in-empty-file.
If you find problems with Org-mode, or if you have questions, remarks, or ideas about it, please contact the maintainer Carsten Dominik at dominik at science dot uva dot nl.
For bug reports, please provide as much information as possible, including the version information of Emacs (C-h v emacs-version <RET>) and Org-mode (C-h v org-version <RET>), as well as the Org-mode related setup in .emacs. If an error occurs, a backtrace can be very useful (see below on how to create one). Often a small example file helps, along with clear information about:
If working with Org-mode produces an error with a message you don't 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:
emacs -l /path/to/org.el
Options menu and select Enter Debugger on Error
(XEmacs has this option in the Troubleshooting sub-menu).
Org-mode is based on outline mode and provides flexible commands to edit the structure of the document.
Org-mode is implemented on top of outline-mode. Outlines allow to organize a document in a hierarchical structure, which (at least for me) is the best representation of notes and thoughts. Overview over this structure is achieved by folding (hiding) large parts of the document to show only the general document structure and the parts currently being worked on. Org-mode greatly simplifies the use of outlines by compressing the entire show/hide functionality into a single command org-cycle, which is bound to the <TAB> key.
Headlines define the structure of an outline tree. The headlines in Org-mode start with one or more stars, on the left margin. For example:
* Top level headline
** Second level
*** 3rd level
some text
*** 3rd level
more text
* Another top level headline
Some people find the many stars too noisy and would prefer an outline that has whitespace followed by a single star as headline starters. Clean view describes a setup to realize this.
Outlines make it possible to hide parts of the text in the buffer. Org-mode uses just two commands, bound to <TAB> and S-<TAB> to change the visibility in the buffer.
,-> FOLDED -> CHILDREN -> SUBTREE --.
'-----------------------------------'
The cursor must be on a headline for this to work1. When the cursor is at the beginning of the buffer and the first line is not a headline, then <TAB> actually runs global cycling (see below)2. Also when called with a prefix argument (C-u <TAB>), global cycling is invoked.
,-> OVERVIEW -> CONTENTS -> SHOW ALL --.
'--------------------------------------'
When S-<TAB> is called with a numerical prefix N, the CONTENTS view up to headlines of level N will be shown. Note that inside tables, S-<TAB> jumps to the previous field.
When Emacs first visits an Org-mode file, the global state is set to
OVERVIEW, i.e. only the top level headlines are visible. 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
The following commands jump to other headlines in the buffer.
When there is an active region (transient-mark-mode), promotion and demotion work on all headlines in the region. To select a region of headlines, it is best to place both point and mark at the beginning of a line, mark at the beginning of the first headline, and point at the line just after the last headline to change. Note that when the cursor is inside a table (see Tables), the Meta-Cursor keys have different functionality.
When a project represented by a (sub)tree is finished, you may want to move the tree out of the way and to stop it from contributing to the agenda. Org-mode knows two ways of archiving. You can mark a tree with the ARCHIVE tag, or you can move an entire (sub)tree to a different location.
A headline that is marked with the ARCHIVE tag (see Tags) stays at its location in the outline tree, but behaves in the following way:
org-cycle-open-archived-trees. Also normal outline commands like
show-all will open archived subtrees.
org-sparse-tree-open-archived-trees.
org-agenda-skip-archived-trees.
org-export-with-archived-trees.
The following commands help managing the ARCHIVE tag:
Once an entire project is finished, you may want to move it to a different location, either in the current file, or even in a different file, the archive file.
org-archive-location.
The default archive location is a file in the same directory as the
current file, with the name derived by appending _archive to the
current file name. For information and examples on how to change this,
see the documentation string of the variable
org-archive-location. There is also an in-buffer option for
setting this variable, for example
#+ARCHIVE: %s_done::
You may have several such lines in the buffer, they will then be valid for the entries following the line (the first will also apply to any text before it).
An important feature of Org-mode is the ability to construct sparse trees for selected information in an outline tree. A sparse tree means that the entire document is folded as much as possible, but the selected information is made visible along with the headline structure above it4. Just try it out and you will see immediately how it works.
Org-mode contains several commands creating such trees. The most basic one is org-occur:
org-agenda-custom-commands to define fast
keyboard access to specific sparse trees. These commands will then be
accessible through the agenda dispatcher (see Agenda dispatcher).
For example:
(setq org-agenda-custom-commands
'(("f" occur-tree "FIXME")))
will define the key C-c a f as a shortcut for creating a sparse tree matching the string `FIXME'.
Other commands use sparse trees as well. For example C-c C-v creates a sparse TODO tree (see TODO basics).
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 5.
Or you can use the command C-c C-e 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-mode supports editing such lists, and the HTML exporter (see Exporting) does parse and format them.
Org-mode knows ordered and unordered lists. Unordered list items start with `-', `+', or `*'6 as bullets. Ordered list items start with `1.' or `1)'. 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. Indentation also determines the end of a list item. It ends before the next line that is indented like the bullet/number, or less. For example:
** Lord of the Rings
My favorite scenes are (in this order)
1. The attack of the Rohirrim
2. Eowyns 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.
But in the end, not individual scenes matter but the film as a whole.
Org-mode supports these lists by tuning filling and wrapping commands to deal with them correctly7.
The following commands act on items when the cursor is in the first line of an item (the line with the bullet or number).
org-cycle-include-plain-lists. 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.
Org-mode has a very fast and intuitive table editor built-in. Spreadsheet-like calculations are supported in connection with the Emacs calc package.
Org-mode makes it easy to format tables in plain ASCII. Any line with `|' as the first non-white character is considered part of a table. `|' is also the column separator. 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> or <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. Any line starting with `|-' is considered as a horizontal separator line and will be expanded on the next 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.
When typing text into a field, Org-mode treats <DEL>,
<Backspace>, and all character keys in a special way, so that
inserting and deleting avoids shifting other fields. Also, when
typing immediately after the cursor 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 variables
org-enable-table-editor and org-table-auto-blank-field.
org-table-copy-increment, integer field values will be
incremented during copy. This key is also used by CUA-mode
(see Cooperation).
If you don't like the automatic table editor because it gets in your way on lines which you would like to start with `|', you can turn it off with
(setq org-enable-table-editor nil)
Then the only table command that still works is C-c C-c to do a manual re-align.
The width of columns is automatically determined by the table editor. Sometimes a single field or a few fields need to carry more text, leading to inconveniently wide columns. To limit8 the width of a column, one field anywhere in the column may contain just the string `<N>' where `N' is an integer specifying the width of the column in characters. The next re-align will then set the width of this column to no more than this value.
|---+------------------------------| |---+--------|
| | | | | <6> |
| 1 | one | | 1 | one |
| 2 | two | ----\ | 2 | two |
| 3 | This is a long chunk of text | ----/ | 3 | This=> |
| 4 | four | | 4 | four |
|---+------------------------------| |---+--------|
Fields that are wider become clipped and end in the string `=>'. Note that the full text is still in the buffer, it is only invisible. To see the full text, hold the mouse over the field - a tooltip window will show the full content. To edit such a field, use the command C-c ` (that is C-c followed by the backquote). This will open a new window with the full field. Edit it and finish with C-c C-c.
When visiting a file containing a table with narrowed columns, the
necessary character hiding has not yet happened, and the table needs to
be aligned before it looks nice. Setting the option
org-startup-align-all-tables will realign all tables in a file
upon visiting, but also slow down startup. You can also set this option
on a per-file basis with:
#+STARTUP: align
#+STARTUP: noalign
If you like the intuitive way the Org-mode 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 mail mode, use
(add-hook 'mail-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 capabulities. 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.
To compute fields in the table from other fields, formulas must reference other fields or ranges. In Org-mode, 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.
Formulas can reference the value of another field with the operator
@row$column
Column references can be absolute like `1', `2',...`N', or relative to the current column like `+1' or `-2'.
The row specification only counts data lines and ignores horizontal separator lines (hlines). You can use absolute row numbers `1'...`N', and row numbers relative to the current row like `+3' or `-1'. Or 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. Relative row numbers like `-3' will not cross hlines if the current line is too close to the hline. Instead, the value directly at the hline is used.
`0' refers to the current row and column. Also, if you omit either the column or the row part of the reference, the current row/column is implied.
Org-mode's references with positive numbers correspond to fixed
references in other spreadsheet programs. For example, @3$28
corresponds to $AB$3. Org-mode's references with negative
numbers behave similar to non-fixed references in other spreadsheet
programs, because when the same formula is used in several fields,
different fields are referenced each time.
Here are a few examples:
@2$3 2nd row, 3rd column $5 column 5 in the current row @2 current column, row 2 @-1$-3 the field one row up, three columns to the left @-I$2 field just under hline above current row, column 2
You may reference a rectangular range of fields by specifying two field
references connected by two dots `..'. 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 under Advanced) @2$1..@4$3 6 fields between these two fields. @-1$-2..@-1 3 numbers from the column to the left, 2 up to current row
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 (but see the `E' mode switch below). If there are no non-empty fields, `[0]' is returned to avoid syntax errors in formulas.
`$name' is interpreted as the name of a column, parameter or
constant. Constants are defined globally through the variable
org-table-formula-constants. 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 kilometers. Column names and
parameters can be specified in special table lines. These are
described below, see Advanced features.
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 calc-eval),
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-mode uses the standard calc modes (precision
12, angular units degrees, fraction and symbolic modes off. The display
format, however, has been changed to (float 5) to keep tables
compact. The default settings can be configured using the variable
org-calc-default-modes.
p20 switch the internal precision to 20 digits n3 s3 e2 f4 normal, scientific, engineering, or fixed display format D R angle modes: degrees, radians F S fraction and symbolic modes N interpret all fields as numbers, use 0 for non-numbers T force text interpretation E keep empty fields in ranges
In addition, you may provide a printf format specifier to
reformat the final result. 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 $;%.1f Reformat current cell to 1 decimal ($3-32)*5/9 Degrees F -> C conversion $c/$1/$cm Hz -> cm conversion, using constants.el tan($1);Dp3s1 Compute in degrees, precision 3, display SCI 1 sin($1);Dp3%.1e Same, but use printf 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
It is also possible to write a formula in Emacs Lisp; this can be useful for string manipulation and control structures. If a formula starts with a single quote followed by an opening parenthesis, then it is evaluated as a lisp form. The evaluation should return either a string or a number. Just as with calc formulas, you can specify modes and a printf format after a semicolon. A reference will be replaced with a string (in double quotes) containing the field. If you provide the `N' mode switch, all referenced elements will be numbers. Ranges are inserted as space-separated fields, so you can embed them in list or vector syntax. A few examples, note how the `N' mode is used when we do computations in lisp.
Swap the first two characters of the content of column 1 '(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2)) Add columns 1 and 2, equivalent to the Calc's$1+$2'(+ $1 $2);N Compute the sum of columns 1-4, like Calc'svsum($1..$4)'(apply '+ '($1..$4));N
To assign a formula to a particular field, type it directly into the field, preceded by `:=', for example `:=$1+$2'. When you press <TAB> or <RET> or C-c C-c with the cursor still in the field, the formula will be stored as the formula for this field, evaluated, and the current field replaced with the result.
Formulas are stored in a special line starting with `#+TBLFM:' directly below the table. If you typed the equation in the 4th field of the 3rd data line in the table, the formula will look like `@3$2=$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. Of cause this is not true if you edit the table structure with normal editing commands - then you must go and fix equations yourself.
Instead of typing an equation into the field, you may also use the following command
Often in a table, the same formula should be used for all fields in a particular column. Instead of having to copy the formula to all fields in that column, org-mode allows to assign a single formula to an entire column.
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 the cursor still in the field, the formula will be 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-mode will only remember the most recently used formula. In the `TBLFM:' line, column formulas will look like `$4=$1+$2'.
Instead of typing an equation into the field, you may also use the following command:
You can edit individual formulas in the minibuffer or directly in the field. Org-mode can also prepare a special buffer with all active formulas of a table.
Making a table field blank does not remove the formula associated with the field, because that is stored in a different line (the `TBLFM' 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' line.
You may edit the `#+TBLFM' directly and re-apply the changed equations with C-c C-c in that line, or with the normal recalculation commands in the table.
When the evaluation of a formula leads to an error, the field content
becomes the string `#ERROR'. If you would like 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-c = <RET> in a field.
Detailed information will be displayed.
Recalculation of a table is normally not automatic, but needs to be triggered by a command. See Advanced features for a way to make recalculation at least semi-automatically.
In order to recalculate a line of a table or the entire table, use the following commands:
If you want the recalculation of fields to happen automatically, or if you want to be able to assign names to fields and columns, you need to reserve the first column of the table for special marking characters.
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 |
| # | Sara | 6 | 14 | 19 | 39 | 7.8 |
| # | Sam | 2 | 4 | 3 | 9 | 1.8 |
|---+---------+--------+--------+--------+-------+------|
| | Average | | | | 29.7 | |
| ^ | | | | | 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 * will only affect 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:
Finally, just to whet your appetite on 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
(homework: try that with Excel :-)
|---+-------------+---+-----+--------------------------------------|
| | 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
Just like HTML, Org-mode provides links inside a file, and external links to other files, Usenet articles, emails, and much more.
Org-mode will recognize plain URL-like links and activate them as clickable links. The general link format, however, looks like this:
[[link][description]] or alternatively [[link]]
Once a link in the buffer is complete (all brackets present), Org-mode
will change the display so that `description' is displayed instead
of `[[link][description]]' and `link' is displayed instead of
`[[link]]'. Links will be highlighted in the face org-link,
which by default is an underlined face. You can directly edit the
visible part of a link. Note that this can be either the `link'
part (if there is no description) or the `description' part. To
edit also the invisible `link' part, use C-c C-l with the
cursor on the link.
If you place the cursor at the beginning or just behind the end of the
displayed text and press <BACKSPACE>, you will remove the
(invisible) bracket at that location. 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 entry
Org->Hyperlinks->Literal links.
If the link does not look like a URL, it is considered to be internal in the current file. Links such as `[[My Target]]' or `[[My Target][Find my target]]' lead to a text search in the current file. The link can be followed with C-c C-o when the cursor is on the link, or with a mouse click (see Handling links). The preferred match for such a link is a dedicated target: the same string in double angular brackets. Targets may be located anywhere; sometimes it is convenient to put them into a comment line. For example
# <<My Target>>
In HTML export (see HTML export), such targets will become named anchors for direct access through `http' links9.
If no dedicated target exists, Org-mode will search for the words in the link. In the above example the search would be for `my target'. Links starting with a star like `*My Target' restrict the search to headlines. When searching, Org-mode will first try an exact match, but then move on to more and more lenient searches. For example, the link `[[*My Targets]]' will find any of the following:
** My targets
** TODO my targets are bright
** my 20 targets are
To insert a link targeting a headline, in-buffer completion can be used. Just type a star followed by a few optional letters into the buffer and press M-<TAB>. All headlines in the current buffer will be offered as completions. See Handling links, for more commands creating links.
Following a link pushes a mark onto Org-mode'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.
You can configure Org-mode to link any occurrences of certain target names in normal text. 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-mode 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 the cursor on or at a target.
Org-mode supports links to files, websites, Usenet and email messages, and BBDB database entries. 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. The following list shows examples for each link type.
http://orgmode.org/ on the web file:/home/dominik/images/jupiter.jpg file, absolute path file:papers/last.pdf file, relative path news:comp.emacs Usenet link mailto:adent@galaxy.net Mail link vm:folder VM folder link vm:folder#id VM message link vm://myself@some.where.org/folder#id VM on remote machine wl:folder WANDERLUST folder link wl:folder#id WANDERLUST message link mhe:folder MH-E folder link mhe:folder#id MH-E message link rmail:folder RMAIL folder link rmail:folder#id RMAIL message link gnus:group GNUS group link gnus:group#id GNUS article link bbdb:Richard Stallman BBDB link shell:ls *.org A shell command elisp:(find-file-other-frame "Elisp.org") An elisp form to evaluate
A link should be enclosed in double brackets and may contain a descriptive text to be displayed instead of the url (see Link format), for example:
[[http://www.gnu.org/software/emacs/][GNU Emacs]]
If the description is a file name or URL that points to an image, HTML export (see HTML export) will inline the image as a clickable button. If there is no description at all and the link points to an image, that image will be inlined into the exported HTML file.
Org-mode also finds external links in the normal text and activates them as links. If spaces must be part of the link (for example in `bbdb:Richard Stallman'), or if you need to remove ambiguities about the end of the link, enclose them in angular brackets.
Org-mode provides methods to create a link in the correct syntax, to insert it into an org-mode file, and to follow the link.
org-file-apps. If
you want to override the default application and visit the file with
Emacs, use a C-u prefix.
(add-hook 'org-load-hook
(lambda ()
(define-key 'org-mode-map "\C-n" 'org-next-link)
(define-key 'org-mode-map "\C-p" 'org-previous-link)))
Long URLs can be cumbersome to type, and often many similar links are needed in a document. For this you can use link abbreviations. An abbreviated link looks like this
[[linkword:tag][description]]
where the tag is optional. Such abbreviations are resolved according to
the information in the variable org-link-abbrev-alist that
relates the linkwords to replacement text. Here is an example:
(setq org-link-abbrev-alist
'(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=")
("google" . "http://www.google.com/search?q=")
("ads" . "http://adsabs.harvard.edu/cgi-bin/
nph-abs_connect?author=%s&db_key=AST")))
If the replacement text contains the string `%s', it will be replaced with the tag. Otherwise the tag will be appended to the string in order to create the link. You may also specify a function that will be called with the tag as the only argument to create the link.
With the above setting, you could link to a specific bug with
[[bugzilla:129]], search the web for `OrgMode' with
[[google:OrgMode]] and find out what the Org-mode author is
doing besides Emacs hacking with [[ads:Dominik,C]].
If you need special abbreviations just for a single Org-mode buffer, you can define them in the file with
#+LINK: bugzilla http://10.1.2.9/bugzilla/show_bug.cgi?id=
#+LINK: google http://www.google.com/search?q=%s
In-buffer completion see Completion can be used after `[' to complete link abbreviations.
File links can contain additional information to make Emacs jump to a particular location in the file when following a link. This can be a line number or a search option after a double12 colon. For example, when the command C-c l creates a link (see Handling links) to a file, it encodes the words in the current line as a search string that can be used to find this line back later when following the link with C-c C-o.
Here is the syntax of the different ways to attach a search to a file link, together with an explan