Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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:

BackendLibraryOutputLoaded by default
asciiox-asciiPlain text in ASCII, Latin-1 or UTF-8yes
htmlox-htmlHTML (XHTML or HTML5)yes
icalendarox-icalendar.ics calendar filesyes
latexox-latexLaTeX, and PDF through a LaTeX engineyes
odtox-odtOpenDocument Text (.odt)yes
beamerox-beamerLaTeX Beamer slidesno
mdox-mdMarkdown (original syntax)no
orgox-orgA normalized Org fileno
texinfoox-texinfoTexinfo and Info manualsno
manox-manMan pagesno
koma-letterox-koma-letterLetters with the KOMA-Script classno

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:

KeysFunctionResult
C-c C-e h horg-html-export-to-htmlfile.html
C-c C-e h Horg-html-export-as-htmlbuffer *Org HTML Export*
C-c C-e t a / t uorg-ascii-export-to-asciifile.txt (ASCII / UTF-8)
C-c C-e m morg-md-export-to-markdownfile.md (after loading ox-md)
C-c C-e l l / l porg-latex-export-to-latex / org-latex-export-to-pdffile.tex / file.pdf
C-c C-e l b / l Porg-beamer-export-to-latex / org-beamer-export-to-pdfBeamer .tex / .pdf
C-c C-e o oorg-odt-export-to-odtfile.odt
C-c C-e O oorg-org-export-to-orgfile.org.org
C-c C-e i t / i iorg-texinfo-export-to-texinfo / org-texinfo-export-to-info.texi / .info
C-c C-e c forg-icalendar-export-to-icsfile.ics
C-c C-e P ...org-publish and friendssee 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-s exports 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-v exports only the visible text, so you can fold or narrow the buffer (for example with a sparse tree) and export what you see.
  • C-b produces 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-a runs the export asynchronously in a separate Emacs process. The results go to the export stack, which C-u C-u C-c C-e (or & inside the dispatcher) displays.
  • C-f forces publishing of unchanged files; it matters only for the P commands.

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-file writes the result of a backend to a file.
  • org-export-as returns the result of the current buffer as a string. Its arguments are the backend, then subtreep, visible-only, body-only and an ext-plist of extra options.
  • org-export-string-as converts 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:

KeywordMeaningGlobal default
TITLEDocument title (several lines are joined)buffer name
AUTHORAuthoruser-full-name
EMAILEmail addressuser-mail-address
DATEDate or timestampnone
LANGUAGELanguage for generated strings such as “Table of Contents”org-export-default-language
CREATORName of the producing softwareorg-export-creator-string
SELECT_TAGSTags that select subtreesorg-export-select-tags, ("export")
EXCLUDE_TAGSTags that remove subtreesorg-export-exclude-tags, ("noexport")
EXPORT_FILE_NAMEOutput file name without extensionderived 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:

ItemEffectVariable
toc:nil, toc:2No table of contents, or limit its depthorg-export-with-toc
num:nil, num:2No section numbers, or number only to a levelorg-export-with-section-numbers
H:3Deepest level exported as a heading; deeper ones become list itemsorg-export-headline-levels
todo:nil, tags:nil, pri:tShow or hide TODO keywords, tags, priority cookiesorg-export-with-todo-keywords, org-export-with-tags, org-export-with-priority
tasks:nil, tasks:todoDrop all task headlines, or only the done onesorg-export-with-tasks
p:t, c:t, d:t, prop:tInclude planning lines, clock lines, drawers, property drawersorg-export-with-planning …
author:nil, date:nil, title:nil, email:tShow or hide document metadataorg-export-with-author …
^:{}Treat a_b literally but a_{b} as a subscriptorg-export-with-sub-superscripts
\n:tKeep line breaks as they areorg-export-preserve-breaks
broken-links:markMark broken internal links instead of abortingorg-export-with-broken-links
timestamp:nilDo not stamp the creation time into the outputorg-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.

ToolGranularityCode blocks inside are evaluated?
# comment lineone linenot applicable
#+BEGIN_COMMENT … #+END_COMMENTa blocknot applicable
COMMENT keyword in a headline (C-c ;, org-toggle-comment)a subtreeno, and not tangled either
:noexport: tag (or any tag in EXCLUDE_TAGS)a subtreeyes
:export: tag (or any tag in SELECT_TAGS)keeps only tagged subtreesyes
tasks: item in OPTIONStask headlinesyes

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 2 inserts a TOC of two levels at that position.
  • #+TOC: headlines 1 local inside a section lists only that section’s children, which is useful for long chapters.
  • The ALT_TITLE property gives a headline a shorter entry in the TOC (“Config” instead of “Configure”).
  • UNNUMBERED: notoc removes the number from “Changelog” and keeps it, with its children, out of every TOC. A plain UNNUMBERED: t removes 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-lisp wraps the file in a source block, so code examples always match the real file.
  • #+INCLUDE: "page.html" export html wraps 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 a CUSTOM_ID.
  • :only-contents t drops the headline, its planning line and its property drawer, and keeps the body.
  • :minlevel 2 shifts 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:

MacroExpands 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_EXPORT works 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 the zip program. org-odt-preferred-output-format can convert the result further, for example to doc or pdf, through an external converter.
  • Org (C-c C-e O o, after loading ox-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 under C-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).
  • COMMENT subtrees are removed before Babel runs, while noexport subtrees 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 backenda 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 rendereda derived backend
Support a new output formatorg-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:

CommandAlias
org-ascii-convert-region-to-asciiorg-export-region-to-ascii
org-ascii-convert-region-to-utf8org-export-region-to-utf8
org-html-convert-region-to-htmlorg-export-region-to-html
org-latex-convert-region-to-latexorg-export-region-to-latex
org-md-convert-region-to-mdorg-export-region-to-md
org-texinfo-convert-region-to-texinfoorg-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-e opens the dispatcher; C-s, C-v and C-b restrict scope and shape; C-u C-c C-e repeats 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 the tasks option decide what reaches the output; only COMMENT prevents code evaluation.
  • #+TOC, #+INCLUDE and #+MACRO assemble a document; export to Org to see the expanded result.
  • Hooks edit text, filters edit strings, and derived backends replace transcoders.

Further reading