[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

11. Markup for rich export

comment(none) to "org/Markupforrichexport"

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

11.1 Structural markup elements

comment(none) to "org/Structuralmarkupelements"

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?
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

comment(none) to "org/Documenttitle"

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

comment(none) to "org/Headingsandsections"

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


Table of contents

comment(none) to "org/Tableofcontents"

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

comment(none) to "org/Textbeforethefirstheadline"

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: This goes between the table of contents and the first headline


comment(none) to "org/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

comment(none) to "org/Paragraphs,linebreaks,andquoting"

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.

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

     -- AlexSchroeder

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:

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

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

Everything should be made as simple as possible, \\
but not any simpler

Footnote markup

comment(none) to "org/Footnotemarkup"

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

comment(none) to "org/Emphasisandmonospace"

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(none) to "org/Horizontalrules"
A line consisting of only dashes, and at least 5 of them, will be exported as a horizontal line (`
' in HTML).

Comment lines

comment(none) to "org/Commentlines"

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

11.2 Images and Tables

comment(none) to "org/ImagesandTables"

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

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

11.3 Literal examples

comment(none) to "org/Literalexamples"

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.

Some example from a text file.

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

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

11.4 Include files

comment(none) to "org/Includefiles"

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
The optional second and third parameter are the markup (e.g. `quote', `example', or `src'), and, if the markup is `src', the language for formatting the contents. The markup is optional, if it is not given, the text will be assumed to be in Org-mode format and will be processed normally. The include line will also allow additional keyword parameters :prefix1 and :prefix to specify prefixes for the first line and for each following line, as well as any options accepted by the selected markup. For example, to include a file as an item, use

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

C-c '
Visit the include file at point.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

11.5 Index entries

comment(none) to "org/Indexentries"

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: Application!CV

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

11.6 Macro replacement

comment(none) to "org/Macroreplacement"

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

11.7 Embedded LaTeX

comment(none) to "org/EmbeddedLaTeX"

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

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

11.7.1 Special symbols

comment(none) to "org/Specialsymbols"

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

11.7.2 Subscripts and superscripts

comment(none) to "org/Subscriptsandsuperscripts"

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

11.7.3 LaTeX fragments

comment(none) to "org/LaTeXfragments"

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:

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.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

11.7.4 Previewing LaTeX fragments

comment(none) to "org/PreviewingLaTeXfragments"

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)

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]

11.7.5 Using CDLaTeX to enter math

comment(none) to "org/UsingCDLaTeXtoentermath"

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):

[ << ] [ >> ]           [Top] [Contents] [Index] [Search] [Page Top / Page Bottom] [?]