Org-mode - summary

1 Emphasis and Monospace

You can make words ‘*bold*’, ‘/italic/’, ‘_underlined_’, ‘=verbatim=’ and ‘~code~’, and, if you must, ‘+strike-through+’. Text in the code and verbatim string is not processed for Org mode specific syntax; it is exported verbatim.

To turn off fontification for marked up text, you can set org-fontify-emphasized-text to nil. To narrow down the list of available markup syntax, you can customize org-emphasis-alist.


2 Activation

The four Org commands org-store-link', org-capture', org-agenda', and org-iswitchb' should be accessible through global keys (i.e., anywhere in Emacs, not just in Org buffers). Here are suggested bindings for these keys, please modify the keys to your own liking.

(global-set-key "\C-cl" 'org-store-link)
(global-set-key "\C-cc" 'org-capture)
(global-set-key "\C-ca" 'org-agenda)
(global-set-key "\C-cb" 'org-iswitchb)


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; -*-


3 Document Structure

Global and local cycling

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.

<TAB>'     (org-cycle')
_Subtree cycling_: Rotate current subtree among the states

,-> FOLDED -> CHILDREN -> SUBTREE --.
'-----------------------------------'

The cursor must be on a headline for this to work(1).  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.

S-<TAB>'     (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, the
CONTENTS view up to headlines of level N will be shown.  Note that
inside tables, S-<TAB>' jumps to the previous field.

C-c C-x v'     (org-copy-visible')
Copy the visible text in the region into the kill ring.


3.1 Motion

C-c C-n     (outline-next-visible-heading')



3.2 Structure editing

M-<RET>     (org-insert-heading')
Insert a new heading/item with the same level than the one at point.

Just like M-<RET>', except when adding a new heading below the
of before it.  This command works from anywhere in the entry.

Insert new TODO entry with same level as current heading.  See
also the variable org-treat-insert-todo-heading-as-state-change'.

Insert new TODO entry with same level as current heading.  Like
C-<RET>', the new headline will be inserted after the current
subtree.

<TAB>     (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.

M-<left>     (org-do-promote')
Promote current heading by one level.

M-<right>     (org-do-demote')
Demote current heading by one level.

M-S-<left>     (org-promote-subtree')
Promote the current subtree by one level.

M-S-<right>     (org-demote-subtree')
Demote the current subtree by one level.

M-S-<up>     (org-move-subtree-up')
Move subtree up (swap with previous subtree of same level).

M-S-<down>     (org-move-subtree-down')
Move subtree down (swap with next subtree of same level).

M-h     (org-mark-element')
Mark the element at point.  Hitting repeatedly will mark
subsequent elements of the one just marked.  E.g., hitting <M-h>
on a paragraph will mark it, hitting <M-h> immediately again will
mark the next one.


3.3 Sparse trees

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 it. Just try it out and you will see immediately how it works.

Org mode contains several commands creating such trees, all these commands can be accessed through a dispatcher:

C-c / (org-sparse-tree')
This prompts for an extra key to select a sparse-tree creating command.
C-c /      (org-sparse-tree')


This prompts for an extra key to select a sparse-tree creating command.

C-c /'     (org-sparse-tree')
This prompts for an extra key to select a sparse-tree creating
command.

C-c / r'     (org-occur')
Prompts for a regexp and shows a sparse tree with all matches.  If
match is in the body of an entry, 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-c'.  When called with a C-u'
prefix argument, previous highlights are kept, so several calls to
this command can be stacked.

M-g n'  or  M-g M-n'     (next-error')

M-g p'  or  M-g M-p'     (previous-error')

For frequently used sparse trees of specific search strings, you can
use the option org-agenda-custom-commands' to define fast keyboard
accessible through the agenda dispatcher (*note 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'.


The other sparse tree commands select headings based on TODO keywords, tags, or properties and will be 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 C-c C-e C-v' to export only the visible part of the document and print the resulting file.

3.4 Plain lists

Within an entry of the outline tree, hand-formatted lists can provide additional structure. They also provide a way to create lists of checkboxes (*note Checkboxes::). Org supports editing such lists, and every exporter (*note Exporting::) can parse and format them.

Org knows ordered lists, unordered lists, and description lists.

• Unordered list items start with -', +', or *'(1) as bullets.
• Ordered list items start with a numeral followed by either a period or a right parenthesis, such as 1.' or 1)'. If you want a list to start with a different value (e.g., 20), start the text of the item with [@20]'. Those constructs can be used in any item of the list in order to enforce a particular numbering.
• Description list items are unordered list items, and contain the separator  :: ' to distinguish the description term from the description.
• description here another line

Footnotes

Org mode supports the creation of footnotes. In contrast to the footnote.el' package, Org mode's footnotes are designed for work on a larger document, not only for one-off documents like emails.

A footnote is started by a footnote marker in square brackets in column 0, no indentation allowed. It ends at the next footnote definition, headline, or after two consecutive empty lines. The footnote reference is simply the marker in square brackets, inside text. For example:

The Org homepage[fn:1] now looks a lot better than it used to.
...


Org mode extends the number-based syntax to named footnotes and optional inline definition. Using plain numbers as markers (as footnote.el' does) is supported for backward compatibility, but not encouraged because of possible conflicts with LaTeX snippets (*note Embedded LaTeX::). Here are the valid references:

3.5 checklists

- [X] Checked.
- [-] Half-checked.
- [ ] Not checked.
- Normal list item.

• [X] Checked.
• [-] Half-checked.
• [ ] Not checked.
• Normal list item.

3.6 Ordered lists

1. Arabic (decimal) numbered list item. We add a few words to show the line
wrapping.
A. Upper case alpha (letter) numbered list item.
a. Lower alpha.
b. Lower alpha.
B. Upper alpha.
2. Number.

1. Arabic (decimal) numbered list item. We add a few words to show the line wrapping.
• Upper case alpha (letter) numbered list item.
• Lower alpha.
• Lower alpha.
• Upper alpha.
2. Number.

3.7 Inline picture

#+caption: Org mode logo
[[file:images/org-mode-unicorn.png]]

Click to see the [[file:images/org-mode-unicorn.png][Unicorn picture]].


Click to see the Unicorn picture.

3.8 Videos

Though, you can add an image with a link to the video like this:

[[http://www.youtube.com/watch?v=DnSGSiXYuOk][file:../bigblow.png]]


Admonitions (contextual backgrounds) are statements taken out of the content's flow and labeled with a title.

1. note
2. warning
3. tip
4. caution
5. important

(Most themes style only note and warning specially.)

This is a sample tip line (with a title)

another line

This is an example note

This is an example warning

Quote example

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

The practitioner of literate programming can be regarded as an essayist, whose main concern is with exposition and excellence of style. Such an author, with thesaurus in hand, chooses the names of variables carefully and explains what each variable means. He or she strives for a program that is comprehensible because its concepts have been introduced in an order that is best for human understanding, using a mixture of formal and informal methods that reinforce each other.

– Donald Knuth

4 Substitutions

4.1 General replacements

#+MACRO: longtext this very very long text

Insert {{{longtext}}} wherever required.


Insert this very very long text wherever required.

4.2 Styled references

#+MACRO: color @@html:<span style="color: $1">$2</span>@@

{{{color(blue, This text is colored in blue.)}}}

{{{color(red, This other text is in red.)}}}


This text is colored in blue.

This other text is in red.

#+begin_src emacs-lisp :exports results
(buffer-name)
#+end_src

The formula $$a^2 + b^2 = c^2$$ has been discovered by Pythagoras.

Let $$a=\sin(x) + \cos(x)$$. Then $$a^2 = 2\sin(x)\cos(x)$$ because $$\sin^2x + \cos^2x = 1$$.


The formula $$a^2 + b^2 = c^2$$ has been discovered by Pythagoras.

Let $$a=\sin(x) + \cos(x)$$. Then $$a^2 = 2\sin(x)\cos(x)$$ because $$\sin^2x + \cos^2x = 1$$.

The /Euler theorem/:

$\int_0^\infty e^{-x^2} dx = {{\sqrt{\pi}} \over {2}}$

LaTeX allows to inline such ~$...$~ constructs (/quadratic formula/):
$\frac{-b \pm \sqrt{b^2 - 4 a c}}{2a}$


The Euler theorem:

$\int_0^\infty e^{-x^2} dx = {{\sqrt{\pi}} \over {2}}$

LaTeX allows to inline such $...$ constructs (quadratic formula): $\frac{-b \pm \sqrt{b^2 - 4 a c}}{2a}$

$\left( \int_{0}^{\infty} \frac{\sin x}{\sqrt x}\,\mathrm{d}x \right)^{2} - \prod_{k=1}^{\infty} \frac{4k^{2}}{4k^{2}-1} + \frac{\lambda}{2n}\sum_{k=1} ^{n} \theta_{k} ^{2} x^{n} = 0$


$\left( \int_{0}^{\infty} \frac{\sin x}{\sqrt x}\,\mathrm{d}x \right)^{2} - \prod_{k=1}^{\infty} \frac{4k^{2}}{4k^{2}-1} + \frac{\lambda}{2n}\sum_{k=1} ^{n} \theta_{k} ^{2} x^{n} = 0$

The equation may be wrong, but it's a nice one!

4.3 Equation numbers

Differently from $...$ and $$...$$, an equation environment produces a numbered equation to which you can add a label and reference the equation by (label) name in other parts of the text. This is not possibly with unnumbered math environments (, …).

The /Pythagoras theorem/:

#+name: pythag
$$a^2 + b^2 = c^2$$

See equation pythag.

# The /sinus theorem/ can be written as the equation:
#
#
# \label{eqn:sinalpha}
# \frac{\sin\alpha}{a}=\frac{\sin\beta}{b}
#
#
# See equation eqn:sinalpha.


The Pythagoras theorem:

$$a^2 + b^2 = c^2$$

See equation 1.

The sinus theorem can be written as the equation:

$$\label{eqn:sinalpha} \frac{\sin\alpha}{a}=\frac{\sin\beta}{b}$$

See equation eqn:sinalpha.

Only captioned equations are numbered.

Other alternatives: use

• \begin{equation*} or
• \begin{displaymath} (= the verbose form of the $...$ construct).

M-q does not fill those.

Created: 2019-05-23 Thu 20:55

Emacs 25.2.2 (Org mode 8.2.10)

Validate