Markup: emphasis, blocks, comments and friends

This file shows how Org marks up text: emphasis, sub- and superscripts, special symbols, blocks, comments, line breaks, keywords and macros. Most of this markup is shown by the editor (colours, hidden markers) and used by the exporter (HTML, LaTeX, plain text…).

Start Neovim from the root of the repository with the bundled config:

nvim -u examples/minimal_init.lua examples/02-markup.org

• The file opens folded. <Tab> on a heading opens it, <S-Tab> cycles the whole buffer.
• <prefix> means <leader>o (<Space>o with the bundled config). g? lists every key of the buffer.
• u undoes; git checkout examples/02-markup.org restores the file.
• Try: lines are exercises, Expect: lines say what you should see.
• Lines starting with =# = are comments: notes for you, never exported.

Six markers change how text looks. Put the marker right before the first character and right after the last one:

verbatim and code look the same in most exports; the difference is that nothing inside them is interpreted: no emphasis, no links, no entities. Use code for code and verbatim for keys, file names and literal strings (this is the convention of the Org manual).

Emphasis can be nested, and can span two lines, but not more.

Try: open "Emphasis examples" below and look at the colours: each kind of markup has its own highlight group (OrgBold, OrgItalic, OrgUnderline, OrgStrikethrough, OrgVerbatim, OrgCode). Then, with the cursor in it, run :Org export html subtree body buffer.

Expect: the HTML contains, one per line:

<b>bold</b>, <i>italic</i>, <span class="underline">underlined</span>,
<del>strike-through</del>, <code>verbatim</code> and <code>code</code>.
<b>bold with <i>italic inside</i> it</b>
<code>*not bold*</code>
<b>emphasis over
two lines</b>

_ makes a subscript and ^ a superscript: x^2, a_i. Without braces the script extends over all the letters and digits that follow, so write H_{2}O (not H_2O, which subscripts "2O"). Braces are always safe: x^{10}, a_{ij}.

Two settings control them:

• In the buffer, with ui.pretty_entities on (see Entities below), scripts are drawn with Unicode super/subscript characters when all of their characters have one (x², aᵢⱼ), else highlighted with OrgSuperscript / OrgSubscript.
• In the export, #+OPTIONS: ^:{} (or :EXPORT_OPTIONS: ^:{} on a subtree) only accepts scripts in braces, so snake_case stays intact. ^:nil turns them off.

Try: export "Scripts with defaults" (:Org export html subtree body buffer).

Expect:

H<sub>2</sub>O and E=mc<sup>2</sup> and a<sub>ij</sub>
H<sub>2O</sub> is wrong: "2O" is subscripted.
snake<sub>case</sub>

Try: export "Scripts with braces only" the same way.

Expect: H_2O and snake_case stay as they are, only the braced ones change:

H_2O snake_case x<sup>2</sup> a<sub>ij</sub>

Entities are TeX-like names for symbols: \alpha, \to, \deg, \copy… Org knows hundreds of them (the same list as Emacs' org-entities). Each exporter writes the right thing: α in HTML, \alpha in LaTeX, α in UTF-8 text. End an entity with {} when a letter follows: \alpha{}beta.

In the buffer, ui.pretty_entities = true (or #+STARTUP: entitiespretty) shows them as their Unicode character. <C-c><C-x>\ toggles this for the current buffer. Entities are never prettified in blocks, code, verbatim or links. As in Emacs, only entities with a one-character symbol are drawn: \sin or \lim stay as written in the buffer (they still export as sin and lim).

Try: open "Entity examples" and press <C-c><C-x>\.

Expect: \alpha is drawn as α, \to as →, \deg{} as °, and the scripts x^2 and a_{ij} as x² and aᵢⱼ. Press <C-c><C-x>\ again to see the plain text.

Try: export "Entity examples" to HTML.

Expect:

α β π → 20°C © 2026
αbeta (the {} ends the name)

When exporting, a few character sequences become typographic symbols (#+OPTIONS: -:t, the default; -:nil turns it off):

Smart quotes (#+OPTIONS: ':t, off by default) turn "straight" quotes into curly ones, using the quotes of #+LANGUAGE:.

Try: export "Dashes and dots", then "Curly quotes".

Expect:

pages 10–20 — and so on…

and for "Curly quotes":

“Hello,” she said. It’s fine.

Math is written in LaTeX: $x^2$ or \(x^2\) inline, \[ ... \] or \begin{equation} … \end{equation} for displayed formulas. In the buffer they are highlighted (OrgLatex); <prefix>xl (Emacs <C-c><C-x><C-l>) previews them as images if you have LaTeX and an image backend. HTML export uses MathJax. Details and previews: 21-images-latex.org.

$ is only math when it is not next to a space inside: $5 and $10 is money, not math.

Try: export "Math examples".

Expect:

The area is \(\pi r^2\) and \(a+b\).
\[ E = mc^2 \]
It costs $5 and $10.

• A paragraph is a group of lines; blank lines separate paragraphs. Line breaks inside a paragraph are ignored when exporting.
• \\ at the end of a line forces a line break.
• #+OPTIONS: \n:t keeps every line break of the file.
• A line of five or more dashes (-----) is a horizontal rule.

Try: export "Breaks and rules".

Expect: the first paragraph has no <br /> (a browser shows its two lines as one), the second has one after "Forced", and the dashes became <hr />:

<p>
These two lines
form one paragraph.
</p>

<p>
Forced <br />
break here.
</p>

<hr />

Blocks start with #+begin_NAME and end with #+end_NAME (upper or lower case). Insert them with <prefix>ib (see 01-outline.org). <Tab> on the #+begin_ line folds the block; #+STARTUP: hideblocks folds all of them when the file opens.

Markup works inside quote, center and verse blocks, but not inside example and src blocks.

Try: on "Block examples", press <Tab> until everything shows, then press <Tab> on each #+begin_ line to fold and unfold it.

Expect: each block folds into its #+begin_ line.

Try: export "Block examples".

Expect: in the HTML you find <blockquote> with <b>ideas</b> inside, <div class"org-center">=, <p class"verse">= with   for the indentation and <br /> at every line end, <pre class"example">= with *not bold* left as it is, <pre class"src src-lua">=, the raw <em>raw HTML</em>, and no trace of "This is a comment block".

A line starting with a colon and a space (=: =) is shown and exported verbatim, like a one-line example block. Handy for short program output.

<C-c>: (toggle_fixed_width) adds or removes the =: = prefix on the current line, or on every line of a Visual selection.

Try: select the two "output" lines below with V and j, press <C-c>:.

Expect: both lines start with : = and are highlighted as fixed-width. Select the two lines again (=V and j) and press <C-c>: to remove it.

Try: export "Fixed-width example".

Expect:

<pre class="example">
$ date
Mon Sep 28 10:00:00 2026
</pre>

Three ways to keep text out of the export:

1. A line starting with # followed by a space (or # alone) is a comment line. #+ starts a keyword instead, and #word is plain text.
2. A #+begin_comment / #+end_comment block (see Blocks).
3. A headline starting with COMMENT comments out the whole subtree: it is left out of the export and the agenda. <prefix>hC (Emacs <C-c>;) toggles the keyword.

Try: export "Comment examples".

Expect: only "Visible text." and "#hashtag is not a comment." are in the HTML. Nothing of "Secret child" appears.

Try: on "Secret child", press <prefix>hC, and export again.

Expect: the keyword is removed, and "Secret child" and "Its text." now appear in the HTML.

Lines like #+TITLE: ... are keywords: settings for the file or the export. The ones at the top of this file are:

#+TITLE: and #+AUTHOR:

the document title and author.

#+STARTUP:

how the file opens (see 01-outline.org).

#+CATEGORY:

the name used by the agenda.

#+MACRO:

text macros (see Macros below).

Others you will meet: #+OPTIONS: (export options), #+TODO:, #+TAGS:, #+PROPERTY:, #+COLUMNS:, and the affiliated keywords #+NAME:, #+CAPTION: and #+ATTR_HTML: which go right above an element (a table, a block, an image) to name or describe it. After editing a #+ line, press <C-c><C-c> on it so the buffer picks up the change.

@@BACKEND:text@@ inserts raw text for one exporter only, inline. Other exporters drop it. Use it for things Org markup can't express, e.g. keyboard keys in HTML.

Try: export "Snippet example" to HTML, then to UTF-8 (:Org export utf8 subtree body buffer).

Expect: in HTML: Press <kbd>Ctrl</kbd>-<kbd>S</kbd> to save. In UTF-8: Press Ctrl-S to save.

Macros are templates expanded when exporting: #+MACRO: name text defines one, {{{name(arg1,arg2)}}} uses it. In the text, $1, $2… are the arguments and $0 all of them. A comma inside an argument is written \,. This file defines three macros at the top:

#+MACRO: greet Hello, $1!
#+MACRO: swap $2 before $1
#+MACRO: kbd @@html:<kbd>@@$1@@html:</kbd>@@

Built-in macros:

In the buffer, macros are highlighted with OrgMacro and not expanded.

Try: export "Macro examples".

Expect: (the export also has a small table of contents, because of the child headline)

Hello, World! Hello, Ada, Grace!
second before first
Press <kbd>C-c</kbd>.
Title: Markup: emphasis, blocks, comments and friends
Author: Ada Lovelace
Steps 1, 2, 3.

and under the "Weekly meeting" heading:

Room: Blue room

:h org-appearance

hiding markers, pretty entities, highlights

:h org-highlights

the highlight groups (OrgBold, OrgLatex…)

:h org-structure

<prefix>E, <prefix>ib, <C-c>:

:h org-export-settings

#+OPTIONS: keys and macros

:h org-images

LaTeX previews

(no term)

19-export.org and 21-images-latex.org :: more on export and math