Export: hands-on examples
Table of Contents
- 1. How to use this file
- 2. The export dispatcher
- 3. Back-ends and the tools they need
- 4. Document keywords: title, author, date, …
- 5. #+OPTIONS: the export switches
- 5.1. Sample: toc, num and H
- 5.2. Exercises: toc, num and H
- 5.3. Sample: sub- and superscripts
- 5.4. Exercises: sub- and superscripts
- 5.5. Sample: tags, TODO keywords and priorities
- 5.6. Exercises: tags, TODO keywords and priorities
- 5.7. Sample: drawers, planning, clocks and timestamps
- 5.8. Exercises: drawers, planning, clocks and timestamps
- 5.9. Sample: line breaks, quotes, special strings
- 5.10. Exercises: line breaks, quotes, special strings
- 5.11. Sample: what to leave out entirely
- 5.12. Exercises: what to leave out entirely
- 6. Choosing what is exported
- 6.1. Tags: noexport and export
- 6.2. Sample: noexport
- 6.3. Exercises: noexport
- 6.4. Sample: select tags
- 6.5. Exercises: select tags
- 6.6. Sample: COMMENT headings, comment lines and blocks
- 6.7. Exercises: COMMENT headings, comment lines and blocks
- 6.8. Sample: archived trees
- 6.9. Exercises: archived trees
- 7. Subtree properties (EXPORT_*)
- 8. Table of contents
- 9. Captions, names and cross-references
- 10. Footnotes in export
- 11. Macros
- 12. Raw output for one back-end
- 13. HTML specifics: #+ATTR_HTML and #+HTML_HEAD
- 14. LaTeX and PDF specifics
- 15. Beamer slides
- 16. Markdown, GFM, plain text and Org
- 17. #+INCLUDE: pulling in other files
- 18. Source blocks and :exports
- 19. Citations
- 20. Broken links
- 21. iCalendar, ODT, DOCX, Texinfo and pandoc (file exports)
- 22. Publishing projects
- 23. Configuring defaults
- 24. Further reading
1. How to use this file
Export turns an Org file (or one subtree of it) into another format: HTML, LaTeX/PDF, Beamer slides, Markdown, plain text, ODT, iCalendar, Texinfo, Org, or anything pandoc can write. This file walks through the dispatcher, every back-end, the export settings and the markup that only matters on export, with sample subtrees you export yourself and compare with the output quoted here.
- The file opens folded (
#+STARTUP: overview).<Tab>on a heading opens it,<S-Tab>cycles the whole buffer. uundoes anything;git checkout examples/19-export.orgrestores the file.g?lists every key of the current buffer.<prefix>is<leader>o(with the bundled init,<Space>o). Emacs keys work too:C-c C-eis the dispatcher.- Lines starting with Try: are exercises, Expect: says what you should see. Lines starting with =# = (hash, space) are comments: they explain the examples and are never exported.
Start Neovim from the repo root with the bundled init, which keeps your own config and notes out of the way:
nvim -u examples/minimal_init.lua examples/19-export.org
(examples/minimal_init.lua sets the agenda files to examples/*.org, puts
captures in a scratch directory under stdpath("state") and defines a few
capture templates and agenda commands; none of that matters for export.)
1.1. Where does the output go?
- To a buffer (the capital-letter keys:
h H,m M,t A,t U,l L,l B,O O,m G): the result opens in a vertical split, in a scratch buffer named like "Org HTML Export #12". Nothing is written to disk; close it with:q. All exercises in this file use these keys. - To a file (lower-case keys:
h h,m m,t a,l l,o o, …): the file is written next to this one, inside the repo (examples/19-export.htmland friends, or#+EXPORT_FILE_NAME). Only a few exercises do that and they say so; delete the files afterwards (git statusshows them as untracked) or setexport.output_dirin your config to send them elsewhere.
1.2. Why the samples are subtrees
Almost every exercise exports one subtree: put the cursor anywhere inside
a heading called "Sample: …" and press <prefix>e s first (s toggles
"export scope = subtree"), then the back-end keys. A subtree export:
- uses only the body of that heading: its children become the top-level sections of the output, and the heading itself is not a section;
- reads
EXPORT_*properties from the heading's:PROPERTIES:drawer (EXPORT_TITLE,EXPORT_OPTIONS, …). They override the#+...keywords of the file, so every sample carries its own settings.
Important: #+TITLE:, #+OPTIONS:, #+HTML_HEAD: and the other
settings keywords apply to the whole file, wherever they are written,
even when you export only a subtree. That is why this file shows
file-level keywords inside #+begin_src org blocks (those are just code)
and uses EXPORT_* properties for the samples. The only live settings
keywords are the few at the top of this file and the #+MACRO: lines of
the macros sample.
Each "Sample: …" heading is followed by an "Exercises: …" heading with the Try: / Expect: steps. Keep the cursor inside the sample when you export: with the cursor in the Exercises heading you would export the exercise text instead.
1.3. Keys in this file
| Keys | What it does |
|---|---|
<prefix>e (C-c C-e) |
open the export dispatcher |
s b v a |
toggles: subtree, body only, visible, async |
h H / m M / m G |
HTML / Markdown / GFM to a buffer |
t A / t U / t L |
ASCII / UTF-8 / Latin-1 text to a buffer |
l L / l B / O O |
LaTeX / Beamer / Org to a buffer |
# |
insert the export settings template |
<Esc> |
close the dispatcher |
:Org export ... |
exports without the menu (see below) |
<Tab>, <S-Tab> |
fold / unfold (matters for v) |
<prefix>' (C-c ') |
edit a source or export block in a split |
2. The export dispatcher
<prefix>e (Emacs C-c C-e) opens a small menu. Each line shows a key in
brackets; press the key, no <CR> needed. Keys with … open a sub-menu.
The first four lines are toggles. Pressing one redraws the menu with the new value, so you can combine them before choosing a format:
| Key | Toggle | Effect when on |
|---|---|---|
b |
body only | no preamble: no <html>=/=<head>, no |
\documentclass, no title block |
||
s |
export scope | "subtree": only the subtree at the cursor |
v |
visible only | skip what is folded right now |
a |
async (PDF) | compile PDFs in the background (see below) |
Then one line per back-end (h HTML, l LaTeX/Beamer/PDF, m Markdown,
t plain text, O Org, o ODT, d DOCX, i Texinfo, c iCalendar,
P publish, p any pandoc format) and # (insert the settings template).
The toggles are reset every time you open the dispatcher.
The same exports without the menu, as an Ex command (the words after the format are optional and can be in any order):
:Org export html subtree buffer " like <prefix>e s h H
:Org export md subtree body buffer " subtree, body only, to a buffer
:Org export ascii visible buffer " only what is unfolded
:Org export latex " whole file to examples/19-export.tex
:Org export pdf async open " compile in the background, then open
:Org export " no format: opens the dispatcher
And from Lua (handy for mappings and scripts): to_string returns the text
and writes nothing, export behaves like the dispatcher.
local exp = require("org.export")
local md = exp.to_string("md", { body_only = true }) -- whole buffer
local line = vim.api.nvim_win_get_cursor(0)[1]
local txt = exp.to_string("ascii", { subtree_line = line })
exp.export("html", { subtree = true, to_buffer = true })
exp.export("md", { output = "/tmp/notes.md" }) -- choose the file
2.1. Sample: first export
Hello from a subtree. It has emphasis, verbatim and a link.
2.1.1. A child heading
Children of the sample become the top-level headings of the output.
2.2. Exercises: first export
Try: put the cursor on the line "Hello from a subtree" in the sample
above. Press <prefix>e, then s (the menu now says "export scope =
subtree"), then m, then M.
Expect: a vertical split with a Markdown buffer. Its whole content is:
Hello from a **subtree**. It has *emphasis*, `verbatim` and a [link](https://neovim.io). # A child heading Children of the sample become the top-level headings of the output.
The comment line (# This is the body ...) is not there, and Markdown has
no title block, so EXPORT_TITLE and EXPORT_AUTHOR are not visible.
Close the split with :q.
Try: same subtree, <prefix>e s t A (plain ASCII to a buffer).
Expect: now the title and author are centered at the top, and the link target is listed as a note after the paragraph:
_________________
MY FIRST EXPORT
Ada
_________________
Hello from a *subtree*. It has /emphasis/, `verbatim' and a [link].
[link] <https://neovim.io>
A child heading
===============
Children of the sample become the top-level headings of the output.
Try: same subtree, <prefix>e s b h H (subtree, body only, HTML).
Expect: no <!DOCTYPE>, <head> or title, just the body:
<p> Hello from a <b>subtree</b>. It has <i>emphasis</i>, <code>verbatim</code> and a <a href="https://neovim.io">link</a>. </p> <div id="outline-container-org6793350" class="outline-2"> <h2 id="org6793350">A child heading</h2>
(The org6793350 ids are computed from the content, so they are the same
on every export and change only when you edit the text.)
Try: <prefix>e h H without s: the whole file is exported. Search
the HTML buffer for My first export with /: it is not found, because
EXPORT_TITLE only applies to subtree exports; the <title> is now
"Export: hands-on examples", from the #+TITLE: line at the top.
Try: :Org export md subtree buffer with the cursor in the sample: the
same Markdown buffer as the first exercise, without the menu.
2.3. Visible only
With v on, whatever is folded at that moment is left out: fold a
subtree with <Tab> and its body disappears from the output (its heading
line is visible, so it stays). Useful to export "just the outline" or to
hide parts temporarily.
Combined with s, only the visible part of the subtree is exported; if
the subtree's own heading is folded, its body is empty (Emacs does the
same).
2.4. Sample: visible only
The intro paragraph is always visible.
2.4.1. Section one
Text of section one.
2.4.2. Section two
Text of section two.
2.5. Exercises: visible only
Try: open the sample above so you see both sections, then fold "Section
one" with <Tab> on its heading. Press <prefix>e v t A (no s: the
whole file, visible parts only). In the output, search with
/The intro paragraph.
Expect: the fold state of the whole file decides. Around the search hit you find (section numbers depend on what else is open):
The intro paragraph is always visible. 2.4.1 Section one ----------------- 2.4.2 Section two ----------------- Text of section two.
"Text of section one." is missing because it was folded.
Try: <S-Tab> until the buffer shows only the top-level headings
(OVERVIEW), then <prefix>e v t A again: the output is little more than
the table of contents and the numbered top-level headings.
2.6. Async
a only concerns PDF: with it on, LaTeX compilation (l p, l P) runs in
the background and a message says when the PDF is ready, so you can keep
editing. With the default config it already does
(export.latex.async_compile = true); a matters when you set that to
false. The other formats are fast and always synchronous.
:Org export pdf async is the command form.
2.7. The settings template (#)
<prefix>e # asks for an option category (default, html, latex,
md, …; <Tab> completes) and inserts every option with its current
value:
- without
s:#+options:lines and#+title:,#+author:,#+date:,#+email:,#+language:,#+select_tags:… keywords at the cursor; - with
s:EXPORT_OPTIONS,EXPORT_TITLE,EXPORT_AUTHOR, … properties in the drawer of the current heading.
2.7.1. Scratch heading for the template
Try: put the cursor on the heading above, press <prefix>e s # and
accept default with <CR>.
Expect: a :PROPERTIES: drawer appears under "Scratch heading for the
template". The values are the defaults (from your config), not what
this file sets:
:PROPERTIES: :EXPORT_OPTIONS: ':nil *:t -:t ::t <:t H:3 \n:nil ^:t arch:headline author:t ... :EXPORT_TITLE: 19-export :EXPORT_DATE: <2026-09-28 Mon> :EXPORT_AUTHOR: (your name) :EXPORT_EMAIL: :EXPORT_LANGUAGE: en :EXPORT_SELECT_TAGS: export :EXPORT_EXCLUDE_TAGS: noexport :EXPORT_CREATOR: Neovim 0.x.y (org.nvim, Org mode 9.8 compatible) :EXPORT_CITE_EXPORT: :END:
(the date is the day you do it). Delete what you don't need and edit the
rest; press u to take it all out again.
Try: on the empty line below, <prefix>e # (no s) and <CR>.
Expect: five #+options: lines, then #+title: 19-export, #+date:
<...>, #+author: ..., #+email:, #+language: en, #+select_tags:
export, #+exclude_tags: noexport, #+creator: ... and #+cite_export:,
inserted at the cursor. Press u: left in place they would change every
export of this file!
3. Back-ends and the tools they need
Everything marked "none" is pure Lua and works out of the box. The o
keys (h o, m o, l o, …) also open the file with your system's
viewer. p asks for a pandoc format name (rst, epub, typst,
mediawiki, asciidoc, …). PDF uses export.latex.compiler
(pdflatex by default) through latexmk when it is installed. ODT is
zipped in Lua; LibreOffice is only needed to convert it further (see
export.odt.preferred_output_format).
| Back-end | Keys (buffer / file) | External tool |
|---|---|---|
| HTML | h H / h h, h o |
none |
| Markdown | m M / m m, m o |
none |
| GitHub Markdown | m G / m g |
none |
| ASCII | t A / t a |
none |
| Latin-1 | t L / t l |
none |
| UTF-8 | t U / t u |
none |
| Org | O O / O o, O v |
none |
| LaTeX | l L / l l |
none |
- / l p, l o |
latexmk or pdflatex | |
| Beamer | l B / l b |
none |
| Beamer PDF | - / l P, l O |
latexmk or pdflatex |
| ODT | - / o o, o O |
none |
| DOCX | - / d d, d o |
pandoc |
| other formats | - / p + format name |
pandoc |
| Texinfo | - / i t |
none |
| Info | - / i i, i o |
makeinfo |
| iCalendar | - / c f, c a, c c |
none |
- ODT, DOCX, pandoc formats, Texinfo, PDF and iCalendar are always written
to files (there is no buffer variant). Only try them if you are happy
to get
examples/19-export.odtetc. in the repo (delete them after). :checkhealth orgreports which of the optional tools are installed.- Pandoc exports first run the Org back-end (macros,
#+INCLUDE,noexportare handled by org.nvim), then pipe the result to pandoc.
4. Document keywords: title, author, date, …
These keywords fill the title block (HTML <title> and <h1>, LaTeX
\title{}, the centered banner of the text export, ODT metadata):
| Keyword | Meaning | Property |
|---|---|---|
#+TITLE: |
document title | EXPORT_TITLE |
#+SUBTITLE: |
subtitle (HTML, LaTeX, text) | ..._SUBTITLE |
#+AUTHOR: |
author; default: your name | EXPORT_AUTHOR |
#+EMAIL: |
shown only with email:t |
EXPORT_EMAIL |
#+DATE: |
any text or a timestamp | EXPORT_DATE |
#+LANGUAGE: |
translates generated words | ..._LANGUAGE |
#+CREATOR: |
shown only with creator:t |
..._CREATOR |
#+KEYWORDS: |
HTML/ODT metadata | ..._KEYWORDS |
#+DESCRIPTION: |
HTML/ODT metadata | ..._DESCRIPTION |
#+EXPORT_FILE_NAME: |
output file name (no extension) | ..._FILE_NAME |
(..._X stands for EXPORT_X.) #+LANGUAGE: translates the words the
exporter writes itself: "Table of Contents", "Footnotes", "Figure", …
In a file they look like this (an example only, not live settings):
#+TITLE: Quarterly report
#+SUBTITLE: Third quarter 2026
#+AUTHOR: Ada Lovelace
#+EMAIL: ada@example.org
#+DATE: <2026-10-01 Thu>
#+LANGUAGE: en
#+OPTIONS: email:t toc:nil
#+EXPORT_FILE_NAME: q3-report
4.1. Sample: title block
Revenue went up.
4.2. Exercises: title block
Try: cursor on "Revenue went up.", <prefix>e s t A.
Expect: a banner with the title, the subtitle, the author, the e-mail
(because of email:t) and the date:
____________________
QUARTERLY REPORT
Third quarter 2026
Ada Lovelace
ada@example.org
____________________
<2026-10-01 Thu>
Revenue went up.
Try: <prefix>e s h H and look at the top of the HTML buffer.
Expect: the title in <head>, and as the first heading with the
subtitle under it:
<title>Quarterly report</title> <meta name="author" content="Ada Lovelace" /> ... <h1 class="title">Quarterly report <br /> <span class="subtitle">Third quarter 2026</span> </h1>
and at the end a postamble with the date, author, e-mail link and the
creation time of the export (timestamp:t):
<div id="postamble" class="status"> <p class="date">Date: 2026-10-01 Thu 00:00</p> <p class="author">Author: Ada Lovelace</p> <p class="email">Email: <a href="mailto:ada@example.org">ada@example.org</a></p> <p class="date">Created: 2026-09-28 Mon 15:13</p>
Try: <prefix>e s l L (LaTeX to a buffer).
Expect: the e-mail becomes a \thanks, the subtitle a second title line:
\author{Ada Lovelace\thanks{ada@example.org}}
\date{\textit{<2026-10-01 Thu>}}
\title{Quarterly report\\\medskip
\large Third quarter 2026}
Try: change email:t to email:nil in EXPORT_OPTIONS and export as
ASCII again: the ada@example.org line disappears. With date:nil the
date goes, with author:nil the author.
4.4. Exercises: another language
Try: <prefix>e s t U (UTF-8 text to a buffer).
Expect: the words the exporter generates are in French:
Table des matières ────────────────── 1. Première partie Voir la note[1]. 1 Première partie ═════════════════ Du texte. Notes de bas de page ──────────────────── [1] Une note de bas de page.
Try: <prefix>e s t A (plain ASCII): the table of contents is now
titled Sommaire, the ASCII-only form of the French dictionary.
Try: change fr to de and export again: Inhaltsverzeichnis and
Fußnoten.
5. #+OPTIONS: the export switches
#+OPTIONS: takes key:value pairs separated by spaces; in a subtree the
same pairs go in EXPORT_OPTIONS. Several #+OPTIONS: lines add up. Values
are Emacs Lisp: t (yes), nil (no), numbers, strings, lists like
("TODO" "NEXT"). The defaults come from the export table of your
config (with_toc, headline_levels, …).
| Option | Default | Meaning |
|---|---|---|
toc: |
t |
table of contents; a number = its depth |
num: |
t |
section numbers; a number = how deep |
H: |
3 |
deeper headings become list items |
^: |
t |
a_b, a^b; {} only a_{b}; nil off |
*: |
t |
emphasis (*bold*, /italic/, …) |
tags: |
t |
headline tags; not-in-toc |
todo: |
t |
TODO keywords |
pri: |
nil |
priority cookies [#A] |
tasks: |
t |
TODO entries: nil, todo, done, list |
stat: |
t |
statistics cookies [1/3] |
prop: |
nil |
property drawers; t or a list of names |
d: |
see below | drawers: t, nil, list, (not ...) |
p: |
nil |
SCHEDULED, DEADLINE and CLOSED lines |
c: |
nil |
CLOCK lines |
<: |
t |
paragraphs made only of timestamps |
timestamp: |
t |
creation time (HTML postamble) |
f: |
t |
footnotes |
\n: |
nil |
keep every line break |
': |
nil |
smart quotes |
-: |
t |
--, ---, ... as dashes and ellipsis |
e: |
t |
entities like \alpha |
tex: |
t |
LaTeX fragments; verbatim, nil |
\vert: |
t |
tables (the key is a pipe character) |
:: |
t |
fixed-width lines (: text) |
arch: |
headline |
archived trees: t, nil, headline |
inline: |
t |
inline tasks |
title: |
t |
the title |
author: |
t |
the author |
date: |
t |
the date |
email: |
nil |
the e-mail |
creator: |
nil |
the creator string |
broken-links: |
nil |
nil error, t drop, mark mark |
The default of d: is (not "LOGBOOK"): every drawer but LOGBOOK. In
the table the pipe key is shown as \vert: because a bare | would
split the cell; in #+OPTIONS: you write |:nil.
5.1. Sample: toc, num and H
Intro.
5.1.2. Another chapter
Text.
5.2. Exercises: toc, num and H
Try: <prefix>e s t A.
Expect: a table of contents with two levels, numbered sections, and the
third level turned into a list item (a * bullet) under 1.1:
Table of Contents _________________ 1. Chapter .. 1. Section 2. Another chapter Intro. 1 Chapter ========= 1.1 Section ~~~~~~~~~~~ * 1.1.1 Too deep to be a section This one becomes a list item. 2 Another chapter ================= Text.
Try: change EXPORT_OPTIONS to toc:nil num:1 H:2 title:nil author:nil
and export again: no table of contents, and only the first level is
numbered: 1 Chapter, then Section without a number, then
* Too deep to be a section, then 2 Another chapter.
Try: H:3 instead of H:2: "Too deep to be a section" is a real
(sub-sub)section again, underlined with dashes.
5.3. Sample: sub- and superscripts
file_name and x^2 stay as they are, but H2O and E = mc2 are converted.
5.4. Exercises: sub- and superscripts
Try: <prefix>e s b m M (body only, Markdown).
Expect:
file\_name and x^2 stay as they are, but H<sub>2</sub>O and E = mc<sup>2</sup> are converted.
Try: change ^:{} to ^:t and export again: file_name becomes
file<sub>name</sub> and x^2 becomes x<sup>2</sup> too. With ^:nil nothing is converted. ^:{} is
the usual choice for documents full of snake_case names.
5.5. Sample: tags, TODO keywords and priorities
5.5.1. TODO Write the report  work
5.5.2. DONE Book the room  office
5.5.3. NEXT Plan the offsite [1/2]
[X]pick a date[ ]pick a place
5.6. Exercises: tags, TODO keywords and priorities
Try: <prefix>e s b m M.
Expect: keywords, priorities, cookies and tags are all there (the
statistics cookie is wrapped in <code>, like Emacs does):
# TODO [#A] Write the report :work: # DONE Book the room :office: # NEXT [#C] Plan the offsite <code>[1/2]</code> - [X] pick a date - [ ] pick a place
Try: set EXPORT_OPTIONS to toc:nil num:nil title:nil author:nil
tags:nil todo:nil pri:nil stat:nil (one line) and export again: the
headings become plain # Write the report, # Book the room and
# Plan the offsite; the checklist stays.
Try: replace tags:t todo:t pri:t by tasks:todo: only the not-done
entries are exported (# TODO Write the report :work: and
# NEXT Plan the offsite <code>[1/2]</code>; the priority is gone too
because pri: is nil by default). tasks:done keeps only "Book the
room", tasks:("NEXT") only "Plan the offsite", tasks:nil drops all
three.
5.7. Sample: drawers, planning, clocks and timestamps
5.7.1. DONE Ship the release
Remember to tag the commit.
The release went out on time.
5.8. Exercises: drawers, planning, clocks and timestamps
Try: <prefix>e s b t A.
Expect: by default only the heading, the NOTES drawer (every drawer but LOGBOOK is exported), the lone timestamp and the paragraph:
DONE Ship the release ===================== Remember to tag the commit. <2026-10-05 Mon> The release went out on time.
Try: one at a time, add these to EXPORT_OPTIONS and export again
(each adds or removes lines between the underline and "Remember to tag"):
p:taddsCLOSED: [2026-09-25 Fri 17:02] SCHEDULED: <2026-09-24 Thu>;prop:taddsVERSION: 2.1andOWNER: Ada;prop:("OWNER")onlyOWNER: Ada;c:talone changes nothing: the clock line is inside LOGBOOK, which is still excluded.c:t d:t(all drawers) showsCLOCK: [2026-09-24 Thu 09:00]--[2026-09-24 Thu 11:30] => 2:30;d:nilremoves "Remember to tag the commit." (no drawers at all);d:("NOTES")exports only the NOTES drawer (same output as now);<:nilremoves<2026-10-05 Mon>, the paragraph made only of a timestamp (an empty line is left in its place).
5.9. Sample: line breaks, quotes, special strings
Roses are red, violets are blue. "Quoted" text – with an en dash — and an em dash…
5.10. Exercises: line breaks, quotes, special strings
Try: <prefix>e s b h H.
Expect: each line ends with <br /> (from \n:t), the quotes become
curly (':t) and the dashes and dots entities (-:t):
<p> Roses are red,<br /> violets are blue.<br /> “Quoted” text – with an en dash — and an em dash…<br /> </p>
Try: set EXPORT_OPTIONS to toc:nil title:nil author:nil \n:nil ':nil
-:nil and export again: the three lines come back as typed, with
straight quotes, --, --- and ..., and no <br />.
5.11. Sample: what to leave out entirely
5.12. Exercises: what to leave out entirely
Try: <prefix>e s b m M.
Expect: only one line: the asterisks stay literal (*:nil), \alpha
stays as typed (e:nil), no footnote, no table, no fixed-width line.
Markdown escapes the characters that would otherwise be markup, so you see
backslashes:
A \*bold\* claim\\alpha with a footnote.
Try: remove *:nil e:nil and export again. Now the emphasis is
converted and the entity is written as HTML:
A **bold** claimα with a footnote.
6. Choosing what is exported
6.1. Tags: noexport and export
- A heading tagged
:noexport:is removed with its whole subtree. - If any heading carries an
:export:tag, only the tagged subtrees are exported (in a whole-file export the text before the first heading is kept too). #+EXCLUDE_TAGS:/#+SELECT_TAGS:(or theEXPORT_EXCLUDE_TAGS/EXPORT_SELECT_TAGSproperties) replace those tag lists. Tags are inherited: a child of a:noexport:heading goes too.
6.2. Sample: noexport
6.2.1. Kept
Public text.
6.2.2. Also kept
More public text.
6.3. Exercises: noexport
Try: <prefix>e s b m M.
Expect: two headings only, "Kept" and "Also kept"; no "Private text":
# Kept Public text. # Also kept More public text.
6.4. Sample: select tags
Intro text of the sample.
6.4.1. Chosen  keep
In.
6.4.2. Not chosen
Out: no keep tag, and another heading has one.
6.4.3. Chosen but secret  keep secret
Out: exclude tags win.
6.5. Exercises: select tags
Try: <prefix>e s b m M.
Expect: only the heading "Chosen". Even the intro text is dropped: in a subtree export it belongs to the sample heading, which is not selected (Emacs does the same).
# Chosen In.
Try: remove the keep tag from both "Chosen" headings (edit the
lines, or <prefix>t on each heading and delete keep from the prompt).
Now no heading is selected, so the select tags do not apply at all:
Intro text of the sample. # Chosen In. # Not chosen Out: no keep tag, and another heading has one.
"Chosen but secret" is still excluded by its secret tag. Press u to
restore the tags.
6.6. Sample: COMMENT headings, comment lines and blocks
Visible paragraph.
6.6.1. Finished part
Done.
6.7. Exercises: COMMENT headings, comment lines and blocks
Try: <prefix>e s b m M.
Expect:
Visible paragraph. # Finished part Done.
Try: put the cursor on the "COMMENT Work in progress" heading and press
<prefix>hC (toggle COMMENT, Emacs C-c ;): the word COMMENT goes away.
Export again: "Work in progress" and its text are now exported between
"Visible paragraph." and "Finished part". Press <prefix>hC again to put
it back.
6.8. Sample: archived trees
6.8.1. Current work
Live.
6.8.2. Old project  ARCHIVE
6.9. Exercises: archived trees
Try: <prefix>e s b m M.
Expect: "Old project" appears as a heading, but "Old details." is gone
(arch:headline, the default):
# Current work Live. # Old project
Try: add arch:t to EXPORT_OPTIONS: "Old details." comes back. With
arch:nil the "Old project" heading goes too.
7. Subtree properties (EXPORT_*)
When you export a subtree, every export keyword can be set in its drawer as
EXPORT_<KEYWORD>: EXPORT_TITLE, EXPORT_AUTHOR, EXPORT_DATE,
EXPORT_EMAIL, EXPORT_OPTIONS, EXPORT_FILE_NAME, EXPORT_LANGUAGE,
EXPORT_SELECT_TAGS, EXPORT_EXCLUDE_TAGS, and the back-end ones
(EXPORT_HTML_HEAD, EXPORT_LATEX_CLASS, EXPORT_LATEX_HEADER, …).
EXPORT_OPTIONSis merged with#+OPTIONS: keys it names win, others keep the file value.- Without
EXPORT_TITLE, a subtree export is titled after the heading. - These properties are ignored when the whole file is exported.
7.1. Sample: a subtree is its own document
A standalone page made from one heading.
7.2. Exercises: a subtree is its own document
Try: <prefix>e s h H.
Expect: <title>Sample: a subtree is its own document</title>, the meta
line from EXPORT_HTML_HEAD inside <head>, and "Author: Grace" in the
postamble.
Try (writes a file outside the repo): <prefix>e s m m. Because of
EXPORT_FILE_NAME, the message says Exported to /tmp/org-nvim-sample.md
(the extension is added for you). A relative name would be relative to
this file, i.e. inside examples/.
8. Table of contents
toc:t/toc:nil/toc:2in#+OPTIONS:control the table at the top.#+TOC: headlines 2puts a table of contents where the keyword is; addlocalfor only the headings below the current one.#+TOC: tablesand#+TOC: listingslist the captioned tables and source blocks.- A heading with
:UNNUMBERED: thas no number;:UNNUMBERED: notocalso keeps it out of the table of contents.
8.1. Sample: tables of contents
Table of Contents
- 1. How to use this file
- 2. The export dispatcher
- 3. Back-ends and the tools they need
- 4. Document keywords: title, author, date, …
- 5. #+OPTIONS: the export switches
- 6. Choosing what is exported
- 7. Subtree properties (EXPORT_*)
- 8. Table of contents
- 9. Captions, names and cross-references
- 10. Footnotes in export
- 11. Macros
- 12. Raw output for one back-end
- 13. HTML specifics: #+ATTR_HTML and #+HTML_HEAD
- 14. LaTeX and PDF specifics
- 15. Beamer slides
- 16. Markdown, GFM, plain text and Org
- 17. #+INCLUDE: pulling in other files
- 18. Source blocks and :exports
- 19. Citations
- 20. Broken links
- 21. iCalendar, ODT, DOCX, Texinfo and pandoc (file exports)
- 22. Publishing projects
- 23. Configuring defaults
- 24. Further reading
Preface
No number here.
Colophon
Not in the table of contents.
8.2. Exercises: tables of contents
Try: <prefix>e s b t A.
Expect: a first list with the level-1 headings (Preface without a
number, 1. Setup, no Colophon), then under "1 Setup" a local list with
only its children:
Table of Contents _________________ Preface 1. Setup Preface ======= No number here. 1 Setup ======= .. 1. Install .. 2. Configure 1.1 Install ~~~~~~~~~~~ 1.2 Configure ~~~~~~~~~~~~~ Colophon ======== Not in the table of contents.
Try: change #+TOC: headlines 1 to #+TOC: headlines 2: the first list
now also shows .. 1. Install and .. 2. Configure under 1. Setup.
9. Captions, names and cross-references
#+CAPTION:before a table, image or source block gives it a caption; exported it is numbered: "Table 1:", "Figure 1:", "Listing 1:".#+NAME:gives it a name;[[name]]links to it and is replaced by its number on export.[[*Heading]]links to a heading (by its text),[[#my-id]]to a heading with:CUSTOM_ID: my-id,<<target>>is an anchor you link to with[[target]], and<<<radio target>>>turns every occurrence of the words into a link.- A link with a description shows the description; without one, a link to a numbered heading shows the section number, a link to a named table its table number.
9.1. Sample: cross-references
9.1.1. Data
9.1.2. Discussion
See table 1, listing 1 and section 9.1.1. The same section by id: the data section. Never skip step 2.
9.2. Exercises: cross-references
Try: <prefix>e s b h H and look for "Discussion".
Expect: the captions are numbered, the named elements and the target get
ids, and the links point to them. The heading with a CUSTOM_ID uses it
as its id (data); the other ids look like org plus 7 hex digits:
<h2 id="data"><span class="section-number-2">1.</span> Data</h2> <table id="orgc141a8c" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides"> <caption class="t-above"><span class="table-number">Table 1:</span> Monthly sales</caption> ... <label class="org-src-name"><span class="listing-number">Listing 1: </span>Doubling a number</label><pre class="src src-lua" id="org608ce3d"><code>return 2 * 21 ... <li><a id="org7457e97"></a>Check the totals.</li> ... See table <a href="#orgc141a8c">1</a>, listing <a href="#org608ce3d">1</a> and section <a href="#data">1</a>. The same section by id: <a href="#data">the data section</a>. Never skip step <a href="#org7457e97">2</a>.
A link to a <<target>> without a description shows the number of what
holds the target: here the list item, so "step 2".
(The generated ids are computed from the content, so they stay the same from one export to the next.)
Try: <prefix>e s b t A: in plain text the references are just the
numbers, and the table and the listing get their captions below them:
Month Units -------------- Oct 12 Nov 17 Table 1: Monthly sales ,---- | return 2 * 21 `---- Listing 1: Doubling a number ... See table 1, listing 1 and section 1. The same section by id: [the data section]. Never skip step 2. [the data section] See section 1
(The last line is the plain-text version of a described link: a note after the section.)
Try: in the Discussion paragraph, replace [[*Data]] by [[*Dataa]] and
export again: the link no longer resolves. Thanks to broken-links:mark at
the top of this file you get [BROKEN LINK: *Dataa] instead of an error
(see "Broken links" below). Press u.
10. Footnotes in export
Footnotes are numbered in order of first reference and collected at the
end of the document (HTML: a "Footnotes" section; LaTeX: real
\footnote{}; Markdown: a "Footnotes" section with links; text: a
"Footnotes" section). Named [fn:name], anonymous inline [fn::text] and
named inline [fn:name:text] footnotes all work. f:nil drops them.
10.2. Exercises: footnotes
Try: <prefix>e s b t A.
Expect: references become [1] and [2] (the second use of sample
is [1] again), with a footnotes section at the end:
A named note[1], an inline one[2] and the named note again[1]. ... Footnotes _________ [1] The definition of the named note. [2] Defined right here.
More on footnotes: 14-footnotes.org.
11. Macros
#+MACRO: name replacement text defines a macro; {{{name}}} uses it.
$1, $2 … are the arguments (separated by commas; \, is a literal
comma). Macros are expanded on export only, anywhere in the text.
Built-in macros:
| Macro | Expands to |
|---|---|
{{{title}}} |
the document title |
{{{author}}} {{{email}}} |
author, e-mail |
{{{date}}}, {{{date(%Y)}}} |
the #+DATE (formatted if a timestamp) |
{{{time(%H:%M)}}} |
the time of the export |
{{{modification-time(%F)}}} |
the file's modification time |
{{{input-file}}} |
the file name |
{{{keyword(NAME)}}} |
the value of #+NAME: |
{{{property(NAME)}}} |
a property of the current heading |
{{{n}}}, {{{n(name)}}} |
a counter (per name), n(name,-) repeats |
{{{results(x)}}} |
how inline babel results are wrapped |
Your config can define global ones: export = { global_macros = { ... } }
(strings, or Lua functions receiving the arguments).
11.1. Sample: macros
Hello, world! two before one. This is "Export: hands-on examples" by org.nvim examples, exported from 19-export.org. Step 1, step 2, step 3; again step 3. Press C-c C-e.
11.1.1. Owned part
This part is owned by Charles.
11.2. Exercises: macros
Try: <prefix>e s b t A.
Expect:
Hello, world! two before one. This is "Export: hands-on examples" by org.nvim examples, exported from 19-export.org. Step 1, step 2, step 3; again step 3. Press . Owned part ========== This part is owned by Charles.
Things to notice:
{{{title}}}and{{{author}}}are the file's#+TITLE:and#+AUTHOR:, not the sample'sEXPORT_TITLE(Emacs does the same).- The
kbdmacro produced nothing in plain text: it expands to an HTML export snippet (next section). With<prefix>e s b h Hthe line readsPress <kbd>C-c C-e</kbd>. {{{property(OWNER)}}}reads the heading it is written under. Text right under the exported heading reads that heading's own drawer: in the sample,{{{property(EXPORT_TITLE)}}}would giveMacro demo.
Try: add a line {{{greet(Neovim\, again)}}} to the sample and export:
Hello, Neovim, again! (the escaped comma is not an argument separator).
12. Raw output for one back-end
Sometimes you want to write HTML or LaTeX directly. Three ways, all passed through untouched to their back-end and dropped by all others:
- export snippets inside a paragraph:
@@html:<mark>@@text@@html:</mark>@@,@@latex:\newpage@@,@@md:...@@,@@ascii:...@@; - one-line keywords:
#+HTML: ...,#+LATEX: ...,#+ASCII: ...,#+MD: ...,#+ODT: ...,#+BEAMER: ...,#+TEXINFO: ...; - export blocks:
#+begin_export html…#+end_export(alsolatex,md,ascii,odt, …). Insert one with<prefix>ib(EmacsC-c C-,) thenh(html),l(latex),a(ascii) orE(asks for the back-end); edit its content in a split with<prefix>'.
12.1. Sample: snippets and export blocks
This word is highlighted in HTML, emphasized in LaTeX.
The end.
12.2. Exercises: snippets and export blocks
Try: <prefix>e s b h H.
Expect: the HTML parts only:
<p> This word is <mark>highlighted</mark> in HTML, emphasized in LaTeX. </p> <hr class="fancy" /> <div class="note">Only in HTML.</div> <p> The end. </p>
Try: <prefix>e s b t A.
Expect: no markup at all, and the ascii block:
This word is highlighted in HTML, emphasized in LaTeX. Only in plain text. The end.
Try: <prefix>e s b l L.
Expect: the LaTeX parts:
This word is highlighted in HTML, \emph{emphasized} in LaTeX.
\newpage
\begin{center}Only in \LaTeX.\end{center}
The end.
13. HTML specifics: #+ATTR_HTML and #+HTML_HEAD
#+ATTR_HTML: :class wide :style color: redbefore a table, image, link-only paragraph, list or block adds those HTML attributes. For a link, the attributes go to the<a>(or<img>) element.#+HTML_HEAD:and#+HTML_HEAD_EXTRA:add lines to<head>(CSS, meta tags); in a subtree useEXPORT_HTML_HEAD.#+HTML_DOCTYPE: html5and#+OPTIONS: html5-fancy:tgive HTML5 elements (<section>,<figure>, …).html-postamble:nilremoves the footer,html-style:nilthe default CSS.#+HTML_LINK_HOME:/#+HTML_LINK_UP:add navigation links,#+HTML_CONTAINER:changes thedivaround sections.
A file set up for HTML (example, not live):
#+TITLE: Team page
#+HTML_DOCTYPE: html5
#+OPTIONS: html5-fancy:t html-postamble:nil toc:nil
#+HTML_HEAD: <link rel="stylesheet" href="style.css" />
#+HTML_HEAD_EXTRA: <meta name="theme-color" content="#336699" />
13.1. Sample: HTML attributes
13.2. Exercises: HTML attributes
Try: <prefix>e s h H.
Expect: the style line at the end of <head>, and in the body:
<style>.wide { width: 100%; }</style>
</head>
...
<table id="team" border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides" class="wide">
...
<p target="_blank" title="Neovim home page">
<a href="https://neovim.io" target="_blank" title="Neovim home page">Neovim</a>
</p>
<ul class="org-ul checklist">
The :id replaced the generated table id, the :class was added to the
default attributes (for lists, to the org-ul class). For a paragraph
holding only a link, the attributes land on both the <p> and the <a>,
exactly like Emacs. The page ends right after the content: no postamble
(html-postamble:nil).
14. LaTeX and PDF specifics
#+LATEX_CLASS: article(default),report,book,beamer… fromexport.latex.classes;#+LATEX_CLASS_OPTIONS: [a4paper,11pt].#+LATEX_HEADER: \usepackage{xcolor}adds preamble lines (EXPORT_LATEX_HEADERin a subtree);#+LATEX_HEADER_EXTRA:too.#+ATTR_LATEX:before a table::environment longtable,:align l|r,:booktabs t,:float nil,:placement [H],:caption; before an image::width 0.5\textwidth; before a list,:options.- LaTeX fragments (
$E=mc^2$,\(...\),\begin{equation}) pass through to LaTeX; HTML shows them with MathJax. - PDF (
l p) writes the .tex file next to this one and runslatexmk(orpdflatexthree times). Without a TeX installation you get an error message and only the .tex file.
14.1. Sample: LaTeX attributes
| Test | Score |
|---|---|
| A | 91 |
Inline math \(a^2 + b^2 = c^2\) and a display:
\begin{equation} e^{i\pi} + 1 = 0 \end{equation}14.2. Exercises: LaTeX attributes
Try: <prefix>e s l L.
Expect: the class, its options and the extra package in the preamble:
\documentclass[a4paper]{report}
...
\usepackage{booktabs}
and in the body a table float with [h], the lr column spec and
booktabs rules:
\begin{table}[h]
\caption{Results}
\centering
\begin{tabular}{lr}
\toprule
Test & Score\\
\midrule
A & 91\\
\bottomrule
\end{tabular}
\end{table}
The math is copied as it is. With the report class, level-1 headings
would be \chapter instead of \section.
15. Beamer slides
Beamer is LaTeX for presentations. By default level-1 headings are frames
(slides); H:2 makes level 2 the frames and level 1 sections. Properties
refine it: BEAMER_env (block, alertblock, example, columns,
column, note, ignoreheading, …), BEAMER_col (column width),
BEAMER_act (overlay like <2->), BEAMER_opt (frame options).
#+BEAMER_THEME: (EXPORT_BEAMER_THEME) picks the theme. l B exports
to a buffer; l P makes a PDF (needs LaTeX).
15.1. Sample: slides
15.1.1. First slide
- point one
- point two
15.2. Exercises: slides
Try: <prefix>e s l B.
Expect: a Beamer document with the theme, a title frame, then one frame per level-1 heading of the sample:
\documentclass[presentation]{beamer}
...
\usetheme{Madrid}
\author{Ada}
\date{\today}
\title{A tiny talk}
...
\maketitle
\begin{frame}[label={sec:orgcc50823}]{First slide}
\begin{itemize}
\item point one
\item point two
\end{itemize}
\end{frame}
\begin{frame}[label={sec:orgcd668b6}]{Two columns}
\begin{columns}
\begin{column}{0.5\columnwidth}
Text on the left.
\end{column}
\begin{column}{0.5\columnwidth}
\begin{alertblock}{Right}
Careful!
\end{alertblock}
\end{column}
\end{columns}
\end{frame}
16. Markdown, GFM, plain text and Org
16.1. Sample: a table and code everywhere
[X]done item[ ]open item
| Tool | Needs |
|---|---|
| md | nothing |
print("hi")
16.2. Exercises: a table and code everywhere
Try: <prefix>e s b m M (plain Markdown).
Expect: Markdown has no table syntax, so the table is written as HTML; the code block is indented by four spaces:
- [X] done item
- [ ] open item
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
...
print("hi")
Try: <prefix>e s b m G (GitHub flavoured Markdown).
Expect: task-list items, a pipe table (not padded, which GitHub does not need) and a fenced block with the language:
- [x] done item
- [ ] open item
| Tool | Needs |
|---|---|
| md | nothing |
```python
print("hi")
```
Try: <prefix>e s b t A (ASCII).
Expect:
- [X] done item
- [ ] open item
Tool Needs
---------------
md nothing
,----
| print("hi")
`----
Try: <prefix>e s b t U (UTF-8).
Expect: the same drawn with Unicode characters:
• ☑ done item
• ☐ open item
━━━━━━━━━━━━━━━
Tool Needs
───────────────
md nothing
━━━━━━━━━━━━━━━
┌────
│ print("hi")
└────
t L (Latin-1) sits in between: Latin-1 characters where they exist,
ASCII otherwise.
Try: <prefix>e s b O O (Org back-end).
Expect: the subtree comes back as Org, after macros, #+INCLUDE and
noexport have been processed (useful to see exactly what the other
back-ends receive). Note the code indented by two spaces, like Emacs:
- [X] done item
- [ ] open item
| Tool | Needs |
|------+---------|
| md | nothing |
#+begin_src python :exports code
print("hi")
#+end_src
17. #+INCLUDE: pulling in other files
#+INCLUDE: "file" is replaced by the file's content on export (never in
the buffer). Variants:
#+INCLUDE: "notes.org": an Org file; its headings are adjusted to the current level (:minlevel Nto choose).#+INCLUDE: "notes.org::*Heading": one subtree;::#custom-idor::namealso work;:only-contents tdrops the heading line.#+INCLUDE: "init.lua" src lua: as a source block;example,export htmlalso work.:lines "5-10"(or"5-","-10") takes a line range (the end is exclusive, like Emacs:"1-4"is lines 1 to 3).
17.1. Sample: include
The first lines of the bundled init file:
-- Try org.nvim without touching your own config:
--
-- nvim -u examples/minimal_init.lua examples/tutorial.org
And a section of the tutorial:
Export options go in #+OPTIONS: at the top of a file, for example
#+OPTIONS: toc:2 num:nil ^:{} todo:nil. #+TITLE:, #+AUTHOR: and
17.2. Exercises: include
Try: <prefix>e s b m M.
Expect: the three comment lines of minimal_init.lua as a code block,
followed by the first two lines of the tutorial's "Export settings"
section:
The first lines of the bundled init file:
-- Try org.nvim without touching your own config:
--
-- nvim -u examples/minimal_init.lua examples/tutorial.org
And a section of the tutorial:
Export options go in `#+OPTIONS:` at the top of a file, for example
`#+OPTIONS: toc:2 num:nil ^:{} todo:nil`. `#+TITLE:`, `#+AUTHOR:` and
#+SETUPFILE: "other.org" is related: it reads the settings keywords
(#+OPTIONS, #+MACRO, #+TODO, …) of another file.
18. Source blocks and :exports
The :exports header argument decides what a code block contributes:
:exports |
Exported |
|---|---|
code |
the code only (default for most languages) |
results |
the result only |
both |
code, then result |
none |
nothing |
With babel.evaluate_on_export = true (the default) blocks exporting
results or both are run again during export, in a copy of the buffer
(the buffer itself is not changed), after the usual "Evaluate?"
confirmation. :eval never-export (or no-export) keeps the #+RESULTS:
already in the buffer instead. More in 17-babel.org.
18.1. Sample: exports
(+ 1 2)
(* 6 7)
(concat "org" "." "nvim")
(message "invisible")
(* 100 100)
stale value kept on export
The answer is (* 6 7).
18.2. Exercises: exports
Try: <prefix>e s b t A. You are asked "Evaluate this emacs-lisp code
block on your system?" three times (the results block, the both block
and the inline src_ call): answer y each time. (Emacs Lisp runs in
emacs --batch when Emacs is installed, otherwise on org.nvim's own Lisp
interpreter, which handles these simple expressions.)
Expect: code and results in the text back-end's boxes; the inline
result is verbatim (`42'):
,---- | (+ 1 2) `---- ,---- | 42 `---- ,---- | (concat "org" "." "nvim") `---- ,---- | org.nvim `---- ,---- | stale value kept on export `---- The answer is `42'.
The :exports none block is absent, and the never-export block shows
its old #+RESULTS: instead of 10000. The buffer is not modified: no
#+RESULTS: was added under the other blocks.
Try: export again and answer n to every question: the results
blocks then export nothing (they have no #+RESULTS: in the buffer), the
both block only its code, and the inline call is left empty.
19. Citations
Citations are written [cite:@key] (styles: [cite/t:@key] text,
[cite/a:@key] author, [cite/na:@key] no author, …; prefixes and
suffixes: [cite:see @key p. 3]). #+BIBLIOGRAPHY: names a .bib or
CSL-JSON file and #+PRINT_BIBLIOGRAPHY: prints the list. The "basic"
processor works with every back-end; LaTeX can use natbib, biblatex or
bibtex with #+CITE_EXPORT:. CSL styles (citeproc) are not supported;
for those, export to Org or Markdown and run pandoc --citeproc.
This file's header has #+BIBLIOGRAPHY: ../tests/fixtures/export/cite/refs.bib
(a test fixture of the repo).
19.1. Sample: citations
As shown before (Doe, John and Smith, Jane, 2020), and in a book (see Zed, Anna, 2019 p. 3). Alpha, Bob (2018) wrote a thesis.
Alpha, Bob (2018). Thesis, Univ.
Doe, John and Smith, Jane (2020). On the TeXbook and \(\alpha\) α things, Journal of Tests.
Zed, Anna (2019). A Book of Strings, ACME Press.
19.2. Exercises: citations
Try: <prefix>e s b t A.
Expect: author-year citations, and the bibliography sorted by author
where #+PRINT_BIBLIOGRAPHY: is:
As shown before (Doe, John and Smith, Jane, 2020), and in a book (see Zed, Anna, 2019 p. 3). Alpha, Bob (2018) wrote a thesis. Alpha, Bob (2018). /Thesis/, Univ. Doe, John and Smith, Jane (2020). /On the TeXbook and $\alpha$ alpha things/, Journal of Tests. Zed, Anna (2019). /A Book of Strings/, ACME Press.
Try: <prefix>e s b h H: the same text in <p> elements, with the
titles in <i> and the $\alpha$ of the .bib title as MathJax
\(\alpha\).
Try: change [cite:@doe2020] to [cite/na:@doe2020] (no author):
As shown before (2020). And [cite:see @zed2019 p. 3] to
[cite/nb:@zed2019] (numeric): in a book (3), the entry's position in
the bibliography.
20. Broken links
A link that points nowhere ([[*No such heading]]) stops the export with
an error by default: better than a silently dead link.
#+OPTIONS: broken-links:mark writes [BROKEN LINK: ...] instead, and
broken-links:t drops the link. This file sets broken-links:mark at
the top so that a whole-file export works despite the sample below.
20.1. Sample: broken links
This points to [BROKEN LINK: *A heading that does not exist].
20.2. Exercises: broken links
Try: <prefix>e s b t A.
Expect: This points to [BROKEN LINK: *A heading that does not exist].
Try: change broken-links:mark to broken-links:nil in
EXPORT_OPTIONS and export again. No buffer opens; instead:
Export failed: Org export aborted. Unable to resolve link: "*A heading that does not exist" See export.with_broken_links (org-export-with-broken-links)
Try: broken-links:t: the link simply disappears (This points to .).
21. iCalendar, ODT, DOCX, Texinfo and pandoc (file exports)
These write files; there is no buffer variant. If you try them here, the
files land in examples/ (delete them afterwards).
- iCalendar (
c f): every entry with an active timestamp, SCHEDULED or DEADLINE becomes a VEVENT (and TODOs a VTODO withexport.icalendar.include_todo).c awrites one .ics per agenda file,c ccombines them intoexport.icalendar.combined_agenda_file(~/org.icsby default, outside the repo). - ODT (
o o): a real OpenDocument file written in pure Lua; opens in LibreOffice, Word, Google Docs.export.odt.preferred_output_format = "docx"converts it with LibreOffice. - DOCX (
d d) and other formats (p, then e.g.rst,epub,typst): pandoc converts the Org back-end's output. The file is always named after the Org file (examples/19-export.docx), even in a subtree withEXPORT_FILE_NAME. - Texinfo (
i t) writes a .texi manual;i ialso runsmakeinfo.
21.1. Sample: calendar entries
21.1.1. Team meeting
21.1.2. Submit the report
21.2. Exercises: calendar entries
Try (writes examples/19-export.ics): <prefix>e c f. The dispatcher's
iCalendar entries always export the whole file, so the three
"Evaluate?" questions of the :exports sample come up again: answer n.
Open the file with :e examples/19-export.ics.
Expect: among others
BEGIN:VEVENT DTSTART:20261007T100000 DTEND:20261007T110000 SUMMARY:Team meeting ... BEGIN:VEVENT DTSTART;VALUE=DATE:20261015 DTEND;VALUE=DATE:20261016 SUMMARY:DL: Submit the report
and an event for <2026-10-05 Mon> of the "Ship the release" sample. A
TODO entry's deadline becomes a VTODO only with
export.icalendar.include_todo; that is why "Submit the report" has no
TODO keyword. Afterwards: :!rm examples/19-export.ics.
Try (writes examples/19-export.odt): <prefix>e s o o, open the file in
LibreOffice (or <prefix>e s o O to open it right away), then delete it.
22. Publishing projects
Publishing exports whole directories at once (a website, a set of PDFs):
projects are set in your config under export.publish.projects, and only
files changed since the last run are exported again. Dispatcher: P f
(this file), P p (its project), P x (choose one), P a (all). The
commands are :Org publish, :Org publish NAME, :Org publish all
force (force re-exports even unchanged files).
This is configuration, not something to run from here:
require("org").setup({
export = {
publish = {
projects = {
notes = {
base_directory = "~/org/site", -- the .org sources
base_extension = "org",
publishing_directory = "~/public_html",
publishing_function = "html", -- or "pdf", "md", "org", ...
recursive = true,
exclude = "^drafts/", -- Vim regex, relative path
auto_sitemap = true, -- writes sitemap.org + .html
sitemap_title = "My notes",
with_toc = false, -- any export option
html_postamble = false,
},
static = {
base_directory = "~/org/site",
base_extension = "css\\|png\\|jpg",
publishing_directory = "~/public_html",
recursive = true,
publishing_function = "attachment", -- copy as is
},
site = { components = { "notes", "static" } },
},
},
},
})
Then :Org publish site builds both. The timestamps of published files
are kept in export.publish.timestamp_directory.
Try: <prefix>e P x: with the bundled init no project is configured, so
the prompt offers nothing to choose; press <Esc>.
23. Configuring defaults
Every #+OPTIONS key has a config default under export, named after the
Emacs variable: with_toc, with_section_numbers, headline_levels,
with_tags, with_todo_keywords, with_priority, with_drawers,
with_properties, with_broken_links, select_tags, exclude_tags,
author, email, … and per back-end tables (export.html,
export.latex, export.md, export.ascii, export.odt, …).
require("org").setup({
export = {
output_dir = "~/exports", -- instead of next to the source file
open_after_export = false, -- open every exported file
with_toc = false,
with_section_numbers = false,
author = "Ada Lovelace",
global_macros = { year = function() return os.date("%Y") end },
html = { doctype = "html5", html5_fancy = true },
ascii = { charset = "utf-8", text_width = 80 },
md = { headline_style = "atx" },
},
})
Filters and hooks (export.filters, export.hooks) run Lua functions on
the text or the lines before parsing: see :h org-export.
24. Further reading
:h org-export(dispatcher, command and Lua API):h org-export-settings(keywords,#+OPTIONS, macros,#+INCLUDE):h org-export-backends,:h org-export-ascii,:h org-export-beamer,:h org-export-odt,:h org-export-texinfo,:h org-export-icalendar:h org-export-cite(citations),:h org-publish:h org-export-unsupported(what needs Emacs)- Related example files: 17-babel.org (code blocks), 14-footnotes.org, 13-links.org (link types), 21-images-latex.org (images and LaTeX fragments), and the overview in 00-index.org.