Org mode syntax

Set the toc attribute to activate an auto-generated table of contents (limited to its 2 first levels) at the top of document.

#+OPTIONS:   toc:2

#+OPTIONS:   p:t

To locally insert the TOC at some random place, use the #+TOC: headlines [n] feature; for example:

#+TOC: headlines 2

#+TOC: figures is not implemented yet in the HMTL backend.

#+TOC: tables is already implemented in the HTML backend.

New section.

You can create numbered headings up to a certain level by setting an option:

#+OPTIONS: H:4

A single newline has no effect.
This line is part of the same paragraph.

But an empty line

demarcates paragraphs.

A single newline has no effect. This line is part of the same paragraph.

But an empty line

demarcates paragraphs.

By entering two consecutive backslashes, \\
you can force to break lines
without starting a new paragraph.

By entering two consecutive backslashes,
you can force to break lines without starting a new paragraph.

For an horizontal line, insert at least 5 dashes: this is some text above an
horizontal rule
-----
and some text below it.

For an horizontal line, insert at least 5 dashes: this is some text above an horizontal rule

and some text below it.

One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin. He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment. His many legs, pitifully thin compared with the size of the rest of him, waved about helplessly as he looked.

Emphasize (italics), strongly (bold), and /very strongly/ (bold italics).

Emphasize (italics), strongly (bold), and very strongly (bold italics).

Markup elements can be nested:

This is italic text which contains underlined text within it, whereas this is
normal underlined text.

This is italic text which contains underlined text within it, whereas this is normal underlined text.

Markup can span across multiple lines, by default no more than 2:

*This
is not
bold.*

*This is not bold.*

Org mode does not interpret a marker surrounded by alphanumeric characters as an emphasis marker. So, you can’t (easily) emphasize just part of a word:

Not feas*ible*.

Not feas*ible*.

Other elements to use sparingly are:

- monospaced typewriter font for inline code
- monospaced typewriter font for verbatim text
- deleted text (vs. inserted text)
- text with superscript, such as 210
- text with subscript, such as H2O

• monospaced typewriter font for inline code
• monospaced typewriter font for verbatim text
• deleted text (vs. inserted text)
• text with super^script, such as 2¹⁰
• text with sub_script, such as H₂O

If the XXX option is specified, Org mode will produce typographically correct output, converting straight quotes to curly quotes, --- to em-dashes, -- to en-dashes, and ... to ellipses.

Itemized lists are marked with bullets. Create them with a minus or a plus sign.

They are convenient to organize data, and make the document prettier, and easier to read.

- Item with some lengthy text wrapping hopefully across several lines. We add
  a few words to really show the line wrapping.
- Bullet.
  + Bullet.
    * Bullet.

• Item with some lengthy text wrapping hopefully across several lines. We add a few words to really show the line wrapping.
• Bullet.
  • Bullet.
    • Bullet.

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

• ☑ Checked.
• ☐ Half-checked.
• ☐ Not checked.
• Normal list item.

Enumerated lists are marked with numbers or letters:

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.
   1. Upper case alpha (letter) numbered list item.
      1. Lower alpha.
      2. Lower alpha.
   2. Upper alpha.
2. Number.

You can have ordered lists with jumping numbers:

2. [@2] We start with point number 2.
3. Automatically numbered item.

2. We start with point number 2.
3. Automatically numbered item.

Labeled, multi-line lists.

- First term to define ::
     Definition of the first term. We add a few words to show the line wrapping,
     to see what happens when you have long lines.

- Second term ::
     Explication of the second term with inline markup.

     In many paragraphs.

First term to define

Definition of the first term. We add a few words to show the line wrapping, to see what happens when you have long lines.

Second term

Explication of the second term with inline markup.

In many paragraphs.

Adjacent lists sometimes like to fuse. To force the start of a new list, offset the two lists by an empty line comment:

- apples
- oranges
- bananas

# Comment.

- carrots
- tomatoes
- celery

• apples
• oranges
• bananas

• carrots
• tomatoes
• celery

| Cell in column 1, row 1 | Cell in column 2, row 1 |
| Cell in column 1, row 2 | Cell in column 2, row 2 |

Org tables have cells of at most one line long: there is no such thing as a multi-line table cell in Org.

Columns are automatically aligned:

• Number-rich columns to the right, and
• String-rich columns to the left.

You can create tables with an header row (by using an horizontal line of dashes to separate it from the rest of the table).

#+CAPTION: Table with an header row
| Name of column 1 | Name of column 2 | Name of column 3 |
|------------------+------------------+------------------|
| Top left         | Top middle       |                  |
|                  |                  | Right            |
| Bottom left      | Bottom middle    |                  |

To test “sticky table headers”…

#+ATTR_LATEX: :center nil
| a | b |
| 1 | 2 |

XXX Different from the following:

| a | b |
| 1 | 2 |

You can fill a table from a CSV file using R commands.

See http://www.pirilampo.org (automatic!) and the
Org mode Web site.

See http://www.pirilampo.org (automatic!) and the Org mode Web site.

#+caption: Org mode logo
file:images/org-mode-unicorn.png

Click to see the Unicorn picture.

Click to see the Unicorn picture.

Books usually align/float images on the right/left of the contents.

XXX Available HTML image tags include …

#+ATTR_LaTeX: :width 0.25\linewidth
file:images/org-mode-unicorn.png

Place images side by side: XXX

To define images that will be treated as book illustrations (figures) and automatically labeled and numbered, use XXX.

Simple box (“inline task”):

*************** TODO Do this task
Description of inline task.
*************** END

* TODO Do this task Description of inline task.

or:

*************** WAIT [#B] Do also this other task                        :phone:
*************** END

* WAIT [#B] Do also this other task :phone:

Alternatively to the inline tasks (for creating “TODO” annotations), if you want such notes not to show up in the published version, drawers may also do the job, e.g.:

:FIXME: …

:END:

You can then control what drawers are exported with org-export-with-drawers (or per document with d OPTIONS item).

Use the quote block for content that doesn’t require the preservation of line breaks.

#+begin_quote
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
#+end_quote

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

A short one:

#+begin_quote
Everything should be made as simple as possible,
but not any simpler. -- Albert Einstein
#+end_quote

Everything should be made as simple as possible, but not any simpler. – Albert Einstein

In a verse environment, there is an implicit line break at the end of each line, and indentation is preserved:

#+begin_verse
Everything should be made as simple as possible,
but not any simpler. -- Albert Einstein
#+end_verse

Everything should be made as simple as possible,
but not any simpler. – Albert Einstein

Typically used for quoting passages of an email message:

#+begin_verse
>>  The meeting has been postponed to next Friday.
>
> Has the deadline for the report been moved too?

Yes.  And chekout http://www.doodle.com/ for rescheduling the meeting.

In the text body,
   indentation is
preserved.
#+end_verse

>> The meeting has been postponed to next Friday.
>
> Has the deadline for the report been moved too?

Yes. And chekout http://www.doodle.com/ for rescheduling the meeting.

In the text body,
   indentation is
preserved.

Insert the Unicode character 00A0 to add a non-breaking space.

FIXME Or add/use an Org entity? Or use tilde?

#+MACRO: longtext this very very long text

Insert {{{longtext}}} wherever required.

Insert this very very long text wherever required.

#+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.

Find more macros on GitHub.

We also use substitutions to include some of the widely used Unicode characters (like ©, converted from text characters to its typographically correct entity).

Reference code like variables or functions inline.

Reference code like variables or functions inline.

You can also evaluate code inline as follows: 1 + 1 is #+BEGIN_SRC R 1 + 1 #+END_SRC 2.

The source code blocks support syntax highlighting:

/*
 * Application that displays a "Hello" message to the standard output.
 */
int main(int arc, char **argv)
{
  printf("Hello, %s!\n", (argc>1) ? argv[1] : "World");
  return 0;
}

(defvar hello "Hello")

(defun hello (name &optional greeting)
  (message "%s %s" (or greeting "Hello") name))

(setq tab-width 4)

The following language strings are currently recognized:

Awk, C, R, Asymptote, Calc, Clojure, CSS, Ditaa, Dot, Emacs Lisp, Fortran, Gnuplot, Haskell, IO, Java, Javascript, LaTeX, Ledger, Lilypond, Lisp, Makefile, Maxima, Matlab, Mscgen, Ocaml, Octave, Org, Perl, Pico Lisp, PlantUML, Python, Ruby, Sass, Scala, Scheme, Screen, Shell Script, Shen, Sql, Sqlite.

Code block with long lines:

testing testing testing testing testing testing testing testing testing testing
0        1         2         3         4         5         6         7         8         9
123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456

For PDF (LaTeX), one solution is to surround the code block such as:

print("This block is in scriptsize")

This block is in scriptsize

Both in example and in src snippets, you can add a -n switch to the end of the begin line to get the lines numbered:

1: (defun org-xor (a b)
2:   "Exclusive or."

If you use a +n switch, the numbering from the previous numbered snippet will be continued in the current one:

3:   (if a (not b) b))

In literal examples, Org will interpret strings like (ref:name) as labels, and use them as targets for special hyperlinks like [[(name)]] (i.e., the reference name enclosed in single parenthesis). In HTML, hovering the mouse over such a link will remote-highlight the corresponding code line, which is kind of cool.

You can also add a -r switch which removes the labels from the source code. With the -n switch, links to these references will be labeled by the line numbers from the code listing, otherwise links will use the labels with no parentheses. Here is an example:

1: (save-excursion                  ;
2:   (goto-char (point-min)))       ;

In line 1, we remember the current position. Line 2 jumps to point-min.

For inline math expressions, use the parentheses notation \(...\):

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\).

For mathematical expressions which you want to make stand out, centered on their own lines, use \[...\]:

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( \int0\infty \frac{\sin x}{\sqrt x}\,\mathrm{d}x \
right)2 -
\prodk=1\infty \frac{4k2}{4k2-1} +
\frac{\lambda}{2n}\sumk=1 ^{n} \thetak ^{2} xn = 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!

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
\begin{equation}
a^2 + b^2 = c^2
\end{equation}

See equation pythag.

# The sinus theorem can be written as the equation:
#
# \begin{equation}
# \label{eqn:sinalpha}
# \frac{\sin\alpha}{a}=\frac{\sin\beta}{b}
# \end{equation}
#
# See equation eqn:sinalpha.

The Pythagoras theorem:

See equation 1.

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.

You can include another Org file and skip its title by using the :lines argument to #+INCLUDE:

#+INCLUDE: "chapter1.org" :lines "2-"

You can include raw HTML in your Org documents and it will get kept as HTML when it’s exported.

Text can be preformatted (in a fixed-width font).

It is especially useful for more advanced stuff like images or tables where you need more control of the HTML options than Org mode actually gives you.

Similarly, you can incorporate JS or do anything else you can do in a Web page (such as importing a CSS file).

You can also use raw LaTeX. XXX

Text can be preformatted (in a fixed-width font).

The string fixme (in upper case) gets replaced by a “Fix Me!” image:

FIXME Delete this...

FIXME Delete this…

Data to be charted:

Code:

plot(data, type="b", bty="l", col=c("#ABD249"), las=1, lwd=4)
grid(nx=NULL, ny=NULL, col=c("#E8E8E8"), lwd=1)
legend("bottom", legend=c("Degrees"), col=c("#ABD249"), pch=c(19))

The resulting chart:

Index (or list of acronyms).

• Write index entries

Note that multi-entry terms generate separate index entries.

• Place the index at the desired location
• Produce the index by updating org-latex-pdf-process

The bibliography…

• Eric Steven Raymond. The Art of Unix Programming. Addison-Wesley. ISBN 0-13-142901-9.

Glossaries are optional. Glossaries entries are an example of definition lists.

A glossary term

The corresponding (indented) definition.

A second glossary term

The corresponding (indented) definition.

Report issues and suggest features and improvements on the GitHub issue tracker.

I love contributions! Patches under any form are always welcome!

If you like the refcard-org-mode project, you can show your appreciation and help support future development by making a donation through PayPal.

Regardless of the donations, refcard-org-mode will always be free both as in beer and as in speech.