Exporting
An Org file is a good place to think, but sooner or later other people need to read what you wrote, and they rarely use Emacs. Exporting turns one Org document into HTML, Markdown, plain text, LaTeX and PDF, OpenDocument, Texinfo, iCalendar and more, while keeping the structure (headlines, lists, tables) and the markup (emphasis, links, code) intact.
This chapter starts with the everyday path (one key sequence, one output file), then shows how to control what is exported and how, and ends with the machinery you can extend: hooks, filters and derived backends. Publishing whole sets of files is the subject of the next chapter, Publishing and Citations; evaluation of code blocks during export is covered in Working with Source Code.
All examples below were run with Org 9.8.13 in emacs -Q --batch, and the outputs are pasted from those runs. Where an output was long, it is trimmed and the cut is mentioned in the text.
The idea: one source, many backends
Org does not convert text with a set of regular expressions. It parses the buffer into a tree of elements and objects (the same tree that the element API exposes, see Hacking and Extending Org), and then hands that tree to a backend. A backend is a library that knows how to turn each kind of node (a headline, a table cell, a bold word) into the target format. Each of these per-node functions is called a transcoder.
Because every backend reads the same tree, a single source file can feed several outputs without any change. The library names follow the pattern ox-NAME:
| Backend | Library | Output | Loaded by default |
|---|---|---|---|
ascii | ox-ascii | Plain text in ASCII, Latin-1 or UTF-8 | yes |
html | ox-html | HTML (XHTML or HTML5) | yes |
icalendar | ox-icalendar | .ics calendar files | yes |
latex | ox-latex | LaTeX, and PDF through a LaTeX engine | yes |
odt | ox-odt | OpenDocument Text (.odt) | yes |
beamer | ox-beamer | LaTeX Beamer slides | no |
md | ox-md | Markdown (original syntax) | no |
org | ox-org | A normalized Org file | no |
texinfo | ox-texinfo | Texinfo and Info manuals | no |
man | ox-man | Man pages | no |
koma-letter | ox-koma-letter | Letters with the KOMA-Script class | no |
The “loaded by default” column reflects the default value of org-export-backends, which is (ascii html icalendar latex odt). You can add more in two ways. Either set the variable (with setq it must happen before Org loads; through the Customize interface it also works later), or simply require the library:
;; Option 1: before Org is loaded
(setq org-export-backends '(ascii html icalendar latex odt md org))
;; Option 2: at any time
(with-eval-after-load 'org
(require 'ox-md)
(require 'ox-beamer))
Third-party packages follow the same naming scheme, so a search for ox- in the package archives finds further backends.
The export dispatcher
Exporting interactively
Every export starts from one command: C-c C-e (org-export-dispatch). It opens a menu with one letter per backend and, under each letter, one letter per action. For example, C-c C-e h h writes file.html next to file.org, and C-c C-e h o writes it and opens it in a browser. Capital letters usually mean “export to a temporary buffer” rather than to a file, which is useful for a quick look:
| Keys | Function | Result |
|---|---|---|
C-c C-e h h | org-html-export-to-html | file.html |
C-c C-e h H | org-html-export-as-html | buffer *Org HTML Export* |
C-c C-e t a / t u | org-ascii-export-to-ascii | file.txt (ASCII / UTF-8) |
C-c C-e m m | org-md-export-to-markdown | file.md (after loading ox-md) |
C-c C-e l l / l p | org-latex-export-to-latex / org-latex-export-to-pdf | file.tex / file.pdf |
C-c C-e l b / l P | org-beamer-export-to-latex / org-beamer-export-to-pdf | Beamer .tex / .pdf |
C-c C-e o o | org-odt-export-to-odt | file.odt |
C-c C-e O o | org-org-export-to-org | file.org.org |
C-c C-e i t / i i | org-texinfo-export-to-texinfo / org-texinfo-export-to-info | .texi / .info |
C-c C-e c f | org-icalendar-export-to-ics | file.ics |
C-c C-e P ... | org-publish and friends | see Publishing and Citations |
Output files are overwritten without a question, so do not keep hand edits in them.
Scope and toggles
By default the whole buffer is exported. If a region is active, only the region is exported. Inside the dispatcher, a few C- keys change the scope or the shape of the output before you choose a backend:
C-sexports only the subtree at point. The subtree’s headline becomes the document title. This is how one Org file can hold many small documents (a handout, a status report, a letter), each exported on its own.C-vexports only the visible text, so you can fold or narrow the buffer (for example with a sparse tree) and export what you see.C-bproduces the body only, without the surrounding document structure (no<html>and<head>in HTML, no preamble in LaTeX). Use it when the output will be pasted into a template or a CMS.C-aruns the export asynchronously in a separate Emacs process. The results go to the export stack, whichC-u C-u C-c C-e(or&inside the dispatcher) displays.C-fforces publishing of unchanged files; it matters only for thePcommands.
A plain C-u before C-c C-e repeats the last export with the same options, which is the fastest way to re-export while editing.
Each toggle has a variable for its default: org-export-initial-scope (buffer or subtree), org-export-visible-only, org-export-body-only, org-export-in-background and org-export-force-publishing. For asynchronous export, org-export-async-init-file names the init file that the child Emacs loads. Without it the child loads your full user-init-file, so a small file that only sets up Org and your export settings makes background exports start faster. If you prefer a minibuffer prompt to the full-screen menu, set org-export-dispatch-use-expert-ui to t (? brings back the menu).
Exporting from the command line and from Lisp
Every export command can also run without a user. This is how you integrate Org into a Makefile or a CI job:
emacs --batch report.org --eval '(require (quote ox-md))' -f org-md-export-to-markdown
Emacs visits report.org, loads the Markdown backend and writes report.md. In Lisp, three functions cover most needs:
org-export-to-filewrites the result of a backend to a file.org-export-asreturns the result of the current buffer as a string. Its arguments are the backend, thensubtreep,visible-only,body-onlyand anext-plistof extra options.org-export-string-asconverts a string of Org text without a buffer of your own.
(require 'ox-md)
(org-export-string-as
"Ship *v2* soon, see [[https://orgmode.org][Org]]."
'md t '(:with-toc nil))
The result:
Ship **v2** soon, see [Org](https://orgmode.org).
The last argument is an export option plist. Every option you can set with a keyword also has a property name such as :with-toc; the next section explains how these layers relate.
Export settings
Where settings come from
An export option can be set at four levels, and the more specific level wins:
flowchart LR A["Global variables<br/>org-export-with-toc ..."] -->|overridden by| B["External plist<br/>ext-plist, publishing project"] B -->|overridden by| C["In-buffer keywords<br/>#+TITLE, #+OPTIONS, #+SETUPFILE"] C -->|overridden by| D["Subtree properties<br/>EXPORT_TITLE, EXPORT_OPTIONS"] D --> E[Export options used]
Figure 15.1: Export options are merged from the general to the specific, so a subtree property beats a file keyword, which beats a global variable.
The order is visible in the source of org-export-get-environment, which combines the global options, the external plist, the in-buffer settings and, for a subtree export, the subtree properties, in that order. Subtree properties are read only when you export a subtree (C-s in the dispatcher).
The practical consequence: put your personal defaults in variables, put document decisions in keywords at the top of the file, and use EXPORT_ properties for documents that live inside a larger file. If several files share the same keywords, move them into one file and pull it in with #+SETUPFILE: path/to/common.org.
Keywords
In-buffer settings are keywords of the form #+KEYWORD: value, usually at the top of the file. The ones every backend understands are:
| Keyword | Meaning | Global default |
|---|---|---|
TITLE | Document title (several lines are joined) | buffer name |
AUTHOR | Author | user-full-name |
EMAIL | Email address | user-mail-address |
DATE | Date or timestamp | none |
LANGUAGE | Language for generated strings such as “Table of Contents” | org-export-default-language |
CREATOR | Name of the producing software | org-export-creator-string |
SELECT_TAGS | Tags that select subtrees | org-export-select-tags, ("export") |
EXCLUDE_TAGS | Tags that remove subtrees | org-export-exclude-tags, ("noexport") |
EXPORT_FILE_NAME | Output file name without extension | derived from the buffer |
Backends add their own keywords, for example HTML_HEAD and HTML_DOCTYPE for HTML or LATEX_CLASS and LATEX_HEADER for LaTeX. To avoid typos, type #+ and complete with M-TAB, or press # inside the dispatcher to insert a template with all keywords of a backend.
The OPTIONS line
#+OPTIONS: packs many switches into one line as name:value pairs. You can repeat the keyword to spread them over several lines. The most useful items are:
| Item | Effect | Variable |
|---|---|---|
toc:nil, toc:2 | No table of contents, or limit its depth | org-export-with-toc |
num:nil, num:2 | No section numbers, or number only to a level | org-export-with-section-numbers |
H:3 | Deepest level exported as a heading; deeper ones become list items | org-export-headline-levels |
todo:nil, tags:nil, pri:t | Show or hide TODO keywords, tags, priority cookies | org-export-with-todo-keywords, org-export-with-tags, org-export-with-priority |
tasks:nil, tasks:todo | Drop all task headlines, or only the done ones | org-export-with-tasks |
p:t, c:t, d:t, prop:t | Include planning lines, clock lines, drawers, property drawers | org-export-with-planning … |
author:nil, date:nil, title:nil, email:t | Show or hide document metadata | org-export-with-author … |
^:{} | Treat a_b literally but a_{b} as a subscript | org-export-with-sub-superscripts |
\n:t | Keep line breaks as they are | org-export-preserve-breaks |
broken-links:mark | Mark broken internal links instead of aborting | org-export-with-broken-links |
timestamp:nil | Do not stamp the creation time into the output | org-export-timestamp-file |
The full list has more than 30 items; see the manual’s Export Settings node.
Subtree settings
When you export a subtree, keywords become properties with an EXPORT_ prefix: EXPORT_TITLE, EXPORT_AUTHOR, EXPORT_OPTIONS, EXPORT_FILE_NAME and so on. Every keyword in the table above has such a twin, except SETUPFILE. The next example combines this with selection by tags.
Choosing what gets exported
A notebook mixes material for readers with material for yourself. Org offers several tools to keep the private part out of the output, and they work at different granularities.
| Tool | Granularity | Code blocks inside are evaluated? |
|---|---|---|
# comment line | one line | not applicable |
#+BEGIN_COMMENT … #+END_COMMENT | a block | not applicable |
COMMENT keyword in a headline (C-c ;, org-toggle-comment) | a subtree | no, and not tangled either |
:noexport: tag (or any tag in EXCLUDE_TAGS) | a subtree | yes |
:export: tag (or any tag in SELECT_TAGS) | keeps only tagged subtrees | yes |
tasks: item in OPTIONS | task headlines | yes |
The difference in the last column matters when a subtree contains code with side effects: a COMMENT subtree is removed before Babel runs, while a noexport subtree is removed only after the code has run. The pipeline in Figure 15.2 below shows why.
Consider this file:
#+TITLE: Team Notebook
#+OPTIONS: toc:nil author:nil date:nil
Preamble text before the first headline.
* Meeting 2026-11-02
Agreed to ship on Friday.
* Handout :export:
:PROPERTIES:
:EXPORT_TITLE: Onboarding Handout
:EXPORT_OPTIONS: num:nil
:EXPORT_FILE_NAME: handout
:END:
Welcome to the team.
** DONE Get a laptop
** TODO Read the style guide
** Secrets :noexport:
The Wi-Fi password.
Exporting the whole buffer to ASCII gives:
_______________
TEAM NOTEBOOK
_______________
1 Handout :export:
=========
Welcome to the team.
1.1 DONE Get a laptop
~~~~~~~~~~~~~~~~~~~~~
1.2 TODO Read the style guide
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Three things happened. Because one subtree carries the export tag, only that subtree was selected, and the meeting notes disappeared. The preamble text vanished too: when select tags are in use, text before the first headline is never exported. Finally, Secrets was removed by its noexport tag. The tag itself still shows in the heading; add tags:nil to OPTIONS if you do not want that.
Now place point on Handout, export the subtree (C-c C-e C-s t a), and set org-export-with-tasks to todo:
____________________
ONBOARDING HANDOUT
____________________
Welcome to the team.
TODO Read the style guide
=========================
The title now comes from EXPORT_TITLE, section numbers are off because of EXPORT_OPTIONS, and the finished task was dropped. Since the subtree also sets EXPORT_FILE_NAME, the file version is written to handout.txt instead of notes.txt.
Tables of contents
By default, Org puts a table of contents (TOC) at the start of the document, with all headline levels. #+OPTIONS: toc:2 limits the depth and toc:nil removes it. To place a TOC elsewhere, turn off the default and insert a #+TOC: keyword where you want it:
#+TITLE: Guide
#+OPTIONS: toc:nil author:nil date:nil title:nil
Intro paragraph.
#+TOC: headlines 2
* Install
** On Linux
** On macOS
* Configure
:PROPERTIES:
:ALT_TITLE: Config
:END:
#+TOC: headlines 1 local
** Basic
** Advanced
* Changelog
:PROPERTIES:
:UNNUMBERED: notoc
:END:
UTF-8 export (C-c C-e t u) produces:
Intro paragraph.
Table of Contents
─────────────────
1. Install
.. 1. On Linux
.. 2. On macOS
2. Config
.. 1. Basic
.. 2. Advanced
1 Install
═════════
1.1 On Linux
────────────
1.2 On macOS
────────────
2 Configure
═══════════
.. 1. Basic
.. 2. Advanced
2.1 Basic
─────────
2.2 Advanced
────────────
Changelog
═════════
The example shows four controls:
#+TOC: headlines 2inserts a TOC of two levels at that position.#+TOC: headlines 1 localinside a section lists only that section’s children, which is useful for long chapters.- The
ALT_TITLEproperty gives a headline a shorter entry in the TOC (“Config” instead of “Configure”). UNNUMBERED: notocremoves the number from “Changelog” and keeps it, with its children, out of every TOC. A plainUNNUMBERED: tremoves only the number.
#+TOC: tables and #+TOC: listings produce lists of captioned tables and code listings. #+TOC: headlines 1 :target #some-id builds a TOC of another section, identified by its CUSTOM_ID; it works in HTML, Markdown, ODT and ASCII.
Including other files
Large documents become easier to manage when you split them. The #+INCLUDE: keyword copies another file (or part of it) into the document at export time. The source file stays untouched; the inclusion happens on a temporary copy of the buffer.
The keyword takes a file name, then an optional block type and language:
#+INCLUDE: "chapter2.org"inserts Org text. Its headlines become children of the current section.#+INCLUDE: "lib.el" src emacs-lispwraps the file in a source block, so code examples always match the real file.#+INCLUDE: "page.html" export htmlwraps it in an export block.
Several parameters narrow the selection:
:lines "5-10"includes lines 5 to 9 (the upper bound is excluded);"-10"and"10-"leave one end open.- A search option after
::picks one element, as in a file link:"paper.org::*Conclusion"for a headline,"paper.org::#theory"for aCUSTOM_ID. :only-contents tdrops the headline, its planning line and its property drawer, and keeps the body.:minlevel 2shifts the included headlines so that the highest one is at level 2.
Here is a book file that pulls in code and text from two other files:
#+TITLE: Include Demo
#+OPTIONS: toc:nil num:nil author:nil date:nil title:nil
* Code
The greeting function:
#+INCLUDE: "lib.el" src emacs-lisp :lines "1-4"
* From the chapter
#+INCLUDE: "chapter.org::#usage" :only-contents t
#+INCLUDE: "chapter.org::*Setup" :minlevel 2
with chapter.org:
* Setup
Install the package first.
* Usage
:PROPERTIES:
:CUSTOM_ID: usage
:END:
Call =greet= with a name.
** Options
There are none yet.
The quickest way to see what an inclusion produces is to export to Org itself (C-c C-e O O after loading ox-org), because the Org backend prints the expanded document:
#+options: toc:nil num:nil author:nil date:nil title:nil
* Code
The greeting function:
#+begin_src emacs-lisp
(defun greet (name)
"Return a greeting for NAME."
(format "Hello, %s!" name))
#+end_src
* From the chapter
Call =greet= with a name.
** Options
There are none yet.
** Setup
Install the package first.
Notice that :only-contents kept the Options child of Usage, and that :minlevel 2 turned the level-1 Setup into a level-2 heading. With point on an INCLUDE line, C-c ' (org-edit-special) opens the included file.
Macros
A macro is a named piece of text that Org substitutes during export. Macros are handy for values that appear many times (a product name, a version) and for small computed strings. Define them with #+MACRO:, or globally in org-export-global-macros, and call them with three braces:
#+TITLE: Macro Demo
#+MACRO: product Orgle
#+MACRO: ver version $1 (build $2)
#+MACRO: upper (eval (upcase $1))
#+OPTIONS: toc:nil num:nil author:nil date:nil title:nil
{{{product}}} {{{ver(2.0, 417)}}} ships today. Shout it: {{{upper(done)}}}.
Step {{{n}}}: install. Step {{{n}}}: configure. Step {{{n}}}: run.
This file is {{{input-file}}}, titled "{{{title}}}".
ASCII export gives:
Orgle version 2.0 (build 417) ships today. Shout it: DONE.
Step 1: install. Step 2: configure. Step 3: run.
This file is macros.org, titled "Macro Demo".
Arguments are referenced as $1, $2 and so on, and are separated by commas (escape a literal comma as \,). A replacement that starts with (eval is evaluated as Emacs Lisp, with the arguments bound as strings. Org also predefines several macros:
| Macro | Expands to |
|---|---|
{{{title}}}, {{{author}}}, {{{email}}} | The corresponding keyword |
{{{keyword(NAME)}}} | All values of any keyword NAME |
{{{date}}}, {{{date(FORMAT)}}} | The DATE keyword, optionally reformatted |
{{{time(FORMAT)}}} | The export time |
{{{modification-time(FORMAT, VC)}}} | The file’s modification time, from version control if VC is non-nil |
{{{input-file}}} | The name of the exported file |
{{{property(NAME)}}} | A property of the current entry, or of a remote entry given as a search option |
{{{n}}}, {{{n(NAME)}}}, {{{n(NAME, ACTION)}}} | An auto-incrementing counter; - holds the value, a number sets it, any other string resets it |
Macros work in paragraphs, headlines, lists, table cells, verse blocks and in keywords such as TITLE, AUTHOR, DATE and CAPTION. Avoid redefining results, because inline code blocks use it. If the braces clutter your buffer, org-hide-macro-markers hides them, and org-export-replace-macros set to nil disables expansion entirely.
Speaking directly to one backend
Sometimes you need a construct that Org has no syntax for: a <kbd> tag in HTML, a \newpage in LaTeX. Org lets you pass raw text to one backend while every other backend ignores it.
- An export snippet
@@html:...@@works inline. - The keyword
#+HTML: ...(or#+LATEX:,#+ASCII:…) works for one line. - An export block
#+BEGIN_EXPORT html…#+END_EXPORTworks for many lines. - An attribute line such as
#+ATTR_HTML:adds attributes to the element that follows it.
#+TITLE: Snippets
#+OPTIONS: toc:nil num:nil author:nil date:nil
Press @@html:<kbd>@@C-c C-e@@html:</kbd>@@ to export.@@ascii: (Keyboard shortcut.)@@
#+ATTR_HTML: :class wide :alt Architecture diagram
[[file:arch.png]]
#+BEGIN_EXPORT html
<aside class="note">Only HTML readers see this.</aside>
#+END_EXPORT
The HTML body (C-b in the dispatcher) is:
<p>
Press <kbd>C-c C-e</kbd> to export.
</p>
<div id="orgd50719d" class="figure">
<p><img src="arch.png" alt="Architecture diagram" class="wide" />
</p>
</div>
<aside class="note">Only HTML readers see this.</aside>
and the ASCII body is:
Press C-c C-e to export. (Keyboard shortcut.)
<file:arch.png>
Each backend kept its own snippets and dropped the others. Snippets also travel through derived backends: Markdown is derived from HTML, so @@html:...@@ snippets appear in Markdown output as well.
The built-in backends at a glance
The same small file serves as input for the comparisons below:
#+TITLE: Release Notes
#+AUTHOR: Ada Example
#+DATE: 2026-11-19
#+OPTIONS: toc:nil num:t
Version 2.0 brings *faster* search and a /new/ plugin API.
* Highlights
- Search is about 3x faster.
- Plugins can register commands.
* TODO Write migration guide
* Internal notes :noexport:
Do not ship the debug build.
* Benchmarks
| Query | v1 (ms) | v2 (ms) |
|-------+---------+---------|
| short | 120 | 40 |
| long | 900 | 310 |
HTML
The HTML backend is the most complete one. Body-only output of the file above (trimmed after the second section) looks like this:
<p>
Version 2.0 brings <b>faster</b> search and a <i>new</i> plugin API.
</p>
<div id="outline-container-org9f54f56" class="outline-2">
<h2 id="org9f54f56"><span class="section-number-2">1.</span> Highlights</h2>
<div class="outline-text-2" id="text-1">
<ul class="org-ul">
<li>Search is about 3x faster.</li>
<li>Plugins can register commands.</li>
</ul>
</div>
</div>
<div id="outline-container-org4c5f174" class="outline-2">
<h2 id="org4c5f174"><span class="section-number-2">2.</span> <span class="todo TODO">TODO</span> Write migration guide</h2>
</div>
Every structural part gets a CSS class (outline-2, section-number-2, todo, timestamp, tag and so on), so a stylesheet can target them. The id values such as org9f54f56 are generated and change between exports; give a headline a CUSTOM_ID property when you need a stable anchor.
A full document adds a <head>, a default style sheet, some JavaScript and a postamble (a footer with author, date and a validation link). For a modern, clean page, ask for HTML5 and switch the extras off. The html-style and html-scripts items of OPTIONS control the built-in CSS and scripts:
#+TITLE: Tiny Page
#+AUTHOR: Ada Example
#+DATE: 2026-11-19
#+HTML_DOCTYPE: html5
#+HTML_HEAD: <link rel="stylesheet" href="style.css" />
#+OPTIONS: toc:nil num:nil html-style:nil html-scripts:nil
Hello from Org.
With org-export-timestamp-file set to nil, the complete output is:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Tiny Page</title>
<meta name="author" content="Ada Example" />
<meta name="generator" content="Org Mode" />
<link rel="stylesheet" href="style.css" />
</head>
<body>
<div id="content" class="content">
<h1 class="title">Tiny Page</h1>
<p>
Hello from Org.
</p>
</div>
<div id="postamble" class="status">
<p class="date">Date: 2026-11-19</p>
<p class="author">Author: Ada Example</p>
<p class="validation"><a href="https://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>
</html>
The postamble is built automatically because org-html-postamble defaults to auto. Set it to nil, to a format string, or to a function returning a string. org-html-preamble works the same way for a header above the content. A configuration for bare HTML pages, with every variable taken from the manual’s Bare HTML node, is:
(setq org-html-doctype "html5"
org-html-head ""
org-html-head-extra ""
org-html-head-include-default-style nil
org-html-head-include-scripts nil
org-html-preamble nil
org-html-postamble nil
org-html-use-infojs nil)
Links to other .org files become links to .html files (controlled by org-html-link-org-files-as-html), which is what makes multi-page sites work; see Publishing and Citations. Math is rendered with MathJax by default (org-html-mathjax-options, keyword HTML_MATHJAX).
Markdown
The Markdown backend follows the original Markdown syntax. It is derived from the HTML backend, so anything Markdown cannot express falls back to HTML. Tables are the most visible case. C-c C-e m m on the release notes produces report.md (trimmed inside the table):
Version 2.0 brings **faster** search and a *new* plugin API.
# Highlights
- Search is about 3x faster.
- Plugins can register commands.
# TODO Write migration guide
# Benchmarks
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
...
<tr>
<td class="org-left">short</td>
<td class="org-right">120</td>
<td class="org-right">40</td>
</tr>
...
</table>
Two details stand out. The #+TITLE does not appear, because the Markdown template returns only the body; put the title in a top-level headline or in front matter of your own if your target needs it. And the noexport subtree is gone, as in every backend. org-md-headline-style chooses between atx (# headings, the default), setext (underlined, two levels only) and mixed; org-md-toplevel-hlevel sets the Markdown level of top-level headlines. If you need pipe tables or fenced code blocks, a derived backend can add them in a few lines; the last section of this chapter builds one.
ASCII, Latin-1 and UTF-8
The text backend fills paragraphs to org-ascii-text-width (72 columns by default) and underlines headings. The three variants differ only in org-ascii-charset (ascii, latin1 or utf-8), which the dispatcher keys t a, t l and t u set for you. Plain text output is the best way to check what a document actually contains, which is why this chapter uses it so often:
_______________
RELEASE NOTES
Ada Example
_______________
2026-11-19
Version 2.0 brings *faster* search and a /new/ plugin API.
1 Highlights
============
- Search is about 3x faster.
- Plugins can register commands.
2 TODO Write migration guide
============================
3 Benchmarks
============
Query v1 (ms) v2 (ms)
-------------------------
short 120 40
long 900 310
Links become footnote-like references collected before the next heading (org-ascii-links-to-notes). Two special blocks, #+BEGIN_JUSTIFYLEFT and #+BEGIN_JUSTIFYRIGHT, align text, and #+ATTR_ASCII: :width 10 sets the width of a horizontal rule.
LaTeX and PDF
The LaTeX backend targets print-quality documents. C-c C-e l p writes the .tex file and runs the commands in org-latex-pdf-process to build a PDF; the engine (pdflatex, xelatex or lualatex) comes from org-latex-compiler or the LATEX_COMPILER keyword. The body of the release notes is:
Version 2.0 brings \textbf{faster} search and a \emph{new} plugin API.
\section{Highlights}
\label{sec:orge3b3863}
\begin{itemize}
\item Search is about 3x faster.
\item Plugins can register commands.
\end{itemize}
\section{{\bfseries\sffamily TODO} Write migration guide}
\label{sec:orgd67671a}
\section{Benchmarks}
\label{sec:orgec6e440}
\begin{center}
\begin{tabular}{lrr}
Query & v1 (ms) & v2 (ms)\\
\hline
short & 120 & 40\\
long & 900 & 310\\
\end{tabular}
\end{center}
Document classes come from org-latex-classes and the LATEX_CLASS keyword; extra preamble lines go into #+LATEX_HEADER:. Packages loaded by default are listed in org-latex-default-packages-alist, and your own additions belong in org-latex-packages-alist. Because LaTeX itself treats blank lines as paragraph breaks, blank lines in the Org source matter more here than in other backends.
Beamer
Beamer turns an outline into slides. Headlines at the frame level (set with H: in OPTIONS or with org-beamer-frame-level) become frames, and headlines above it become sections:
#+TITLE: Why Plain Text
#+OPTIONS: H:2 toc:nil num:nil
* Motivation
** One source, many outputs
- Notes become slides
- Slides become handouts
\section*{Motivation}
\label{sec:org54a4030}
\begin{frame}[label={sec:org9aa0fd8}]{One source, many outputs}
\begin{itemize}
\item Notes become slides
\item Slides become handouts
\end{itemize}
\end{frame}
Load ox-beamer, then use C-c C-e l b for the .tex file or C-c C-e l P for the PDF.
ODT, Org, Texinfo and man
- ODT (
C-c C-e o o) writes an OpenDocument Text file that LibreOffice and Word can open. It needs thezipprogram.org-odt-preferred-output-formatcan convert the result further, for example todocorpdf, through an external converter. - Org (
C-c C-e O o, after loadingox-org) writes a normalized copy with includes and macros expanded, Babel results computed, and content for other backends removed. It is the debugging tool for everything in this chapter. - Texinfo (
C-c C-e i t,C-c C-e i i) produces GNU-style manuals; the Org manual itself is written in Org and exported this way. - man (
ox-man, keys underC-c C-e M) writes man pages.
iCalendar
The iCalendar backend exports headlines that carry active timestamps as calendar events, so your Org schedule can appear in any calendar application. Tags become categories, and the ID property, if present, provides a stable UID:
#+TITLE: Calendar
* Team sync :work:
:PROPERTIES:
:ID: 7d1c0f3e-2a7b-4e5c-9a51-0b6f1f2c9e10
:LOCATION: Room 4
:END:
<2026-11-23 Mon 10:00-10:30>
Weekly status round.
* TODO Submit report
DEADLINE: <2026-11-27 Fri>
With org-icalendar-include-todo set to t, C-c C-e c f writes cal.ics (header lines trimmed):
BEGIN:VCALENDAR
VERSION:2.0
X-WR-CALNAME:cal
PRODID:-////Emacs with Org mode//EN
CALSCALE:GREGORIAN
BEGIN:VEVENT
DTSTAMP:20261119T092619Z
UID:TS1-7d1c0f3e-2a7b-4e5c-9a51-0b6f1f2c9e10
DTSTART:20261123T100000
DTEND:20261123T103000
SUMMARY:Team sync
LOCATION:Room 4
DESCRIPTION:<2026-11-23 Mon 10:00-10:30> Weekly status round.
CATEGORIES:work,cal
END:VEVENT
BEGIN:VTODO
UID:TODO-3f2a835a-82b2-4649-9dc0-55779302c29b
DTSTAMP:20261119T092620Z
DUE;VALUE=DATE:20261127
SUMMARY:Submit report
CATEGORIES:cal
SEQUENCE:1
PRIORITY:5
STATUS:NEEDS-ACTION
END:VTODO
END:VCALENDAR
The UID prefix (TS1-, TODO-) records which part of the entry produced the event, so one entry can yield several calendar items. Set org-icalendar-store-UID to write generated IDs back into the Org file, so that UIDs stay stable across exports. C-c C-e c a exports each file in org-agenda-files separately, and C-c C-e c c combines them into org-icalendar-combined-agenda-file. Timestamps without an end time get the length in org-agenda-default-appointment-duration (two hours if that is unset); org-icalendar-use-deadline and org-icalendar-use-scheduled decide which planning lines become events or task dates. The properties SUMMARY, DESCRIPTION, LOCATION, TIMEZONE and CLASS are copied when present. See Dates and Times for the timestamps themselves.
How an export runs
Everything so far has been configuration. To change the export process itself, you need a picture of its stages. Org never touches your buffer: it works on a temporary copy and goes through four phases.
flowchart TD A[Org buffer] -->|copy| B["Temporary buffer"] B --> C["before-processing hook"] C --> D["Expand #+INCLUDE, drop COMMENT trees, expand macros"] D --> E["Run Babel, apply :exports"] E --> F["before-parsing hook"] F -->|parse| G["Parse tree, pruned by tags and OPTIONS"] G -->|"parse-tree filters"| H["Backend transcoders, node by node"] H -->|"element and object filters"| I["Template: TOC, preamble, metadata"] I -->|"body and final-output filters"| J[Output string or file]
Figure 15.2: An export copies the buffer, rewrites the text, parses it into a tree, transcodes each node through the backend, and passes every stage through hooks or filters that you can extend.
The figure explains several behaviors seen earlier:
- Includes and macros are expanded before parsing. That is why an included file may contain headlines and macros, and why a hook that inserts
{{{input-file}}}still gets it expanded (see the example below). COMMENTsubtrees are removed before Babel runs, whilenoexportsubtrees are removed only after parsing; their code has already been evaluated.- Once the tree exists, the buffer no longer matters. Changes must be made by hooks before parsing, or by filters and transcoders after it.
Hooks run on text, filters run on strings that transcoders produced, and derived backends replace transcoders. The rest of the chapter takes them in that order.
Hooks
Two abnormal hooks run in the temporary buffer. org-export-before-processing-functions runs first, before includes, macros and Babel. org-export-before-parsing-functions runs after them, just before parsing. Each function receives the backend name as a symbol and may edit the buffer freely.
The following hook inserts a line at the top of every exported document. Since it runs before macro expansion, it can use a macro:
(defun my-insert-source-note (_backend)
"Insert a note at the top of the buffer before macros expand."
(goto-char (point-min))
(while (looking-at-p "^#\\+") (forward-line))
(insert "Generated from {{{input-file}}}.\n\n"))
(add-hook 'org-export-before-processing-functions #'my-insert-source-note)
Use hooks for structural edits that are easier to express on text than on a tree: removing or reordering headlines, inserting boilerplate, or rewriting custom syntax into standard Org.
Filters
A filter is a function that receives the string a transcoder produced and may return a changed string. Filters are stored in variables named org-export-filter-TYPE-functions, where TYPE is an element or object type (headline, link, table, src-block, plain-text …) or one of the special stages parse-tree, options, body and final-output. Each filter receives three arguments: the text, the backend name, and the communication channel info, a plist with all export options and state. Returning nil leaves the text unchanged.
Here are two filters. The first replaces an internal code name in all plain text, for every backend. The second adds target="_blank" to external links, but only in HTML:
(defun my-filter-codename (text _backend _info)
"Replace the internal codename in every piece of plain text."
(replace-regexp-in-string "Bluebird" "Orgle" text t t))
(defun my-html-external-links (text backend _info)
"Open external links in a new tab in HTML output."
(when (and (org-export-derived-backend-p backend 'html)
(string-match-p "href=\"https?:" text))
(replace-regexp-in-string "<a href=" "<a target=\"_blank\" href=" text t t)))
(add-to-list 'org-export-filter-plain-text-functions #'my-filter-codename)
(add-to-list 'org-export-filter-link-functions #'my-html-external-links)
Together with the hook from the previous section, this input:
#+TITLE: Filters
#+OPTIONS: toc:nil num:nil author:nil date:nil title:nil
Bluebird is our new search engine. See [[https://orgmode.org][the Org site]] or [[#faq][the FAQ]].
* FAQ
:PROPERTIES:
:CUSTOM_ID: faq
:END:
Bluebird is fast.
exports to this HTML body:
<p>
Generated from filters.org.
</p>
<p>
Orgle is our new search engine. See <a target="_blank" href="https://orgmode.org">the Org site</a> or <a href="#faq">the FAQ</a>.
</p>
<div id="outline-container-faq" class="outline-2">
<h2 id="faq">FAQ</h2>
<div class="outline-text-2" id="text-faq">
<p>
Orgle is fast.
</p>
</div>
</div>
and to this Markdown:
Generated from filters.org.
Orgle is our new search engine. See [the Org site](https://orgmode.org) or [the FAQ](#faq).
<a id="faq"></a>
# FAQ
Orgle is fast.
The internal link kept its plain href, because the filter checks for http. Note also why the HTML filter tests the text as well as the backend: org-export-derived-backend-p is true for md, since Markdown is derived from HTML. Without the href= test, the filter would run on Markdown links too. Always think about derived backends when you write a backend test.
Filters for a single file
Filters are global variables, but sometimes one document needs its own. The #+BIND: keyword makes a variable buffer-local during export, and it can bind a filter list. Because a file could use it to set any variable, BIND is ignored unless org-export-allow-bind-keywords is non-nil.
#+TITLE: Per-file filter
#+OPTIONS: toc:nil num:nil author:nil date:nil title:nil
#+BIND: org-export-filter-strike-through-functions (my-drop-strike)
#+BEGIN_SRC emacs-lisp :exports results :results none
(defun my-drop-strike (_text _backend _info) "")
#+END_SRC
The meeting is on +Monday+ Tuesday.
The code block defines the filter during export: it runs in the Babel phase, before the BIND values are read. By default Org asks for confirmation before it evaluates the block; the runs below set org-confirm-babel-evaluate to nil. ASCII export with default settings, then with org-export-allow-bind-keywords set to t:
--- default ---
The meeting is on +Monday+ Tuesday.
--- with org-export-allow-bind-keywords ---
The meeting is on Tuesday.
The struck-out word disappears only in the second run. Since this technique evaluates code from the document, apply it only to files you trust; Working with Source Code discusses org-confirm-babel-evaluate.
Derived backends
Filters edit strings after the fact. When you want to change how a whole kind of node is rendered, it is cleaner to replace its transcoder. org-export-define-derived-backend creates a new backend that inherits everything from a parent and overrides only the transcoders you list in :translate-alist.
flowchart LR
N["Node, e.g. src-block"] --> Q{"In my-md<br/>translate-alist?"}
Q -->|yes| M["my-md-src-block"]
Q -->|no| P{"In md?"}
P -->|yes| MD["md transcoder"]
P -->|no| H["html transcoder"]
M --> O[Output text]
MD --> O
H --> O
Figure 15.3: A derived backend looks up each node type in its own table first and falls back to its parent’s chain, so you write only the transcoders you want to change.
The Markdown backend writes code as indented blocks and tables as HTML. Many sites expect fenced code blocks with a language and pipe tables instead. A derived backend fixes both:
(require 'ox-md)
(defun my-md-src-block (src-block _contents info)
"Transcode SRC-BLOCK into a fenced code block with a language tag."
(format "```%s\n%s```"
(or (org-element-property :language src-block) "")
(org-export-format-code-default src-block info)))
(defun my-md-table-cell (_cell contents _info)
"Transcode a table cell into one pipe-table cell."
(concat " " (or contents "") " |"))
(defun my-md-table-row (row contents info)
"Transcode ROW into a pipe-table line or a separator line."
(if (eq (org-element-property :type row) 'rule)
(let ((columns (cdr (org-export-table-dimensions
(org-element-lineage row 'table) info))))
(concat "|" (apply #'concat (make-list columns "---|"))))
(concat "|" contents)))
(defun my-md-table (_table contents _info)
"Return the rows of a table unchanged."
contents)
(org-export-define-derived-backend 'my-md 'md
:translate-alist '((src-block . my-md-src-block)
(table . my-md-table)
(table-row . my-md-table-row)
(table-cell . my-md-table-cell))
:menu-entry
'(?m 1 ((?f "To fenced Markdown buffer"
(lambda (a s v b)
(org-export-to-buffer 'my-md "*Org my-md Export*"
a s v b nil (lambda () (text-mode))))))))
A transcoder takes three arguments: the node, its already transcoded contents (or nil for leaf nodes such as source blocks), and the info channel. Helper functions from ox.el do the hard work: org-export-format-code-default returns the code with any line numbers applied, and org-export-table-dimensions returns the number of rows and columns. A transcoder can also delegate to the parent for cases it does not handle, with (org-export-with-backend 'md node contents info).
The :menu-entry adds f under the existing m (Markdown) menu, so C-c C-e m f now exports with the new backend. Because the second element is a number (1) instead of a description, the dispatcher adds the item to the submenu that already exists under m instead of creating a new top-level letter.
For this input:
#+TITLE: Fenced
#+OPTIONS: toc:nil num:nil author:nil date:nil title:nil
* Example
Run this:
#+BEGIN_SRC python
print("hello")
#+END_SRC
| a | b |
|---+---|
| 1 | 2 |
the stock md backend writes (table trimmed):
# Example
Run this:
print("hello")
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
...
</table>
while my-md writes:
# Example
Run this:
```python
print("hello")
```
| a | b |
|---|---|
| 1 | 2 |
The derived backend reused the parent for headlines, paragraphs and everything else. You can also add options with :options-alist, run filters specific to the backend with :filters-alist, or build a completely new backend with org-export-define-backend; Hacking and Extending Org covers that case.
Choosing the right tool
| You want to … | Use |
|---|---|
| Rewrite Org text before export (add, remove, reorder) | org-export-before-processing-functions or org-export-before-parsing-functions |
| Adjust a string in the output of an existing backend | a filter, org-export-filter-TYPE-functions |
| Do the same for one document only | #+BIND: with org-export-allow-bind-keywords |
| Change how a whole kind of node is rendered | a derived backend |
| Support a new output format | org-export-define-backend |
Converting a region in place
Some backends can also convert a region in place, replacing Org text in any buffer with the target format. This is useful when you edit an HTML or LaTeX file and want to write a table or list in Org syntax. Select the Org text and run one of these commands:
| Command | Alias |
|---|---|
org-ascii-convert-region-to-ascii | org-export-region-to-ascii |
org-ascii-convert-region-to-utf8 | org-export-region-to-utf8 |
org-html-convert-region-to-html | org-export-region-to-html |
org-latex-convert-region-to-latex | org-export-region-to-latex |
org-md-convert-region-to-md | org-export-region-to-md |
org-texinfo-convert-region-to-texinfo | org-export-region-to-texinfo |
For example, selecting
| tea | 3 |
| coffee | 4 |
and running M-x org-html-convert-region-to-html replaces it with (blank lines trimmed):
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<colgroup>
<col class="org-left" />
<col class="org-right" />
</colgroup>
<tbody>
<tr>
<td class="org-left">tea</td>
<td class="org-right">3</td>
</tr>
<tr>
<td class="org-left">coffee</td>
<td class="org-right">4</td>
</tr>
</tbody>
</table>
For tables that must stay editable inside another major mode, Orgtbl mode with its send-and-receive mechanism is the better tool; see The Table Editor.
Summary
C-c C-eopens the dispatcher;C-s,C-vandC-brestrict scope and shape;C-u C-c C-erepeats the last export.- Options come from variables, then an external plist, then keywords, then
EXPORT_properties, with the most specific winning. - Tags,
COMMENT, comment lines and thetasksoption decide what reaches the output; onlyCOMMENTprevents code evaluation. #+TOC,#+INCLUDEand#+MACROassemble a document; export to Org to see the expanded result.- Hooks edit text, filters edit strings, and derived backends replace transcoders.
Further reading
- Org manual: Exporting, The Export Dispatcher, Export Settings, Table of Contents, Include Files, Macro Replacement, Comment Lines
- Org manual, backends: HTML Export, Bare HTML, Markdown Export, LaTeX Export, Beamer Export, OpenDocument Text Export, Org Export, Texinfo Export, iCalendar Export, Other Built-in Backends
- Org manual: Advanced Export Configuration (hooks, filters, the export process step by step, extending a backend) and Export Region
- Source:
lisp/ox.el(the generic exporter:org-export-as,org-export-define-derived-backend, the filter variables) andlisp/ox-md.el(a small backend derived from HTML, good to read before writing your own)