Org Export Reference Documentation

Table of Contents

{Back to Worg’s index}

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.

:value
Raw call, as Org syntax (string).

Bold

Recursive object.

No specific property.

Center Block

Greater element.

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).

Diary Sexp

Element.

:value
Full Sexp (string).

Drawer

Greater element.

:drawer-name
Drawer’s name (string).

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).

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.

: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 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

Recursive object.

:label
Footnote’s label, if any (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).
: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.

:value
Raw call, as Org syntax (string).

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).
: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).
: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:

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.

:properties
Properties defined in the drawer (alist).

Quote Block

Greater element.

Radio Target

Recursive object.

:raw-value
Uninterpreted contents (string).

Section

Greater element.

No specific property.

Special Block

Greater element.

:type
Block’s name (string).
:raw-value
Raw contents in block (string).

Src Block

Element.

: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).
:warning-type
Type of warning, if any (symbol: all, first or nil)
:warning-unit
Unit of delay, if one is defined (symbol: year, month, week, day, hour or nil).
:warning-value
Value of delay, if one is defined (integer or nil).
: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.

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
structure

: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-buffer

Original buffer name.

category
option
type
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-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-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.

See also: org-element-set-element

org-element-set-element

Replace an element with another in the parse tree.

See also: org-element-adopt-element.

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.

See also: org-export-collect-headlines, org-export-collect-tables, org-export-collect-listings.

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.

See also: org-export-footnote-first-reference-p, org-export-get-footnote-definition, org-export-get-footnote-number.

org-export-collect-headlines

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

Used to build a table of contents.

See also: org-export-collect-tables, org-export-collect-figures, org-export-collect-listings.

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.

See also: org-export-collect-headlines, org-export-collect-tables, org-export-collect-figures.

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.

See also: org-export-collect-headlines, org-export-collect-figures, org-export-collect-listings.

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.

See also: org-export-with-backend, org-export-data-with-translations

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.

See also: org-export-with-backend, org-export-data-with-backend

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.

See also: org-export-get-relative-level, org-export-number-to-roman, org-export-last-sibling-p.

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.

See also: org-export-collect-footnote-definitions, org-export-get-footnote-definition, org-export-get-footnote-number.

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.

See also: org-export-format-code, org-export-unravel-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.

See also: org-export-format-code-default, org-export-get-loc, org-export-unravel-code.

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"))))

See also: org-export-read-attribute.

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.

See also: org-export-get-node-property.

org-export-get-coderef-format

Return an appropriate format string for code reference links.

See also: org-export-resolve-coderef.

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.

See also: org-export-collect-footnote-definitions, org-export-footnote-first-reference-p, org-export-get-footnote-number.

org-export-get-footnote-number

Return the ordinal attached to a footnote reference or definition.

See also: org-export-collect-footnote-definitions, org-export-footnote-first-reference-p, org-export-get-footnote-definition.

org-export-get-genealogy

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

See also: org-export-get-next-element, org-export-get-parent, org-export-get-parent-headline, org-export-get-parent-paragraph, org-export-get-previous-element.

org-export-get-headline-number

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

See also: org-export-headline-numbered-p, org-export-number-to-roman.

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.

See also: org-export-format-code, org-export-unravel-code.

org-export-get-next-element

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

See also: org-export-get-genealogy, org-export-get-parent, org-export-get-parent-headline, org-export-get-parent-paragraph, org-export-get-previous-element.

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.

See also: org-export-get-category.

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 "."))))))))
   ...))

See also : org-export-resolve-fuzzy-link

org-export-get-parent-element

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

See also: org-export-get-genealogy, org-export-get-parent, org-export-get-parent-headline, org-export-get-previous-element, org-export-get-next-element.

org-export-get-parent-headline

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

See also: org-export-get-genealogy, org-export-get-next-element, org-export-get-parent, org-export-get-parent-paragraph, org-export-get-previous-element.

org-export-get-parent

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

See also: org-export-get-genealogy, org-export-get-next-element, org-export-get-parent-paragraph, org-export-get-parent-headline, org-export-get-previous-element.

org-export-get-previous-element

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

See also: org-export-get-genealogy, org-export-get-next-element, org-export-get-parent, org-export-get-parent-headline, org-export-get-parent-paragraph.

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.

See also:org-export-first-sibling-p, org-export-get-headline-number,org-export-headline-numbered-p, org-export-last-sibling-p.

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.

See also: org-export-table-cell-address, org-export-table-dimensions.

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.

See also: org-export-get-headline-number, org-export-get-relative-level.

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\\)\\'"))

See also: org-export-solidify-link-text, org-export-get-coderef-format, org-export-resolve-fuzzy-link.

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.

See also: org-export-get-relative-level, org-export-number-to-roman, org-export-first-sibling-p.

org-export-number-to-roman

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

See also: org-export-get-headline-number.

org-export-raw-special-block-p

Non nil when a given special block should be inserted as-is in the final output.

This fuction should be used as a first check in a special block translator, in order to know if contents are to be processed or not. In the latter case, one can extract raw contents through :raw-value property, as shown in the following excerpt from latex back-end:

(defun org-latex-special-block (special-block contents info)
  "Transcode a SPECIAL-BLOCK element from Org to LaTeX.
CONTENTS holds the contents of the block.  INFO is a plist
holding contextual information."
  (if (org-export-raw-special-block-p special-block info)
      (org-remove-indentation (org-element-property :raw-value special-block))
    (let ((type (downcase (org-element-property :type special-block)))
          (opt (org-export-read-attribute :attr_latex special-block :options)))
      (concat (format "\\begin{%s}%s\n" type (or opt ""))
              (org-latex--caption/label-string special-block info)
              contents
              (format "\\end{%s}" type)))))

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")

See also: org-export-get-caption.

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.

See also : org-export-get-coderef-format, org-export-resolve-fuzzy-link, org-export-resolve-id-link, org-export-resolve-radio-link.

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.

See also: org-export-get-table-cell-at, org-export-table-dimensions.

org-export-table-cell-alignment

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

See also: org-export-table-cell-borders, org-export-table-cell-width.

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.

See also: org-export-table-cell-alignment, org-export-table-cell-width.

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

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

See also: org-export-table-cell-starts-colgroup-p.

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

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

See also: org-export-table-cell-ends-colgroup-p.

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))

See also: org-export-table-cell-alignment, org-export-table-cell-borders.

org-export-table-dimensions

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

See also: org-export-get-table-cell-at, org-export-table-cell-address.

org-export-table-has-header-p

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

See also: org-export-table-has-special-column-p, org-export-table-row-is-special-p.

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

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

See also: org-export-table-has-header-p, org-export-table-row-is-special-p.

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

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.

See also: org-export-table-has-header-p, org-export-table-has-special-column-p.

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.

See also: org-export-format-code, org-export-format-code-default, org-export-get-loc.

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))))

See also: org-export-data-with-backend, org-export-data-with-translations

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.

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

  1. Export to a temporary buffer:

    ;;;###autoload
    (defun org-latex-export-as-latex
    (&optional async subtreep visible-only body-only ext-plist)
      (interactive)
      (org-export-to-buffer 'latex "*Org LATEX Export*"
        async subtreep visible-only body-only ext-plist (lambda () (LaTeX-mode))))
    
  2. 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)))
        (org-export-to-file 'latex outfile
          async 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))

Documentation from the http://orgmode.org/worg/ website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.