Markup for Rich Contents
Org started as a tool for organizing notes, but the same plain text can become an HTML page, a PDF or a slide deck. For that, Org needs a way to express emphasis, symbols, formulas, code, images and footnotes. This chapter describes that markup.
Two ideas make the rules easier to remember. First, markup is designed to look reasonable as plain text: *bold* reads as emphasis even in a terminal. Second, every piece of markup is either an element or an object, and that distinction decides where it may appear.
Elements and objects
Org’s parser divides a document into two kinds of syntax:
- An element is a block-level unit that occupies whole lines: a paragraph, a list, a table, a block, a drawer, a keyword line. Some elements, called greater elements, can contain other elements: a plain list contains items, and a quote block contains paragraphs.
- An object is an inline unit inside a line: bold text, a link, an entity, a footnote reference, a LaTeX fragment. Objects can contain other objects (italic inside bold), but never elements.
The following entry and its parse tree show the relationship. The tree was printed from org-element-parse-buffer in Org 9.8.13 (plain text nodes omitted):
* Notes
Org is *plain /text/*.[fn:1]
- see =README=
#+BEGIN_QUOTE
Keep it simple.
#+END_QUOTE
flowchart TD
D["org-data"] --> H["headline: Notes"]
H --> S["section"]
S --> P["paragraph (element)"]
S --> L["plain-list (greater element)"]
S --> Q["quote-block (greater element)"]
P --> B["bold (object)"]
B --> I["italic (object)"]
P --> F["footnote-reference (object)"]
L --> IT["item (greater element)"]
IT --> P2["paragraph (element)"]
P2 --> V["verbatim (object)"]
Q --> P3["paragraph (element)"]
Figure 4.1: Elements stack inside greater elements down to paragraphs, and objects live only inside paragraphs and similar text-holding elements.
This explains several rules you will meet below. A caption keyword attaches to the next element, so it can label a table or a paragraph containing a single image link. Emphasis is an object, so it cannot span two paragraphs. The full lists of types are in the variables org-element-all-elements and org-element-all-objects; the parser itself is the subject of Hacking and Extending Org.
Paragraphs and line breaks
A paragraph is a run of text lines separated from other text by at least one empty line. Single line breaks inside a paragraph are not significant: when exporting, Org joins the lines, and the target format decides where to wrap.
When you need a hard line break inside a paragraph, end the line with two backslashes (\\):
Line one\\
line two
The HTML exporter turns this into Line one<br /> followed by line two, still within one <p> element.
Verse, quote and center blocks
Three blocks change how a paragraph is laid out.
| Block | Purpose |
|---|---|
#+BEGIN_VERSE … #+END_VERSE | Keep line breaks, leading spaces and blank lines, for poems and addresses. |
#+BEGIN_QUOTE … #+END_QUOTE | Mark a quotation, usually indented on both sides. |
#+BEGIN_CENTER … #+END_CENTER | Center the contained text. |
#+BEGIN_VERSE
Roses
are red
#+END_VERSE
#+BEGIN_QUOTE
Simple things should be simple.
#+END_QUOTE
Exported to HTML, the verse block keeps its shape through <br /> and non-breaking spaces, while the quote block becomes a <blockquote>:
<p class="verse">
Roses<br />
are red<br />
</p>
<blockquote>
<p>
Simple things should be simple.
</p>
</blockquote>
The text inside these blocks is still Org markup: emphasis and links work as usual. To insert any of them quickly, use the structure templates described in Getting Started.
Emphasis and monospace
Org has 6 inline markers. Each one surrounds the text it applies to:
| Markup | Meaning | HTML | LaTeX |
|---|---|---|---|
*bold* | Bold | <b>bold</b> | \textbf{bold} |
/italic/ | Italic | <i>italic</i> | \emph{italic} |
_underlined_ | Underline | <span class="underline"> | \uline{underlined} |
=verbatim= | Verbatim | <code>verbatim</code> | \texttt{verbatim} |
~code~ | Code | <code>code</code> | \texttt{code} |
+struck+ | Strike-through | <del>struck</del> | \sout{struck} |
The HTML and LaTeX columns are the real output of Org 9.8.13 for the sentence Make words *bold*, /italic/, _underlined_, =verbatim=, ~code~ and +struck+.
Verbatim and code differ from the others in one important way: their contents are not parsed. Inside =...= or ~...~, stars, slashes and brackets are just characters. This makes them the right choice for file names, commands and identifiers. By convention, ~code~ is used for code and =verbatim= for literal strings such as file names, although most backends export both the same way.
Emphasis can be nested, as long as the markers differ:
*bold /and italic/ together*
This exports as <b>bold <i>and italic</i> together</b>.
When a marker counts as markup
A star or slash in the middle of ordinary text should not start emphasis, so Org applies boundary rules. The rules live in org-emphasis-regexp-components; in Org 9.8.13 they say, in summary:
- The opening marker must be preceded by the start of a line, whitespace, or one of
-('"{. - The character right after the opening marker, and the character right before the closing marker, must not be whitespace.
- The closing marker must be followed by the end of a line, whitespace, or one of
-.,:!?;'")}\[.
The same variable also limits the number of line breaks, but that limit concerns highlighting in the buffer. In a test, the exporter accepted an italic span that ran over 4 lines of one paragraph.
These rules handle most cases, but they are not perfect. The following sentence was exported to HTML:
*bold /and italic/ together*, but * not bold*, and x*y*z.
A path like /usr/bin/ is fine; but a/b/c is not italic.
<b>bold <i>and italic</i> together</b>, but * not bold*, and x*y*z.
A path like <i>usr/bin</i> is fine; but a/b/c is not italic.
* not bold* is safe because a space follows the opening star, and x*y*z is safe because a letter precedes it. The path /usr/bin/, however, satisfies every rule and becomes italic. There are two ways out:
- Write paths and identifiers as verbatim:
=/usr/bin/=exports as<code>/usr/bin/</code>. - Insert a zero width space right after the opening marker (see Escaping Org syntax). The exporter then leaves
/usr/bin/as plain text.
The reverse problem also exists. A marker character inside the emphasized text can end the emphasis early. The line /a sentence with ~user/?var~ inside/ exports as <i>a sentence with ~user</i>?var~ inside/: the slash inside the code is followed by ?, which is a valid closing context, so the italic span ends there and the code markup is lost. Again, a zero width space resolves the ambiguity.
Commands and display options
C-c C-x C-f (org-emphasize) asks for a marker character and applies it. With an active region, it wraps the region; without one, it inserts a pair of markers and places point between them.
Three variables control how emphasis looks in the buffer. None of them changes the file or the export.
org-hide-emphasis-markers: whent, the marker characters are hidden, so*bold*displays as a bold word without stars. This makes prose easier to read, but harder to edit at the edges of the emphasis.org-fontify-emphasized-text(defaultt): set it tonilto turn off emphasis highlighting completely.org-emphasis-alist: maps each marker to its face. Removing an entry stops the highlighting for that marker, but the markup is still recognized on export.
Subscripts and superscripts
_ introduces a subscript and ^ a superscript. Curly braces delimit a longer script:
The area is r^2, and R_{sun} is the solar radius.
Without braces, the script extends over the following run of alphanumeric characters, which may be more than you intended. This is the HTML export of a short sentence:
Water is H_2O, the area is r^2 and R_{sun} differs from file_name.
Water is H<sub>2O</sub>, the area is r<sup>2</sup> and R<sub>sun</sub> differs from file<sub>name</sub>.
Two results are wrong for most writers: 2O is lowered as a whole, and the underscore in file_name becomes a subscript. Technical documents contain many underscores, so the usual solution is to require braces. The export option ^:{} does this for one file:
#+OPTIONS: ^:{}
Water is H_{2}O but file_name stays.
Water is H<sub>2</sub>O but file_name stays.
The option sets two variables at once: org-use-sub-superscripts (the display in Emacs) and org-export-with-sub-superscripts (the export). Both accept t, {} or nil. With {}, a_b is still parsed as a subscript object, but neither displayed nor exported as one. Export options are described in Exporting.
In the buffer, C-c C-x \ (org-toggle-pretty-entities) displays sub- and superscripts raised and lowered, together with the entities described next. To start in that state, set org-pretty-entities to t; org-pretty-entities-include-sub-superscripts (default t) decides whether scripts are included.
Special symbols: entities
Plain text lacks many characters that technical writing needs. Org borrows the LaTeX style: an entity is a backslash followed by a name, such as \alpha for the Greek letter or \to for an arrow. When an entity is directly followed by a letter, end it with {}:
Angles \alpha and \beta; an arrow \to; \pi{}d; 5\nbsp{}km.
Each exporter translates entities into its native form. Org 9.8.13 produces:
Angles α and β; an arrow →; πd; 5 km.
Angles \(\alpha\) and \(\beta\); an arrow \(\to\); \(\pi\)d; 5~km.
To find an entity, type \ and a few letters, then press M-TAB to complete. M-x org-entities-help lists all built-in entities in a buffer. You can add your own through org-entities-user. Each entry gives the name, the LaTeX code, whether that code needs math mode, and the HTML, ASCII, Latin-1 and UTF-8 forms:
(setq org-entities-user
'(("check" "\\checkmark" t "✓" "[x]" "[x]" "✓")))
With this setting, Done \check{} exports as Done ✓ in HTML and Done \(\checkmark\) in LaTeX.
C-c C-x \ displays entities as UTF-8 characters in the buffer; the file keeps the ASCII form. Use #+STARTUP: entitiespretty to turn this on for a single file.
Special strings
A few common character sequences also receive special treatment on export:
| Input | Exported as |
|---|---|
-- | En dash (– in HTML) |
--- | Em dash (— in HTML) |
... | Ellipsis (… in HTML, \ldots{} in LaTeX) |
\- | Soft hyphen (­ in HTML) |
If you need the sequences exported unchanged, add #+OPTIONS: -:nil. With that option, A -- B --- C ... exports to HTML exactly as written.
Embedded LaTeX
Mathematical notation is hard to express in plain text, and LaTeX is the established notation for it. Org therefore recognizes LaTeX directly in the text, with no extra markup. Two forms are recognized:
- A LaTeX environment: any
\begin{...}…\end{...}construct, provided\beginstarts a line (only whitespace may precede it). - A LaTeX fragment: math inside
\(...\)or\[...\], or inside$...$and$$...$$.
\begin{equation}
x=\sqrt{b}
\end{equation}
If \( b=2 \), then the solution is \[ x=\sqrt{2} \].
Prefer \(...\) for inline math. The single dollar form has strict conditions so that prices are not mistaken for math: the enclosed text may contain at most two line breaks, no whitespace may follow the opening $ or precede the closing one, and the closing $ must be followed by whitespace or punctuation other than a dash. When a literal dollar sign is misread, the entities \dollar and \USD help. For example:
It costs \dollar{}5, and $x$ is math.
exports to HTML as It costs $5, and \(x\) is math.; the second part is then rendered by MathJax in the browser.
Controlling LaTeX on export
The variable org-export-with-latex (default t) decides what happens to LaTeX on export. The LaTeX backend always passes the code through unchanged. For HTML, the default is MathJax, which renders the formulas in the browser. A file can override the default:
| Option line | Effect |
|---|---|
#+OPTIONS: tex:t | Process fragments in the default way (MathJax for HTML). |
#+OPTIONS: tex:nil | Do not process LaTeX fragments at all. |
#+OPTIONS: tex:verbatim | Export the LaTeX source as plain text. |
HTML math settings are covered in Exporting.
Previewing formulas in the buffer
With a LaTeX installation and an image converter (by default dvipng, chosen by org-preview-latex-default-process), Org can show typeset formulas as images in the buffer.
C-c C-x C-l (org-latex-preview) previews the fragment at point, or all fragments in the current entry when point is not on one. Prefix arguments widen or reverse the action:
| Key | Effect |
|---|---|
C-c C-x C-l | Preview the fragment at point, or the current entry. |
C-u C-c C-x C-l | Remove previews in the current entry. |
C-u C-u C-c C-x C-l | Preview all fragments in the buffer. |
C-u C-u C-u C-c C-x C-l | Remove all previews in the buffer. |
The size of the images is set by the :scale property of org-format-latex-options (default 1.0), and org-format-latex-header defines the LaTeX preamble used to render them. #+STARTUP: latexpreview previews all fragments when the file opens, and nolatexpreview turns this off.
Entering math with CDLaTeX
If you write a lot of math, the third-party package CDLaTeX speeds up typing. Org ships its own minor mode for it, org-cdlatex-mode, which you turn on with M-x org-cdlatex-mode or for all Org buffers with:
(add-hook 'org-mode-hook #'turn-on-org-cdlatex)
The cdlatex package itself must be installed separately (it is available from NonGNU ELPA). Inside a LaTeX fragment, TAB then expands abbreviations such as fr into \frac{}{}, and C-c { inserts an environment template. Do not turn on the original cdlatex-mode in Org buffers; use the Org variant.
Literal examples
Technical notes often contain text that must appear exactly as written: program output, configuration files, code. Org provides several ways to keep such text away from the markup parser.
Example blocks and fixed-width lines
An example block holds literal text, exported in monospace with no markup processing:
#+BEGIN_EXAMPLE
Some output, where *stars* are just stars.
#+END_EXAMPLE
For one or two lines, a colon followed by a space at the start of each line is shorter. Such lines are called fixed-width lines:
: $ make test
: 42 tests passed
Escaping with commas
The contents of a block are protected from markup, but not from structure: a line starting with * would still end the block and start a headline. To prevent this, Org puts a comma before lines that begin with *, ,*, #+ or ,#+. The comma is removed whenever Org reads the block contents, including on export:
#+BEGIN_EXAMPLE
,* not a headline
,#+TITLE: not a keyword
#+END_EXAMPLE
The ASCII exporter prints this block as:
,----
| * not a headline
| #+TITLE: not a keyword
`----
You rarely need to add the commas yourself: when you edit a block with C-c ' (described below), Org adds and removes them automatically.
Source blocks
When the literal text is code, use a source block, which names a language:
#+BEGIN_SRC emacs-lisp
(defun double (n)
"Return twice N."
(* 2 n))
#+END_SRC
The language name serves three purposes. In the buffer, Org highlights the code with the major mode for that language. On export, backends can highlight it too. And with Babel, Org can run the code and insert its results. Running code is the subject of Working with Source Code; this section covers only the display features that example and source blocks share.
Line numbers and code references
The -n switch numbers the lines of an example or source block on export. It takes an optional starting number. The +n switch continues the numbering of the previous numbered block, optionally adding an offset. In a source block, switches go after the language name and before any header arguments.
#+BEGIN_SRC python -n 20
print(1)
print(2)
#+END_SRC
#+BEGIN_SRC python +n 10
print(3)
#+END_SRC
The ASCII export shows the numbering: the first block starts at 20, and the second continues from the last line (21) plus 10.
,----
| 20 print(1)
| 21 print(2)
`----
,----
| 31 print(3)
`----
Prose often needs to refer to a specific line of code. Put a label of the form (ref:name) at the end of the line, and link to it with [[(name)]]. The -r switch removes the labels from the exported code; combined with -n, the links then show the line numbers:
#+BEGIN_SRC emacs-lisp -n -r
(save-excursion (ref:sc)
(goto-char (point-min))) (ref:jump)
#+END_SRC
Line [[(sc)]] saves point; line [[(jump)]] moves to the start.
,----
| 1 (save-excursion
| 2 (goto-char (point-min)))
`----
Line 1 saves point; line 2 moves to the start.
Without -n, the links show the label names instead. If the default label format clashes with the language’s syntax, change it with the -l switch, for example -l "((%s))", or globally with org-coderef-label-format (default "(ref:%s)").
Blocks may be indented to line up with a list item. By default Org keeps only the relative indentation of the lines; the -i switch preserves the block’s indentation as written.
Editing in the native mode
C-c ' (org-edit-special) opens the block at point in a separate buffer that uses the language’s major mode, with all its editing commands and completion. Press C-c ' again to write the edited text back into the Org file. On fixed-width lines, the same key opens an Artist mode buffer for drawing ASCII diagrams.
While you edit code this way, org-store-link (see Hyperlinks) asks for a label, inserts it as a (ref:label) at the end of the line, and stores a link to it that you can insert into your prose later.
Images and link previews
An image in Org is simply a link to an image file that has no description part:
[[./img/architecture.png]]
Exporters turn such a link into an embedded image. A link with a description, such as [[./img/architecture.png][the diagram]], stays an ordinary link. Links are covered in Hyperlinks.
Showing images in the buffer
Org can display images inside the buffer. Since Org 9.8 this is part of a general link preview system: image links are the type previewed by default, and other link types can define their own previews (Hacking and Extending Org).
| Key | Command | Effect |
|---|---|---|
C-c C-x C-v | org-link-preview | Preview links in the region if it is active, otherwise the link at point, otherwise the current section. |
C-u C-c C-x C-v | Clear previews at point or in the current entry. | |
C-u C-u C-c C-x C-v | Preview all links in the buffer. | |
C-u C-u C-u C-c C-x C-v | Clear all previews in the buffer. | |
C-c C-x C-M-v | org-link-preview-refresh | Refresh all previews in the buffer. |
By default only links without a description are previewed. A numeric argument of 1 (C-1 C-c C-x C-v) also previews described links locally, and 11 does the same for the whole buffer. M-x org-link-preview-region and M-x org-link-preview-clear work on the region or the whole buffer.
To show previews whenever a file opens, set org-startup-with-link-previews or add #+STARTUP: linkpreviews (nolinkpreviews disables it). With org-cycle-link-previews-display set, unfolding a subtree also displays its previews.
Size and alignment
Three variables control how previewed images appear:
org-image-actual-width(defaultt) uses the image’s real width, limited byorg-image-max-width. A number forces that width in pixels. A number in a list, such as'(300), first looks for a width in an#+ATTR_...keyword above the link and falls back on the number.org-image-max-width(defaultfill-column) caps the width when none is given explicitly. It also acceptswindow, a pixel count, ornilfor no limit.org-image-align(defaultleft) can also becenterorright. It affects only images that stand alone in their paragraph.
A single image can override these settings through attribute keywords. #+ATTR_ORG takes precedence in the buffer, while the exporters read their own keyword:
#+ATTR_HTML: :width 600px :align right
#+ATTR_ORG: :width 300 :align center
[[./img/architecture.png]]
In Emacs, this image is centered, and the HTML export uses the #+ATTR_HTML values. The :width 300 is honored in the buffer only when org-image-actual-width is nil or a list; with the default t, Org keeps the actual width. For a whole subtree, the property ORG-IMAGE-ACTUAL-WIDTH overrides org-image-actual-width.
Captions and names
A caption describes a table, an image or another element. Put a #+CAPTION: keyword directly before the element. A #+NAME: keyword gives the element a label that links can point to:
#+CAPTION: Request flow through the proxy
#+NAME: fig:flow
[[./img/flow.png]]
As [[fig:flow]] shows, every request passes the proxy.
Exported to HTML by Org 9.8.13, the image becomes a numbered figure, and the link resolves to its number (the id value is generated and changes between runs):
<div id="org79f6116" class="figure">
<p><img src="./img/flow.png" alt="flow.png" />
</p>
<p><span class="figure-number">Figure 1: </span>Request flow through the proxy</p>
</div>
<p>
As <a href="#org79f6116">1</a> shows, every request passes the proxy.
</p>
For an image, the link must be alone on its line, so that the paragraph contains nothing else. Tables work the same way, and are numbered as tables:
#+CAPTION[Disk sizes]: Disk sizes of the home server, measured after installation.
#+NAME: tab:sizes
| Disk | Size |
|------+------|
| sda | 2 TB |
The text in square brackets is an optional short caption, used where space is limited, such as a list of tables in LaTeX. The HTML export of this table begins with <caption class="t-above"><span class="table-number">Table 1:</span> Disk sizes of the home server, measured after installation.</caption>. Other elements, such as source blocks and LaTeX environments, can also take captions; whether a backend uses them depends on the backend.
Horizontal rules
A line containing only dashes, at least 5 of them, is a horizontal rule. ----- exports to HTML as <hr />.
Footnotes
Footnotes let you add a remark without interrupting the main text. A footnote has two parts: a reference in the text and a definition elsewhere.
Org is plain text.[fn:1] It also exports well.[fn:: An inline note.]
[fn:1] Plain text survives changes of tools.
A definition starts with the label in square brackets at column 0, with no indentation. It ends at the next footnote definition, the next headline, or two consecutive empty lines.
Org accepts three forms of reference:
| Reference | Meaning |
|---|---|
[fn:NAME] | A reference to the definition labeled NAME; the label is a word or a number. |
[fn:: text] | An anonymous footnote, defined right where it is referenced. |
[fn:NAME: text] | An inline definition that also has a name, so that other places can refer to it with [fn:NAME]. |
Several references may point to the same named footnote. On export, Org numbers all footnotes in order of appearance. The HTML backend in 9.8.13 turns the example above into superscript links 1 and 2 and collects the definitions in a <div id="footnotes"> at the end of the page.
Footnote commands
C-c C-x f (org-footnote-action) is the main footnote command:
- On a reference, it jumps to the definition.
- On a definition, it jumps back to the first reference.
- Elsewhere, it creates a new footnote. With the default settings the label is created automatically (see
org-footnote-auto-labelbelow).
With a prefix argument, C-c C-x f offers maintenance actions:
| Key | Action |
|---|---|
s | Sort the definitions in the order of their references. |
r | Renumber the simple fn:N footnotes. |
S | Renumber, then sort. |
n | Rename all footnotes into the sequence fn:1 … fn:n. |
d | Delete the footnote at point with its definition and references. |
C-c C-c on a reference or definition also jumps between the two, and with a prefix offers the same menu. C-c C-o and mouse clicks follow footnotes like links.
Four variables decide where new definitions go and how labels are created:
org-footnote-section(default"Footnotes"): the headline under which definitions are collected. When it isnil, each definition goes to the end of its own section.org-footnote-define-inline(defaultnil): whent, new footnotes are defined inline. The per-file options are#+STARTUP: fninlineandnofninline.org-footnote-auto-label(defaultt): creates numeric labels automatically. Other values prompt for a label or offer one for confirmation; the matchingSTARTUPoptions arefnauto,fnprompt,fnconfirmandfnanon.org-footnote-auto-adjust(defaultnil): renumbers and sorts footnotes after each insertion or deletion. TheSTARTUPoptions arefnadjustandnofnadjust.
Escaping Org syntax
Sometimes text looks like Org syntax but should stay plain. Org uses specific escape mechanisms in a few places: commas in blocks (described above), and backslashes in links and macros (Hyperlinks, Exporting). For everything else, the general tool is the zero width space, the invisible character U+200B. Inserted between two characters, it breaks the pattern without visible change.
Insert it with C-x 8 RET followed by either zero width space or 200B, then RET. Two typical uses:
- To write
[[1,2]]as text, put a zero width space between the two opening brackets. Without it, Org reads a link to a target named1,2, and export fails withUnable to resolve link: "1,2". - To keep
/usr/bin/from becoming italic, put a zero width space right after the first slash. Org’s character classes count the zero width space as whitespace, so the opening slash is now followed by whitespace and no longer qualifies. For the same reason, a zero width space placed before the first slash does not help: it acts like an ordinary space there, which is a valid context for an opening marker.
The zero width space is invisible, which is both its strength and its weakness: a reader of the raw file cannot see why the markup is not applied. For paths and identifiers, verbatim markup (=/usr/bin/=) is usually clearer.
Summary
- Elements are block-level and objects are inline; objects only appear inside text-holding elements.
- Use
*bold*,/italic/,_underline_,+strike+, and prefer=verbatim=or~code~for anything technical. - Add
#+OPTIONS: ^:{}to documents with many underscores. - Entities (
\alpha,\to,\nbsp) and LaTeX fragments (\(...\)) are translated per backend. - Example blocks, fixed-width lines and source blocks keep text literal;
C-c 'edits them in their native mode. - An image is a link without a description;
#+CAPTIONand#+NAMEturn it into a numbered figure. C-c C-x fmanages footnotes, and the zero width space escapes everything else.
Further reading
- Official manual: Markup for Rich Contents, Paragraphs, Emphasis and Monospace, Subscripts and Superscripts, Special Symbols, Embedded LaTeX, Previewing LaTeX fragments, CDLaTeX mode, Literal Examples, Images and link previews, Captions, Horizontal Rules, Creating Footnotes, Escape Character, Org Syntax.
- Source at release 9.8.13: lisp/org-element.el (the parser), lisp/org-entities.el (entity table), lisp/org-footnote.el (footnotes), etc/ORG-NEWS (the 9.8 link preview changes).