UP | HOME

Support via Liberapay

Org Export Reference Documentation

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

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

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, use org-export-define-derived-backend to simplify the creation process. In the example below, we implement a new back-end which behaves like latex except 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.

Eventually, you can create an anonymous back-end with org-export-create-backend. It can inherit from an existing back-end or define everything from scratch.

Such a back-end doesn’t appear in any user-facing menu, however. It is meant to be used as an argument for org-export-with-backend and org-export-data-with-backend, for exporting rules with a limited scope.

For example, entries in a table of contents usually link to headings in the document. As a consequence, targets, footnote references, and external links may be ignored from the table of contents. As an example, the HTML export back-end prunes various link-like types from table of contents’ entries – here toc-entry – with the following code:

(org-export-data-with-backend
 toc-entry
 (org-export-create-backend
  :parent 'html
  :transcoders `((footnote-reference . ,#'ignore)
                     (link . ,(lambda (l c i)
                                (or c
                                    (org-export-data
                                     (org-element-property :raw-link l)
                                     i))))
                     (radio-target . ,(lambda (_r c _i) c))
                     (target . ,#'ignore)))
 info)

Since this is a common anonymous back-end, the above is readily available calling org-export-toc-entry-backend.

The Communication Channel

During export process, every function has access to a number of properties. They are of two types:

  1. Environment options are collected once at the very beginning of the process, out of the original buffer and configuration. Collecting them is handled by org-export-get-environment function.

    Most environment options are defined through the org-export-options-alist variable.

  2. Tree properties are extracted directly from the parsed tree, just before export, by org-export-collect-tree-properties.

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

: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

:output-file

Full path to output file, if any.

category
option
type
string or nil

: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
integer 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 alter 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-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-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-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, e.g., when a “#+TOC: headlines 2” keyword value pair is specified.

See also: org-export-collect-tables, org-export-collect-figures, org-export-collect-listings, org-export-excluded-from-toc-p.

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, e.g., when a “#+TOC: listings” keyword value pair is specified.

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, e.g., when a “#+TOC: tables” keyword value pair is specified.

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-toc-entry-backend.

org-export-excluded-from-toc-p

Non-nil if a headline must not appear in a table of contents.

See also : org-export-collect-headlines.

org-export-file-uri

Return URI associated to a given filename.

org-export-first-sibling-p

Non-nil if an element or object is the first of its siblings.

It may be 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.

Its scope can be arbitrary narrowed, e.g., to a headline.

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

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

Its scope can be arbitrary narrowed, e.g., to get the numbering relative to a headline.

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

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

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

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

org-export-get-parent-element

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

See also: 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-next-element, org-export-get-parent, org-export-get-parent-paragraph, 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-next-element, org-export-get-parent, org-export-get-parent-headline, org-export-get-parent-paragraph.

org-export-get-reference

Return unique reference associated to an element or an object, as a string.

Since it consists of alphanumerical characters only, it can be used as internal references for back-ends needing them.

For example, ox-latex.el uses it to translate radio targets into \label{} and links to radio targets into \hyperref{}:

(defun org-latex-radio-target (radio-target text info)
  (format "\\label{%s}%s" (org-export-get-reference radio-target info) text))

(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)))
        (if (not destination) desc
          (format "\\hyperref[%s]{%s}"
                  (org-export-get-reference destination info)
                  desc))))
     ...)))

See also: org-export-inline-image-p, org-export-resolve-id-link, org-export-resolve-fuzzy-link, org-export-resolve-radio-link.

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 targeting 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-get-reference, org-export-get-coderef-format, org-export-resolve-fuzzy-link.

org-export-last-sibling-p

Non-nil if an element or object is the last of its siblings.

It may be 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-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 explicitly 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

org-export-table-row-group

org-export-table-row-in-header-p

Non-nil if a given table row element belongs to table’s header. Always nil if the table contains no header or the row is a separator.

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

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

Non-nil if 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

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-toc-entry-backend

Generate an anonymous export back-end appropriate for entries in table of contents.

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

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 delegates 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))))
           (pcase (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-timestamp-translate

Translate a timestamp object according to org-time-stamp-custom-formats, which see.

It should be used whenever exported timestamps are expected to comply to user-defined display. As an example, in the following excerpt from, ox-html.el, the timestamp object is first turned into a custom string:

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

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