11. Markup for rich export

When exporting Org-mode documents, the exporter tries to reflect the structure of the document as accurately as possible in the backend. Since export targets like HTML, LaTeX, or DocBook allow much richer formatting, Org-mode has rules on how to prepare text for rich export. This section summarizes the markup rules used in an Org-mode buffer.

11.1 Structural markup elements

Document title		Where the title is taken from
Headings and sections		The document structure as seen by the exporter
Table of contents		The if and where of the table of contents
Text before the first headline		Text before the first heading?
Lists
Paragraphs, line breaks, and quoting		Paragraphs
Footnote markup		Footnotes
Emphasis and monospace		Bold, italic, etc.
Horizontal rules		Make a line
Comment lines		What will *not* be exported

Document title

The title of the exported document is taken from the special line

#+TITLE: This is the title of the document

If this line does not exist, the title is derived from the first non-empty, non-comment line in the buffer. If no such line exists, or if you have turned off exporting of the text before the first headline (see below), the title will be the file name without extension.

If you are exporting only a subtree by marking is as the region, the heading of the subtree will become the title of the document. If the subtree has a property EXPORT_TITLE, that will take precedence.

Headings and sections

The outline structure of the document as described in 2. Document structure, forms the basis for defining sections of the exported document. However, since the outline structure is also used for (for example) lists of tasks, only the first three outline levels will be used as headings. Deeper levels will become itemized lists. You can change the location of this switch globally by setting the variable org-export-headline-levels, or on a per-file basis with a line

#+OPTIONS: H:4

Table of contents

The table of contents is normally inserted directly before the first headline of the file. If you would like to get it to a different location, insert the string [TABLE-OF-CONTENTS] on a line by itself at the desired location. The depth of the table of contents is by default the same as the number of headline levels, but you can choose a smaller number, or turn off the table of contents entirely, by configuring the variable org-export-with-toc, or on a per-file basis with a line like

#+OPTIONS: toc:2          (only to two levels in TOC)
#+OPTIONS: toc:nil        (no TOC at all)

Text before the first headline

Org-mode normally exports the text before the first headline, and even uses the first line as the document title. The text will be fully marked up. If you need to include literal HTML, LaTeX, or DocBook code, use the special constructs described below in the sections for the individual exporters.

Some people like to use the space before the first headline for setup and internal links and therefore would like to control the exported text before the first headline in a different way. You can do so by setting the variable org-export-skip-text-before-1st-heading to t. On a per-file basis, you can get the same effect with `#+OPTIONS: skip:t'.

If you still want to have some text before the first headline, use the #+TEXT construct:

#+OPTIONS: skip:t
#+TEXT: This text will go before the *first* headline.
#+TEXT: [TABLE-OF-CONTENTS]
#+TEXT: This goes between the table of contents and the first headline

Lists

Plain lists as described in 2.7 Plain lists, are translated to the backend's syntax for such lists. Most backends support unordered, ordered, and description lists.

Paragraphs, line breaks, and quoting

Paragraphs are separated by at least one empty line. If you need to enforce a line break within a paragraph, use `\\' at the end of a line.

To keep the line breaks in a region, but otherwise use normal formatting, you can use this construct, which can also be used to format poetry.

#+BEGIN_VERSE
 Great clouds overhead
 Tiny black birds rise and fall
 Snow covers Emacs

     -- AlexSchroeder
#+END_VERSE

When quoting a passage from another document, it is customary to format this as a paragraph that is indented on both the left and the right margin. You can include quotations in Org-mode documents like this:

#+BEGIN_QUOTE
Everything should be made as simple as possible,
but not any simpler -- Albert Einstein
#+END_QUOTE

If you would like to center some text, do it like this:

#+BEGIN_CENTER
Everything should be made as simple as possible, \\
but not any simpler
#+END_CENTER

Footnote markup

Footnotes defined in the way described in 2.10 Footnotes, will be exported by all backends. Org allows multiple references to the same note, and different backends support this to varying degrees.

Emphasis and monospace

You can make words *bold*, /italic/, _underlined_, =code= and ~verbatim~, 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.

Horizontal rules

Comment lines

Lines starting with `#' in column zero are treated as comments and will never be exported. If you want an indented line to be treated as a comment, start it with `#+ '. Also entire subtrees starting with the word `COMMENT' will never be exported. Finally, regions surrounded by `#+BEGIN_COMMENT' ... `#+END_COMMENT' will not be exported.

C-c ;

Toggle the COMMENT keyword at the beginning of an entry.

11.2 Images and Tables

Both the native Org-mode tables (see section 3. Tables) and tables formatted with the `table.el' package will be exported properly. For Org-mode tables, the lines before the first horizontal separator line will become table header lines. You can use the following lines somewhere before the table to assign a caption and a label for cross references, and in the text you can refer to the object with \ref{tab:basic-data}:

#+CAPTION: This is the caption for the next table (or link)
#+LABEL:   tbl:basic-data
   | ... | ...|
   |-----|----|

Some backends (HTML, LaTeX, and DocBook) allow you to directly include images into the exported document. Org does this, if a link to an image files does not have a description part, for example [[./img/a.jpg]]. If you wish to define a caption for the image and maybe a label for internal cross references, make sure that the link is on a line by itself and precede it with #+CAPTION and #+LABEL as follows:

#+CAPTION: This is the caption for the next figure link (or table)
#+LABEL:   fig:SED-HR4049
[[./img/a.jpg]]

You may also define additional attributes for the figure. As this is backend-specific, see the sections about the individual backends for more information.

11.3 Literal examples

You can include literal examples that should not be subjected to markup. Such examples will be typeset in monospace, so this is well suited for source code and similar examples.

#+BEGIN_EXAMPLE
Some example from a text file.
#+END_EXAMPLE

Note that such blocks may be indented in order to align nicely with indented text and in particular with plain list structure (see section 2.7 Plain lists). For simplicity when using small examples, you can also start the example lines with a colon followed by a space. There may also be additional whitespace before the colon:

Here is an example
   : Some example from a text file.

If the example is source code from a programming language, or any other text that can be marked up by font-lock in Emacs, you can ask for the example to look like the fontified Emacs buffer(84). This is done with the `src' block, where you also need to specify the name of the major mode that should be used to fontify the example:

#+BEGIN_SRC emacs-lisp
  (defun org-xor (a b)
     "Exclusive or."
     (if a (not b) b))
#+END_SRC

Both in example and in src snippets, you can add a -n switch to the end of the BEGIN line, to get the lines of the example numbered. If you use a +n switch, the numbering from the previous numbered snippet will be continued in the current one. 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(85). 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:

#+BEGIN_SRC emacs-lisp -n -r
(save-excursion                  (ref:sc)
   (goto-char (point-min))       (ref:jump)
#+END_SRC
In line [[(sc)]] we remember the current position.  [[(jump)][Line (jump)]]
jumps to point-min.

If the syntax for the label format conflicts with the language syntax, use a -l switch to change the format, for example `#+BEGIN_SRC pascal -n -r -l "((%s))"'. See also the variable org-coderef-label-format.

HTML export also allows examples to be published as text areas, See section 12.5.6 Text areas in HTML export.

C-c '

Edit the source code example at point in its native mode. This works by switching to a temporary buffer with the source code. You need to exit by pressing C-c ' again(86), the edited version will then replace the old version in the Org buffer. Fixed-width regions (where each line starts with a colon followed by a space) will be edited using artist-mode(87) to allow creating ASCII drawings easily. Using this command in an empty line will create a new fixed-width region.

C-c l

Calling org-store-link while editing a source code example in a temporary buffer created with C-c ' will prompt for a label, make sure that it is unique in the current buffer, and insert it with the proper formatting like `(ref:label)' at the end of the current line. Then the label is stored as a link `(label)', for retrieval with C-c C-l.

11.4 Include files

During export, you can include the content of another file. For example, to include your `.emacs' file, you could use:

#+INCLUDE: "~/.emacs" src emacs-lisp

#+INCLUDE: "~/snippets/xx" :prefix1 "   + " :prefix "     "

C-c '

Visit the include file at point.

11.5 Index entries

You can specify entries that will be used for generating an index during publishing. This is done by lines starting with #+INDEX. An entry the contains an exclamation mark will create a sub item. See 13.1.8 Generating an index for more information.

* Curriculum Vitae
#+INDEX: CV
#+INDEX: Application!CV

11.6 Macro replacement

You can define text snippets with

#+MACRO: name   replacement text $1, $2 are arguments

which can be referenced anywhere in the document (even in code examples) with {{{name(arg1,arg2)}}}. In addition to defined macros, {{{title}}}, {{{author}}}, etc., will reference information set by the #+TITLE:, #+AUTHOR:, and similar lines. Also, {{{date(FORMAT)}}} and {{{modification-time(FORMAT)}}} refer to current date time and to the modification time of the file being exported, respectively. FORMAT should be a format string understood by format-time-string.

Macro expansion takes place during export, and some people use it to construct complex HTML code.

11.7 Embedded LaTeX

Plain ASCII is normally sufficient for almost all note taking. One exception, however, are scientific notes which need to be able to contain mathematical symbols and the occasional formula. LaTeX(88) is widely used to typeset scientific documents. Org-mode supports embedding LaTeX code into its files, because many academics are used to reading LaTeX source code, and because it can be readily processed into images for HTML production.

It is not necessary to mark LaTeX macros and code in any special way. If you observe a few conventions, Org-mode knows how to find it and what to do with it.

11.7.1 Special symbols		Greek letters and other symbols
11.7.2 Subscripts and superscripts		Simple syntax for raising/lowering text
11.7.3 LaTeX fragments		Complex formulas made easy
11.7.4 Previewing LaTeX fragments		What will this snippet look like?
11.7.5 Using CDLaTeX to enter math		Speed up entering of formulas

11.7.1 Special symbols

You can use LaTeX macros to insert special symbols like `\alpha' to indicate the Greek letter, or `\to' to indicate an arrow. Completion for these macros is available, just type `\' and maybe a few letters, and press M-TAB to see possible completions. Unlike LaTeX code, Org-mode allows these macros to be present without surrounding math delimiters, for example:

Angles are written as Greek letters \alpha, \beta and \gamma.

During export, these symbols will be transformed into the native format of the exporter backend. Strings like \alpha will be exported as α in the HTML output, and as $\alpha$ in the LaTeX output. Similarly, \nbsp will become   in HTML and ~ in LaTeX. If you need such a symbol inside a word, terminate it like this: `\Aacute{}stor'.

A large number of entities is provided, with names taken from both HTML and LaTeX, see the variable org-entities for the complete list. `\-' is treated as a shy hyphen, and `--', `---', and `...' are all converted into special commands creating hyphens of different lengths or a compact set of dots.

If you would like to see entities displayed as utf8 characters, use the following command(89):

C-c C-x \

Toggle display of entities as UTF8 characters. This does not change the buffer content which remains plain ASCII, but it overlays the UTF8 character for display purposes only.

11.7.2 Subscripts and superscripts

Just like in LaTeX, `^' and `_' are used to indicate super- and subscripts. Again, these can be used without embedding them in math-mode delimiters. To increase the readability of ASCII text, it is not necessary (but OK) to surround multi-character sub- and superscripts with curly braces. For example

The mass if the sun is M_sun = 1.989 x 10^30 kg.  The radius of
the sun is R_{sun} = 6.96 x 10^8 m.

To avoid interpretation as raised or lowered text, you can quote `^' and `_' with a backslash: `\^' and `\_'. If you write a text where the underscore is often used in a different context, Org's convention to always interpret these as subscripts can get in your way. Configure the variable org-export-with-sub-superscripts to globally change this convention, or use, on a per-file basis:

#+OPTIONS: ^:{}

C-c C-x \

In addition to showing entities as UTF8 characters, this command will also format sub- and superscripts in a WYSIWYM way.

11.7.3 LaTeX fragments

With symbols, sub- and superscripts, HTML is pretty much at its end when it comes to representing mathematical formulas(90). More complex expressions need a dedicated formula processor. To this end, Org-mode can contain arbitrary LaTeX fragments. It provides commands to preview the typeset result of these fragments, and upon export to HTML, all fragments will be converted to images and inlined into the HTML document(91). For this to work you need to be on a system with a working LaTeX installation. You also need the `dvipng' program, available at http://sourceforge.net/projects/dvipng/. The LaTeX header that will be used when processing a fragment can be configured with the variable org-format-latex-header.

LaTeX fragments don't need any special marking at all. The following snippets will be identified as LaTeX source code:

• Environments of any kind. The only requirement is that the \begin statement appears on a new line, preceded by only whitespace.
• Text within the usual LaTeX math delimiters. To avoid conflicts with currency specifications, single `$' characters are only recognized as math delimiters if the enclosed text contains at most two line breaks, is directly attached to the `$' characters with no whitespace in between, and if the closing `$' is followed by whitespace, punctuation or a dash. For the other delimiters, there is no such restriction, so when in doubt, use `\(...\)' as inline math delimiters.

For example:

\begin{equation}                          % arbitrary environments,
x=\sqrt{b}                                % even tables, figures
\end{equation}                            % etc

If $a^2=b$ and \( b=2 \), then the solution must be
either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \].

If you need any of the delimiter ASCII sequences for other purposes, you can configure the option org-format-latex-options to deselect the ones you do not wish to have interpreted by the LaTeX converter.

11.7.4 Previewing LaTeX fragments

LaTeX fragments can be processed to produce preview images of the typeset expressions:

C-c C-x C-l

Produce a preview image of the LaTeX fragment at point and overlay it over the source code. If there is no fragment at point, process all fragments in the current entry (between two headlines). When called with a prefix argument, process the entire subtree. When called with two prefix arguments, or when the cursor is before the first headline, process the entire buffer.

C-c C-c

Remove the overlay preview images.

You can customize the variable org-format-latex-options to influence some aspects of the preview. In particular, the :scale (and for HTML export, :html-scale) property can be used to adjust the size of the preview images.

During HTML export (see section 12.5 HTML export), all LaTeX fragments are converted into images and inlined into the document if the following setting is active:

(setq org-export-with-LaTeX-fragments t)

11.7.5 Using CDLaTeX to enter math

CDLaTeX mode is a minor mode that is normally used in combination with a major LaTeX mode like AUCTeX in order to speed-up insertion of environments and math templates. Inside Org-mode, you can make use of some of the features of CDLaTeX mode. You need to install `cdlatex.el' and `texmathp.el' (the latter comes also with AUCTeX) from http://www.astro.uva.nl/~dominik/Tools/cdlatex. Don't use CDLaTeX mode itself under Org-mode, but use the light version org-cdlatex-mode that comes as part of Org-mode. Turn it on for the current buffer with M-x org-cdlatex-mode, or for all Org files with

(add-hook 'org-mode-hook 'turn-on-org-cdlatex)

When this mode is enabled, the following features are present (for more details see the documentation of CDLaTeX mode):

• Environment templates can be inserted with C-c {.
• The TAB key will do template expansion if the cursor is inside a LaTeX fragment(92). For example, TAB will expand fr to \frac{}{} and position the cursor correctly inside the first brace. Another TAB will get you into the second brace. Even outside fragments, TAB will expand environment abbreviations at the beginning of a line. For example, if you write `equ' at the beginning of a line and press TAB, this abbreviation will be expanded to an equation environment. To get a list of all abbreviations, type M-x cdlatex-command-help.
• Pressing _ and ^ inside a LaTeX fragment will insert these characters together with a pair of braces. If you use TAB to move out of the braces, and if the braces surround only a single character or macro, they are removed again (depending on the variable cdlatex-simplify-sub-super-scripts).
• Pressing the backquote ` followed by a character inserts math macros, also outside LaTeX fragments. If you wait more than 1.5 seconds after the backquote, a help window will pop up.
• Pressing the single-quote ' followed by another character modifies the symbol before point with an accent or a font. If you wait more than 1.5 seconds after the backquote, a help window will pop up. Character modification will work only inside LaTeX fragments, outside the quote is normal.

mail: