Org Export Reference Documentation

Defining a Back-End
Elements Attributes
- Babel Call
- Bold
- Center Block
- Clock
- Code
- Comment
- Comment Block
- Diary Sexp
- Drawer
- Dynamic Block
- Entity
- Example Block
- Export Block
- Export Snippet
- Fixed Width
- Footnote Definition
- Footnote Reference
- Headline
- Horizontal Rule
- Inline Babel Call
- Inline Src Block
- Inlinetask
- Italic
- Item
- Keyword
- LaTeX Environment
- LaTeX Fragment
- Line Break
- Link
- Macro
- Paragraph
- Plain List
- Planning
- Property Drawer
- Quote Block
- Quote Section
- Radio Target
- Section
- Special Block
- Src Block
- Statistics Cookie
- Strike Through
- Subscript
- Superscript
- Table
- Table Cell
- Table Row
- Target
- Timestamp
- Underline
- Verbatim
- Verse Block
The Communication Channel
The Filter System
The Toolbox
Interactive functions

This document is aimed at back-end developers for the generic export engine ox.el. It assumes a good understanding of Org syntax from the reader.

It covers back-end creation process, all attributes associated to each element or object type, properties offered by the communication channel during export, the filter system internals and tools provided by the exporter. Eventually, expected interactive functions aimed at end-users are explained in the last part of this document.

Defining a Back-End

A back-end is defined with org-export-define-backend function. It requires two mandatory arguments: the back-end name and its translation table, an alist that associates element and object types to translator functions. According to the doc-string:

These functions should return a string without any trailing space, or nil. They must accept three arguments: the object or element itself, its contents or nil when it isn’t recursive and the property list used as a communication channel.

Contents, when not nil, are stripped from any global indentation (although the relative one is preserved). They also always end with a single newline character.

If, for a given type, no function is found, that element or object type will simply be ignored, along with any blank line or white space at its end. The same will happen if the function returns the nil value. If that function returns the empty string, the type will be ignored, but the blank lines or white spaces will be kept.

In addition to element and object types, one function can be associated to the template symbol and another one to the plain-text symbol.

The former returns the final transcoded string, and can be used to add a preamble and a postamble to document’s body. It must accept two arguments: the transcoded string and the property list containing export options.

The latter, when defined, is to be called on every text not recognized as an element or an object. It must accept two arguments: the text string and the information channel. It is an appropriate place to protect special chars relative to the back-end.

Optionally, the function can set-up back-end specific properties (like values from specific buffer keywords) accessible from every translator function with the :options-alist keyword. See org-export-options-alist for details on the structure of the value.

As an example, the following excerpt from latex back-end definition introduces three new buffer keywords (and their headline’s property counterpart), and redefine DATE default value:

(org-export-define-backend 'latex
  ...
  :options-alist '((:date "DATE" nil "\\today" t)
                   (:date-format nil nil org-latex-date-timestamp-format)
                   (:latex-class "LATEX_CLASS" nil org-latex-default-class t)
                   (:latex-class-options "LATEX_CLASS_OPTIONS" nil nil t)
                   (:latex-header-extra "LATEX_HEADER" nil nil newline)
                   (:latex-hyperref-p nil "texht" org-latex-with-hyperref t)))

It is also possible, with :export-block keyword, to associate given block names to the export-block type. Such blocks can contain raw code that will be directly inserted in the output, as long as the corresponding translator function says so.

In the following example, in the html back-end, HTML blocks are export blocks. The associated translator function inserts their contents as-is, and ignores any other export block.

(org-export-define-backend 'html
  '(...
    (export-block . org-html-export-block)
    ... )
  :export-block "HTML")

(defun org-html-export-block (export-block contents info)
  "Transcode a EXPORT-BLOCK element from Org to HTML.
CONTENTS is nil.  INFO is a plist used as a communication
channel."
  (when (string= (org-element-property :type export-block) "HTML")
    (org-element-property :value export-block)))

Eventually org-export-define-backend allows to define back-ends specific filters. Refer to The Filter System section for more information.

If the new back-end shares most properties with another one, org-export-define-derived-backend can be used to simplify the process. In the example below, we implement a new back-end which behaves like latex excepted for headlines and the template.

(org-export-define-derived-backend 'my-latex 'latex
  :translate-alist '((headline . my-latex-headline-translator)
                     (template . my-latex-template)))

Back-ends defined with either function can be registered in the export dispatcher using special keyword :menu-entry. See defuns docstrings for more information.

Elements Attributes

Element attributes are accessed with org-element-property function. Other accessors relative to elements are org-element-type and org-element-contents.

Each greater element, element and object has a fixed set of properties attached to it. Among them, four are shared by all types: :begin and :end, which refer to the beginning and ending buffer positions of the considered element or object, :post-blank, which holds the number of blank lines, or white spaces, at its end and :parent which refers to the element or object containing it.

Greater elements, elements and objects containing objects will have :contents-begin and :contents-end properties to delimit contents. Greater elements and elements accepting affiliated keywords will also have a :post-affiliated property, referring to the buffer position after any affiliated keyword, when applicable.

In addition to these properties, each element can optionally get some more from affiliated keywords, namely: :caption, :header, :name, :plot, :results or :attr_NAME where NAME stands for the name of an export back-end.

At the lowest level, a :parent property is also attached to any string, as a text property.

Other properties, specific to each element or object, are listed below.

Babel Call

Element.

:info: Information about function being called, as returned by ob-babel-lob-get-info (string).

Bold

Recursive object.

No specific property.

Center Block

Greater element.

:hiddenp: Non-nil if the block is hidden (boolean).

Clock

Element.

:duration: Clock duration for a closed clock, or nil (string or nil).
:status: Status of current clock (symbol: closed or running).
:value: Timestamp associated to clock keyword (timestamp object).

Code

Object.

:value: Contents (string).

Comment

Element.

:value: Comments, with pound signs (string).

Comment Block

Element.

:value: Comments, without block’s boundaries (string).
:hiddenp: Non-nil if block is hidden (boolean).

Diary Sexp

Element.

:value: Full Sexp (string).

Drawer

Greater element.

:drawer-name: Drawer’s name (string).
:hiddenp: Non-nil if the drawer is hidden (boolean).

Note relative to export: The idea behind drawers is that they are transparent export-wise. By default, they should return their contents without additional decorations.

Dynamic Block

Greater element.

:arguments: Block’s parameters (string).
:block-name: Block’s name (string).
:drawer-name: Drawer’s name (string).
:hiddenp: Non-nil if the block is hidden (boolean).

Entity

Object.

:ascii: Entity’s ASCII representation (string).
:html: Entity’s HTML representation (string).
:latex: Entity’s LaTeX representation (string).
:latex-math-p: Non-nil if entity’s LaTeX representation should be in math mode (boolean).
:latin1: Entity’s Latin-1 encoding representation (string).
:name: Entity’s name, without backslash nor brackets (string).
:use-brackets-p: Non-nil if entity is written with optional brackets in original buffer (boolean).
:utf-8: Entity’s UTF-8 encoding representation (string).

Example Block

Element.

:hiddenp: Non-nil if block is hidden (boolean).
:label-fmt: Format string used to write labels in current block, if different from org-coderef-label-format (string or nil).
:language: Language of the code in the block, if specified (string or nil).
:number-lines: Non-nil if code lines should be numbered. A new value starts numbering from 1 wheareas continued resume numbering from previous numbered block (symbol: new, continued or nil).
:options: Block’s options located on the block’s opening line (string).
:parameters: Optional header arguments (string or nil).
:preserve-indent: Non-nil when indentation within the block mustn’t be modified upon export (boolean).
:retain-labels: Non-nil if labels should be kept visible upon export (boolean).
:switches: Optional switches for code block export (string or nil).
:use-labels: Non-nil if links to labels contained in the block should display the label instead of the line number (boolean).
:value: Contents (string).

Export Block

Element.

:hiddenp: Non-nil if block is hidden (boolean).
:type: Related back-end’s name (string).
:value: Contents (string).

Export Snippet

Object.

:back-end: Relative back-end’s name (string).
:value: Export code (string).

Fixed Width

Element.

:value: Contents, with colons (string).

Footnote Definition

Greater element.

:label: Label used for references (string).

Footnote Reference

Object.

:inline-definition: Footnote’s definition, when inlined (secondary string or nil).
:label: Footnote’s label, if any (string or nil).
:raw-definition: Uninterpreted footnote’s definition, when inlined (string or nil).
:type: Determine whether reference has its definition inline, or not (symbol: inline, standard).

Headline

Greater element.

In addition to the following list, any property specified in a property drawer attached to the headline will be accessible as an attribute (with an uppercase name, e.g. :CUSTOM_ID).

:archivedp: Non-nil if the headline has an archive tag (boolean).
:closed: Headline’s CLOSED reference, if any (timestamp object or nil)
:commentedp: Non-nil if the headline has a comment keyword (boolean).
:deadline: Headline’s DEADLINE reference, if any (timestamp object or nil).
:footnote-section-p: Non-nil if the headline is a footnote section (boolean).
:hiddenp: Non-nil if the headline is hidden (boolean).
:level: Reduced level of the headline (integer).
:pre-blank: Number of blank lines between the headline and the first non-blank line of its contents (integer).
:priority: Headline’s priority, as a character (integer).
:quotedp: Non-nil if the headline contains a quote keyword (boolean).
:raw-value: Raw headline’s text, without the stars and the tags (string).
:scheduled: Headline’s SCHEDULED reference, if any (timestamp object or nil).
:tags: Headline’s tags, if any, without the archive tag. (list of strings).
:title: Parsed headline’s text, without the stars and the tags (secondary string).
:todo-keyword: Headline’s TODO keyword without quote and comment strings, if any (string or nil).
:todo-type: Type of headline’s TODO keyword, if any (symbol: done, todo).

Horizontal Rule

Element.

No specific property.

Inline Babel Call

Object.

:info: Information about function called, as returned by org-babel-lob-get-info (list).

Note relative to export: Since Babel related blocks are expanded before parsing, these can safely be ignored by back-ends.

Inline Src Block

Object.

:language: Language of the code in the block (string).
:parameters: Optional header arguments (string or nil).
:value: Source code (string).

Inlinetask

Greater element.

In addition to the following list, any property specified in a property drawer attached to the headline will be accessible as an attribute (with an uppercase name, e.g. :CUSTOM_ID).

:closed: Inlinetask’s CLOSED reference, if any (timestamp object or nil)
:deadline: Inlinetask’s DEADLINE reference, if any (timestamp object or nil).
:hiddenp: Non-nil if the headline is hidden (boolean).
:level: Reduced level of the inlinetask (integer).
:priority: Headline’s priority, as a character (integer).
:raw-value: Raw inlinetask’s text, without the stars and the tags (string).
:scheduled: Inlinetask’s SCHEDULED reference, if any (timestamp object or nil).
:tags: Inlinetask’s tags, if any (list of strings).
:title: Parsed inlinetask’s text, without the stars and the tags (secondary string).
:todo-keyword: Inlinetask’s TODO keyword, if any (string or nil).
:todo-type: Type of inlinetask’s TODO keyword, if any (symbol: done, todo).

Italic

Recursive object.

No specific property.

Item

Greater element.

:bullet: Item’s bullet (string).
:checkbox: Item’s check-box, if any (symbol: on, off, trans, nil).
:counter: Item’s counter, if any. Literal counters become ordinals (integer).
:raw-tag: Uninterpreted item’s tag, if any (string or nil).
:tag: Parsed item’s tag, if any (secondary string or nil).
:hiddenp: Non-nil if item is hidden (boolean).
:structure: Full list’s structure, as returned by org-list-struct (alist).

Keyword

Element.

:key: Keyword’s name (string).
:value: Keyword’s value (string).

Note relative to export: Each back-end should, as far as possible, support a number of common keywords. These include:

Back-end relative keyword (i.e. “LATEX” for ox-latex), which should always return its value as-is.
“TOC” keyword. It accepts three common values: “headlines”, “tables” and “listings”. Also, “headlines” value can have an optional numeric argument to specify depth of the contents.
See org-export-collect-headlines, org-export-collect-tables, org-export-collect-figures and org-export-collect-listings.
“INDEX” keyword.

LaTeX Environment

Element.

:begin: Buffer position at first affiliated keyword or at the beginning of the first line of environment (integer).
:end: Buffer position at the first non-blank line after last line of the environment, or buffer’s end (integer).
:post-blank: Number of blank lines between last environment’s line and next non-blank line or buffer’s end (integer).
:value: LaTeX code (string).

LaTeX Fragment

Object.

:value: LaTeX code (string).

Line Break

Element.

No specific property.

Link

Recursive object.

:application

Name of application requested to open the link in Emacs (string or nil). It only applies to “file” type links.

:path

Identifier for link’s destination. It is usually the link part with type, if specified, removed (string).

:raw-link

Uninterpreted link part (string).

:search-option

Additional information for file location (string or nil). It only applies to “file” type links.

:type

Link’s type. Possible types (string) are:

coderef: Line in some source code,
custom-id: Specific headline’s custom-id,
file: External file,
fuzzy: Target, referring to a target object, a named element or a headline in the current parse tree,
id: Specific headline’s id,
radio: Radio-target.

It can also be any org-link-types element.

Notes relative to export:

A fuzzy link with no description should display the cross-reference number of its target. This number can be:

If link’s destination is a target object within a footnote, it will be footnote’s number.
If link’s destination is a target object in a list, it will be an item number.
If link leads to a named element, it will be the sequence number of that element among named elements of the same type.
Otherwise, it will be the number of the headline containing link’s destination.
See org-export-get-ordinal function.

Macro

Object.

:args: Arguments passed to the macro (list of strings).
:key: Macro’s name (string).
:value: Replacement text (string).

Note relative to export: Macro expansion takes place before buffer parsing. As such, export back-ends don’t have to handle: they’ll never see them.

Paragraph

Element containing objects.

No specific property.

Plain List

Greater element.

:structure: Full list’s structure, as returned by org-list-struct (alist).
:type: List’s type (symbol: descriptive, ordered, unordered).

Planning

Element.

:closed: Timestamp associated to closed keyword, if any (timestamp object or nil).
:deadline: Timestamp associated to deadline keyword, if any (timestamp object or nil).
:scheduled: Timestamp associated to scheduled keyword, if any (timestamp object or nil).

Property Drawer

Element.

:hiddenp: Non-nil if drawer is hidden (boolean).
:properties: Properties defined in the drawer (alist).

Quote Block

Greater element.

:hiddenp: Non-nil if block is hidden (boolean).

Quote Section

Element.

:value: Quoted text (string).

Radio Target

Recursive object.

:raw-value: Uninterpreted contents (string).

Section

Greater element.

No specific property.

Special Block

Greater element.

:hiddenp: Non-nil if block is hidden (boolean).
:type: Block’s name (string).

Src Block

Element.

:hiddenp: Non-nil if block is hidden (boolean).
:label-fmt: Format string used to write labels in current block, if different from org-coderef-label-format (string or nil).
:language: Language of the code in the block, if specified (string or nil).
:number-lines: Non-nil if code lines should be numbered. A new value starts numbering from 1 wheareas continued resume numbering from previous numbered block (symbol: new, continued or nil).
:parameters: Optional header arguments (string or nil).
:preserve-indent: Non-nil when indentation within the block mustn’t be modified upon export (boolean).
:retain-labels: Non-nil if labels should be kept visible upon export (boolean).
:switches: Optional switches for code block export (string or nil).
:use-labels: Non-nil if links to labels contained in the block should display the label instead of the line number (boolean).
:value: Source code (string).

Statistics Cookie

Object.

:value: Full cookie (string).

Strike Through

Recursive object.

No specific property.

Subscript

Recursive object.

:use-brackets-p: Non-nil if contents are enclosed in curly brackets (t, nil).

Superscript

Recursive object.

:use-brackets-p: Non-nil if contents are enclosed in curly brackets (t, nil).

Table

Greater element.

:tblfm: Formulas associated to the table, if any (string or nil).
:type: Table’s origin (symbol: table.el, org).
:value: Raw table.el table or nil (string or nil).

Table Cell

Recursive object.

No specific property.

Table Row

Element containing objects.

:type: Row’s type (symbol: standard, rule).

Target

Object.

:value: Target’s ID (string).

Notes relatives to export:

Target should become an anchor, if back-end permits it.
Target’s ID shouldn’t be visible on export.

Timestamp

Object.

:day-end: Day part from timestamp end. If no ending date is defined, it defaults to start day part (integer).
:day-start: Day part from timestamp start (integer).
:hour-start: Hour part from timestamp end. If no ending date is defined, it defaults to start hour part, if any (integer or nil).
:hour-start: Hour part from timestamp start, if specified (integer or nil).
:minute-start: Minute part from timestamp end. If no ending date is defined, it defaults to start minute part, if any (integer or nil).
:minute-start: Minute part from timestamp start, if specified (integer or nil).
:month-end: Month part from timestamp end. If no ending date is defined, it defaults to start month part (integer).
:month-start: Month part from timestamp start (integer).
:raw-value: Raw timestamp (string).
:repeater-type: Type of repeater, if any (symbol: catch-up, restart, cumulate or nil)
:repeater-unit: Unit of shift, if a repeater is defined (symbol: year, month, week, day, hour or nil).
:repeater-value: Value of shift, if a repeater is defined (integer or nil).
:type: Type of timestamp (symbol: active, active-range, diary, inactive, inactive-range).
:year-end: Year part from timestamp end. If no ending date is defined, it defaults to start year part (integer).
:year-start: Year part from timestamp start (integer).

Note relative to export: org.el provides tools to work on timestamps objects. In particular, back-ends usually make use of org-timestamp-translate function. Thus, in ox-html.el, the timestamp object is first translated:

(defun org-html-timestamp (timestamp contents info)
  "Transcode a TIMESTAMP object from Org to HTML.
CONTENTS is nil.  INFO is a plist holding contextual
information."
  (let ((value (org-html-plain-text
                (org-timestamp-translate timestamp) info)))
    (format "<span class=\"timestamp-wrapper\"><span class=\"timestamp\">%s</span></span>"
            (replace-regexp-in-string "--" "&ndash;" value))))

Underline

Recursive object.

No specific property.

Verbatim

Object.

:value: Contents (string).

Verse Block

Element containing objects.

:hiddenp: Non-nil if block is hidden (boolean).

The Communication Channel

This is the full list of properties available during transcode process, with their category (option or tree) and their value type.

`:author`

Author’s name.

category: option
type: string

`:back-end`

Current back-end used for transcoding.

category: tree
type: symbol

`:creator`

String to write as creation information.

category: option
type: string

`:date`

String to use as date.

category: option
type: string

`:description`

Description text for the current data.

category: option
type: string

`:email`

Author’s email.

category: option
type: string

`:exclude-tags`

Tags for exclusion of sub-trees from export process.

category: option
type: list of strings

`:export-options`

List of export options available for current process.

category: none
type: list of symbols, among subtree, body-only and visible-only.

`:exported-data`

Hash table used to memoize results from org-export-data.

category: tree
type: hash table

`:filetags`

List of global tags for buffer. Used by org-export-get-tags to get tags with inheritance.

category: option
type: list of strings

`:footnote-definition-alist`

Alist between footnote labels and their definition, as parsed data. Only non-inline footnotes are represented in this alist. Also, every definition isn’t guaranteed to be referenced in the parse tree. The purpose of this property is to preserve definitions from oblivion – i.e. when the parse tree comes from a part of the original buffer –, it isn’t meant for direct use in a back-end. To retrieve a definition relative to a reference, use org-export-get-footnote-definition instead.

category: option
type: alist (STRING . LIST)

`:headline-levels`

Maximum level being exported as an headline. Comparison is done with the relative level of headlines in the parse tree, not necessarily with their actual level.

category: option
type: integer

`:headline-numbering`

Alist between headlines’ beginning position and their numbering, as a list of numbers – cf. org-export-get-headline-number.

category: tree
type: alist (INTEGER . LIST)

`:headline-offset`

Difference between relative and real level of headlines in the parse tree. For example, a value of -1 means a level 2 headline should be considered as level 1 — cf. org-export-get-relative-level.

category: tree
type: integer

`:ignore-list`

List of elements and objects that will be unconditionally ignored during export.

category: option
type: list of elements

`:id-alist`

Alist between ID strings and destination file’s path, relative to current directory.

category: option
type: alist (STRING . STRING)

`:input-file`

Full path to input file, if any.

category: option
type: string or nil

`:keywords`

List of keywords attached to data.

category: option
type: string

`:language`

Default language used for translations.

category: option
type: string

`:parse-tree`

Whole parse tree, available at any time during transcoding.

category: option
type: list (as returned by org-element-parse-buffer)

`:preserve-breaks`

Non-nil means transcoding should preserve all line breaks.

category: option
type: symbol (nil, t)

`:section-numbers`

Non-nil means transcoding should add section numbers to headlines.

category: option
type: symbol (nil, t)

`:select-tags`

List of tags enforcing inclusion of sub-trees in transcoding. When such a tag is present, sub-trees without it are de facto excluded from the process. See :use-select-tags.

category: option
type: list of strings

`:time-stamp-file`

Non-nil means transcoding should insert a time stamp in the output.

category: option
type: symbol (nil, t)

`:translate-alist`

Alist between element and object types and transcoding functions relative to the current back-end. Special keys template and plain-text are also possible.

category: option
type: alist (SYMBOL . FUNCTION)

`:use-select-tags`

When non-nil, a select tags has been found in the parse tree. Thus, any headline without one will be filtered out. See :select-tags.

category: tree
type: interger or nil

`:with-archived-trees`

Non-nil when archived sub-trees should also be transcoded. If it is set to the headline symbol, only the archived headline’s name is retained.

category: option
type: symbol (nil, t, headline)

`:with-author`

Non-nil means author’s name should be included in the output.

category: option
type: symbol (nil, t)

`:with-clocks`

Non-nil means clock keywords should be exported.

category: option
type: symbol (nil, t)

`:with-creator`

Non-nil means a creation sentence should be inserted at the end of the transcoded string. If the value is comment, it should be commented.

category: option
type: symbol (comment, nil, t)

`:with-date`

Non nil means output should contain a date.

category: option
type: symbol (nil, t)

`:with-drawers`

Non-nil means drawers should be exported. If its value is a list of names, only drawers with such names will be transcoded.

category: option
type: symbol (nil, t) or list of strings

`:with-email`

Non-nil means output should contain author’s email.

category: option
type: symbol (nil, t)

`:with-emphasize`

Non-nil means emphasized text should be interpreted.

category: option
type: symbol (nil, t)

`:with-fixed-width`

Non-nil if transcoder should interpret strings starting with a colon as a fixed-with — verbatim — area.

category: option
type: symbol (nil, t)

`:with-footnotes`

Non-nil if transcoder should interpret footnotes.

category: option
type: symbol (nil, t)

`:with-latex`

Non-nil means latex-environment elements and latex-fragment objects should appear in export output. When this property is set to verbatim, they will be left as-is.

category: option
type: symbol (verbatim, nil, t)

`:with-planning`

Non-nil means transcoding should include planning info.

category: option
type: symbol (nil, t)

`:with-priority`

Non-nil means transcoding should include priority cookies.

category: option
type: symbol (nil, t)

`:with-smart-quotes`

Non-nil means activate smart quotes during export.

category: option
type: symbol (nil ,t)

`:with-special-strings`

Non-nil means transcoding should interpret special strings in plain text.

category: option
type: symbol (nil, t)

`:with-sub-superscript`

Non-nil means transcoding should interpret subscript and superscript. With a value of {}, only interpret those using curly brackets.

category: option
type: symbol (nil, {}, t)

`:with-tables`

Non-nil means transcoding should interpret tables.

category: option
type: symbol (nil, t)

`:with-tags`

Non-nil means transcoding should keep tags in headlines. A not-in-toc value will remove them from the table of contents, if any, nonetheless.

category: option
type: symbol (nil, t, not-in-toc)

`:with-tasks`

Non-nil means transcoding should include headlines with a TODO keyword. A todo value will only include headlines with a TODO type keyword while a done value will do the contrary. If a list of strings is provided, only tasks with keywords belonging to that list will be kept.

category: option
type: symbol (t, todo, done, nil) or list of strings

`:with-timestamps`

Non-nil means transcoding should include time stamps. Special value active (resp. inactive) ask to export only active (resp. inactive) timestamps. Otherwise, completely remove them.

category: option
type: symbol: (active, inactive, t, nil)

`:with-toc`

Non-nil means that a table of contents has to be added to the output. An integer value limits its depth.

category: option
type: symbol (nil, t or integer)

`:with-todo-keywords`

Non-nil means transcoding should include TODO keywords.

category: option
type: symbol (nil, t)

The Filter System

Filters sets are lists of functions. They allow to pre-process parse tree before export and to post-process output of each transcoded object or element.

Each function in a set must accept three arguments: a string (or a parse tree as a special case), a symbol representing the current back-end, and the communication channel, as a plist.

As an exception, functions in options filter only accept two arguments: the property list containing the export options and the back-end, as a symbol.

From the developer side, filters sets can be installed using :filters-alist keyword while defining the back-end with org-export-define-derived-backend. Each association has a key among the following symbols and a function or a list of functions as value:

:filter-babel-call
:filter-bold
:filter-center-block
:filter-clock
:filter-code
:filter-comment
:filter-comment-block
:filter-drawer
:filter-dynamic-block
:filter-entity
:filter-example-block
:filter-export-block
:filter-export-snippet
:filter-final-output
:filter-fixed-width
:filter-footnote-definition
:filter-footnote-reference
:filter-headline
:filter-horizontal-rule
:filter-inline-babel-call
:filter-inline-src-block
:filter-inlinetask
:filter-italic
:filter-item
:filter-keyword
:filter-latex-environment
:filter-latex-fragment
:filter-line-break
:filter-link
:filter-macro
:filter-node-property
:filter-options
:filter-paragraph
:filter-parse-tree
:filter-plain-list
:filter-plain-text
:filter-planning
:filter-property-drawer
:filter-quote-block
:filter-quote-section
:filter-radio-target
:filter-section
:filter-special-block
:filter-src-block
:filter-strike-through
:filter-statistics-cookie
:filter-subscript
:filter-superscript
:filter-table
:filter-table-cell
:filter-table-row
:filter-target
:filter-timestamp
:filter-underline
:filter-verbatim
:filter-verse-block

For example, ascii back-end implements a filter that makes sure headlines end with two blank lines:

(org-export-define-backend 'ascii
  ...
  :filters-alist '((:filter-headline . org-ascii-filter-headline-blank-lines)
                   (:filter-section . org-ascii-filter-headline-blank-lines)))

(defun org-ascii-filter-section-blank-lines (headline back-end info)
  "Filter controlling number of blank lines after a section."
  (let ((blanks (make-string 2 ?\n)))
    (replace-regexp-in-string "\n\\(?:\n[ \t]*\\)*\\'" blanks headline)))

The Toolbox

A whole set of tools is available to help build new exporters. Any function general enough to have its use across a couple of back-ends may be added here.

Many of them are high-level access to properties from the communication channel. As such, they should be preferred to straight access to communication channel, when possible.

`org-element-adopt-element`

Add an element to the contents of another element.

`org-element-set-element`

Replace an element with another in the parse tree.

`org-export-activate-smart-quotes`

Transform quotes and apostrophes into their “smart” counterpart in a given string.

It should be used after a check against :with-smart-quotes value in communication channel.

Since this function needs the original string, it may be useful to apply others transformations (i.e. characters protection) on a copy of that string and provide the pristine original string as the optional argument.

For example, in html back-end, it is necessary to protect “<”, “>” and “&” characters before calling this function. Here’s an excerpt of its plain-text transcoder:

(let ((output text))
  ;; Protect following characters: <, >, &.
  (setq output (org-html-encode-plain-text output))
  ;; Handle smart quotes.  Be sure to provide original string since
  ;; OUTPUT may have been modified.
  (when (plist-get info :with-smart-quotes)
    (setq output (org-export-activate-smart-quotes output :html info text)))
  ...
  ;; Return value.
  output)

`org-export-collect-figures`

Return a list of all exportable figures in parse tree.

Used to build a table of figures.

`org-export-collect-footnote-definitions`

List actually used footnotes definitions in order to add footnote listings throughout the transcoded data.

Feed it with the whole parse tree to get the full footnote listing. Feed it with the current headline to get partial footnote listing relative to that headline.

Number, label, if any, and definition are provided.

`org-export-collect-headlines`

Return a list of all exportable headlines, possibly limited to a certain depth.

Used to build a table of contents.

`org-export-collect-listings`

Return a list of all exportable source blocks with a caption or a name in parse tree.

Used to build a table of listings.

`org-export-collect-tables`

Return a list of all exportable tables with a caption or a name in parse tree.

Used to build a table of tables.

`org-export-data`

Transcode a given element, object, secondary string or string using current back-end.

It is used primarily to transcode secondary strings, like :title. For example beamer back-end uses the following:

(defun org-beamer-template (contents info)
  (let ((title (org-export-data (plist-get info :title) info)))
    ...))

`org-export-data-with-backend`

Recursively convert some data (an element, an object, a secondary string or a string) using another backend.

`org-export-data-with-translations`

Recursively convert some data (an element, an object, a secondary string or a string) using a given translation table, which basically acts as an anonymous back-end.

`org-export-first-sibling-p`

Non-nil if an headline is the first of its siblings.

Used to know when to start a list if headline’s relative level is below the one specified in :headline-levels property.

`org-export-footnote-first-reference-p`

Non-nil when a footnote reference if the first reference relative to its definition.

Used when a back-end needs to attach the footnote definition only to the first occurrence of the corresponding label.

`org-export-format-code-default`

Return contents of a src-block or example-block element in a format suited for raw text or verbatim output. More specifically, it takes care of line numbering and labels integration depending of element’s switches, but no formatting is otherwise applied to source code.

`org-export-format-code`

Helper function to format source code. It applies a given function on each line of the code, passing current line number and associated code reference label, if any, as arguments.

`org-export-get-alt-title`

Return the alternative title for a given headline as a secondary string. If no such title is found, it will return its main title.

This function is useful when building a table of contents.

`org-export-get-caption`

Return the caption of a given element, as a secondary string. With an optional argument, return the short caption instead.

As an example, ascii back-end, when creating a list of listings, uses the following:

(defun org-ascii--list-listings (keyword info)
  (let ((title (org-ascii--translate "List of Listings" info)))
    (concat title "\n"
            ...
            (mapconcat
             (lambda (src-block)
               ...
               ;; Use short name in priority, if available.
               (let ((caption (or (org-export-get-caption src-block t)
                                  (org-export-get-caption src-block))))
                 (org-export-data caption info)
                 ...))
             (org-export-collect-listings info) "\n"))))

`org-export-get-category`

Return category associated to a given element or object. Unlike to the :category property from headlines and inlinetasks, this function handles inheritance and CATEGORY keywords. Therefore, it should be the preferred way to retrieve a category during export.

`org-export-get-coderef-format`

Return an appropriate format string for code reference links.

`org-export-get-date`

Returns a date, as a string or a secondary string. It handles org-export-date-timestamp-format.

Note that :with-date property in communication channel should be checked prior to use this, as shown in the following example extracted from ox-latex.el:

(let ((date (and (plist-get info :with-date) (org-export-get-date info))))
  (format "\\date{%s}\n" (org-export-data date info)))

`org-export-get-footnote-definition`

Retrieve the footnote definition relative to a given footnote reference.

If the footnote definition in inline, it is returned as a secondary string. Otherwise, it is full Org data.

`org-export-get-footnote-number`

Return the ordinal attached to a footnote reference or definition.

`org-export-get-genealogy`

Return flat list of current object or element’s parents from closest to farthest, along with their contents.

`org-export-get-headline-number`

Return the section number of an headline, as a list of integers.

`org-export-get-loc`

Return count of accumulated lines of code from previous line-numbered example-block and src-block elements, according to current element’s switches.

In other words, the first line of code in the current block is supposed to be numbered as the returned value plus one, assuming its :number-lines properties is non-nil.

`org-export-get-next-element`

Return element (resp. object or string) after an element (resp. object), or nil.

`org-export-get-node-property`

Return the node property associated to an element or object. If the element is an headline, this is equivalent to reading the property with org-element-property.

Though, this function can optionally handle inheritance.

`org-export-get-ordinal`

Associate a sequence number to any object or element. It is meant to be used to build captions.

Also, it could be applied on a fuzzy link’s destination, since such links are expected to be replaced with the sequence number of their destination, provided they have no description.

Taken from ascii back-end, the following example shows how fuzzy links could be handled :

(let ((type (org-element-property :type link)))
  (cond
   ...
   ;; Do not apply a special syntax on fuzzy links pointing to targets.
   ((string= type "fuzzy")
    (let ((destination (org-export-resolve-fuzzy-link link info)))
      ;; If link has a description, use it.
      (if (org-string-nw-p desc) desc
        (when destination
          (let ((number (org-export-get-ordinal destination info)))
            (when number
              (if (atom number) (number-to-string number)
                (mapconcat 'number-to-string number "."))))))))
   ...))

`org-export-get-parent-element`

Return the first element containing provided object, if any. Return nil otherwise.

`org-export-get-parent-headline`

Return the headline containing provided element or object, if any. Return nil otherwise.

`org-export-get-parent`

Return closest element containing current element or object, if any. Return nil otherwise.

`org-export-get-previous-element`

Return element (resp. object or string) before an element (resp. object), or nil.

`org-export-get-relative-level`

Return headline level, relatively to the lower headline level in the parsed tree. It is meant to be used over :level headline’s property.

`org-export-get-table-cell-at`

Return exportable cell object at a given position, or nil. Hence, position (0 . 0) will always point to the first exportable cell in the table.

`org-export-get-tags`

Return list of exportable tags attached to a given headline or inlinetask element. With an optional argument, tags are inherited from parent headlines and FILETAGS keywords.

In particular, it removes select tags and exclude tags. The function also accepts an arbitrary list of tags for further cleaning.

For example, latex back-end uses the following snippet in the inlinetask transcode function.

 (let ((title (org-export-data (org-element-property :title inlinetask) info))
    (todo (and (plist-get info :with-todo-keywords)
               (let ((todo (org-element-property :todo-keyword inlinetask)))
                 (and todo (org-export-data todo info)))))
    (todo-type (org-element-property :todo-type inlinetask))
    (tags (and (plist-get info :with-tags)
               (org-export-get-tags inlinetask info)))
    (priority (and (plist-get info :with-priority)
                   (org-element-property :priority inlinetask))))
...)

`org-export-headline-numbered-p`

Non nil when a given headline should be numbered.

`org-export-inline-image-p`

Non-nil when the link provided should be considered as an inline image. Note that it always return nil when the link has a description.

It accepts an optional set of rules in order to tweak the definition of an inline image, which is, by default, any link targetting a local file whose extension is either “png”, “jpeg”, “jpg”, “gif”, “tiff”, “tif”, “xbm”, “xpm”, “pbm”, “pgm” or “ppm”.

A set of rules consists in an alist whose key is a type of link, as a string, and whose value is a regexp matching link’s path. As an example, html back-end uses the following rules:

'(("file" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'")
  ("http" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'")
  ("https" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'"))

`org-export-last-sibling-p`

Non-nil if an headline is the last of its siblings.

Used to know when to close a list if headline’s relative level is below the one specified in :headline-levels property.

`org-export-number-to-roman`

Convert numbers to roman numbers. It can be used to provide roman numbering for headlines and numbered lists.

`org-export-read-attribute`

Read a property from a given element as a plist. It can be used to normalize affiliated keywords’ syntax. For example, the following affiliated keywords:

#+ATTR_HTML: :width 10 :height 5
#+ATTR_HTML: :file "filename.ext"

would be returned as:

'(:width 10 :height 5 :file "filename.ext")

`org-export-resolve-coderef`

Search for a code reference within src-block and example-block elements. Return corresponding –possibly accumulated– line number, or reference itself, depending on container’s switches.

`org-export-resolve-fuzzy-link`

Search destination of a fuzzy link — i.e. it has a fuzzy :type attribute – within the parsed tree, and return that element, object, or nil.

`org-export-resolve-id-link`

Search headline targetted by an id link — i.e. it has a id or custom-id :type attribute — within the parse tree. Return the matching headline in the tree, the name of the external file, as a string, or nil.

`org-export-resolve-radio-link`

Return first radio target object matching a radio link — that is with a radio :type attribute — in the parse tree, or nil.

Typically, target’s contents are exported through org-export-data and used as link description, as in the following excerpt from ox-latex.el:

(defun org-latex-link (link desc info)
  (let* ((type (org-element-property :type link))
         ...)
    (cond
     ...
     ((string= type "radio")
      (let ((destination (org-export-resolve-radio-link link info)))
        (when destination
          (format "\\hyperref[%s]{%s}"
                  (org-export-solidify-link-text path)
                  (org-export-data (org-element-contents destination) info)))))
     ...)))

`org-export-solidify-link-text`

Normalize a string, replacing most non-standard characters with hyphens.

Used to turn targets names into safer versions for links.

`org-export-table-cell-address`

Return row and column of a given cell object. Positions are 0-indexed and only exportable rows and columns are considered. The function returns nil if called on a non-exportable cell.

`org-export-table-cell-alignment`

Return expected alignment for the contents of a given cell object. It can be either left, right or center.

`org-export-table-cell-borders`

Indicate expected borders for a given cell object. When non-nil, return value is a list of symbols among top, bottom, above, below, left and right.

Special values top and bottom only happen for cells in, respectively, the first and the last exportable rows.

`org-export-table-cell-ends-colgroup-p`

Non-nil when a table cell object ends a column group.

`org-export-table-cell-starts-colgroup-p`

Non-nil when a table cell object starts a column group.

`org-export-table-cell-width`

Return expected width for contents of a given cell object.

Only width specified explicitely through meta-data is considered. If no such information can be found, return nil instead.

Some back-end may still need to know the actual width of exported cell’s contents in order to compute column’s width. In that case, every cell in the column must be transcoded in order to find the widest one. The snippet below, extracted from ox-ascii.el illustrates a possible implementation.

(or (org-export-table-cell-width table-cell info)
    (let* ((max-width 0)
           (table (org-export-get-parent-table table-cell info))
           (specialp (org-export-table-has-special-column-p table))
           (col (cdr (org-export-table-cell-address table-cell info))))
      (org-element-map
       table 'table-row
       (lambda (row)
         ;; For each exportable row, get the cell at column COL and
         ;; transcode its contents.  Then compare its length with
         ;; MAX-WIDTH and keep the greater of two.
         (setq max-width
               (max (length
                     (org-export-data
                      (org-element-contents
                       (elt (if specialp (car (org-element-contents row))
                              (org-element-contents row))
                            col))
                      info))
                    max-width)))
       info)
      max-width))

`org-export-table-dimensions`

Return the number of exportable rows and columns in a given table.

`org-export-table-has-header-p`

Non-nil when table has at least two row groups.

`org-export-table-has-special-column-p`

Non-nil when first column in the table only contains meta-data.

`org-export-table-row-ends-header-p`

Non-nil when a table row element ends table’s header.

`org-export-table-row-ends-rowgroup-p`

Non-nil when a a table row element ends a rowgroup, header included.

See also: org-export-table-row-ends-header-p, org-export-table-row-group, org-export-table-row-starts-header-p, org-export-table-row-starts-rowgroup-p.

`org-export-table-row-group`

Return row group number for a given table row element.

See also: org-export-table-row-ends-header-p, org-export-table-row-ends-rowgroup-p, org-export-table-row-starts-header-p, org-export-table-row-starts-rowgroup-p.

`org-export-table-row-is-special-p`

Non-nil a given table row element only contains meta-data.

`org-export-table-row-starts-header-p`

Non-nil when a table row element starts table’s header.

See also: org-export-table-row-ends-header-p, org-export-table-row-ends-rowgroup-p, org-export-table-row-group, org-export-table-row-starts-rowgroup-p.

`org-export-table-row-starts-rowgroup-p`

Non-nil when a table row element starts a rowgroup, header included.

See also: org-export-table-row-ends-header-p, org-export-table-row-ends-rowgroup-p, org-export-table-row-group, org-export-table-row-starts-header-p.

`org-export-translate`

Translate a string, i.e. “Table of Contents”, according to language specification.

Refer to org-export-dictionary variable for the list of all supported strings.

`org-export-unravel-code`

Clean source code from an example-block or a src-block element and extract code references out of it.

Its purpose is to allow to transform raw source code first and then integrate line numbers or references back into the final output. That final task can be achieved with the help of org-export-format-code function.

`org-export-with-backend`

Export an element or object using locally another back-end.

In a derived back-end, it may be used as a fall-back function once all specific cases have been handled. Thus, beamer back-end, derived from latex, takes care of every internal link type and delagates everything else to its parent back-end:

(let ((type (org-element-property :type link))
      (path (org-element-property :path link)))
  (cond
   ;; Handle every internal link type, but be careful to ignore "id"
   ;; type links pointing to external files.
   ((equal type "radio") ...)
   ((and (member type '("custom-id" "fuzzy" "id"))
         (let ((destination (if (string= type "fuzzy")
                                (org-export-resolve-fuzzy-link link info)
                              (org-export-resolve-id-link link info))))
           (case (org-element-type destination)
             (headline ...)
             (target ...)))))
   ;; Otherwise, use `latex' back-end.
   (t (org-export-with-backend 'latex link contents info))))

Interactive functions

Once the back-end is complete, interactive functions have to be offered for the user to use it. Depending on the desired output, three functions are provided to help in this task, along with a wrapper function allowing to make export asynchronous.

Hence, org-export-to-buffer may be used if the expected output is a temporary buffer whereas org-export-to-file will be used when exporting to a file. In the latter case, org-export-output-file-name can be useful to guess the name of the output file — though, don’t use it in an external process, since it will ask the user for a file name when guessing fails. At the lowest level, org-export-as returns the output as a string. It may be used in conjunction with org-export-async-start in order to export asynchronously to a temporary buffer, since buffer creation cannot happen in the external process.

When exporting in background, the output is expected to be displayed in the Export Stack. The function org-export-add-to-stack helps doing so.

While it is suggested to have a look at their respective docstring, the following examples illustrate how to combine all these functions:

Export to a temporary buffer:

;;;###autoload
(defun org-latex-export-as-latex
(&optional async subtreep visible-only body-only ext-plist)
  (interactive)
  (if async
      (org-export-async-start
          (lambda (output)
            (with-current-buffer (get-buffer-create "*Org E-LATEX Export*")
              (erase-buffer)
              (insert output)
              (goto-char (point-min))
              (LaTeX-mode)
              (org-export-add-to-stack (current-buffer) 'latex)))
        `(org-export-as 'latex ,subtreep ,visible-only ,body-only ',ext-plist))
    (let ((outbuf (org-export-to-buffer 'latex "*Org E-LATEX Export*"
                                 subtreep visible-only body-only ext-plist)))
      (with-current-buffer outbuf (LaTeX-mode))
      (when org-export-show-temporary-export-buffer
        (switch-to-buffer-other-window outbuf)))))

Export to a file:

;;;###autoload
(defun org-latex-export-to-latex
  (&optional async subtreep visible-only body-only ext-plist)
  (interactive)
  (let ((outfile (org-export-output-file-name ".tex" subtreep)))
    (if async
        (org-export-async-start
            (lambda (f) (org-export-add-to-stack f 'latex))
          `(expand-file-name
            (org-export-to-file
             'latex ,outfile ,subtreep ,visible-only ,body-only ',ext-plist)))
      (org-export-to-file
       'latex outfile subtreep visible-only body-only ext-plist))))

It may also be interesting to provide a publishing function for the back-end. Such function must accept three arguments: a plist containing properties relative to the project being exported, the name of the current file being published and the publishing directory. It often is a simple wrapper around org-publish-org-to function defined in ox-publish.el, as shown in the following example:

(defun org-html-publish-to-html (plist filename pub-dir)
  (org-publish-org-to 'html filename ".html" plist pub-dir))