1 #+TITLE: Org Export Reference Documentation
2 #+AUTHOR: Nicolas Goaziou
3 #+EMAIL: mail@nicolasgoaziou.fr
4 #+OPTIONS: H:3 num:nil toc:t \n:nil ::t |:t ^:t -:t f:t *:t tex:t d:(HIDE) tags:not-in-toc ':t
5 #+STARTUP: align fold nodlcheck hidestars oddeven lognotestate
6 #+SEQ_TODO: TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
7 #+TAGS: Write(w) Update(u) Fix(f) Check(c) NEW(n)
12 [[file:../index.org][{Back to Worg's index}]]
14 This document is aimed at back-end developers for the generic export
15 engine =ox.el=. It assumes a good understanding of [[./org-syntax.org][Org syntax]] from
18 It covers [[#back-end][back-end creation]] process, properties offered by the
19 [[#communication][communication channel]] during export, the [[#filter-system][filter system]] internals and
20 [[#toolbox][tools]] provided by the exporter. Eventually, expected [[#interactive][interactive
21 functions]] aimed at end-users are explained in the last part of this
30 A back-end is defined with ~org-export-define-backend~ function. It
31 requires two mandatory arguments: the back-end name and its
32 translation table, an alist that associates element and object types
33 to translator functions. According to the documentation:
36 These functions should return a string without any trailing space,
37 or nil. They must accept three arguments: the object or element
38 itself, its contents or nil when it isn't recursive and the property
39 list used as a communication channel.
41 Contents, when not nil, are stripped from any global indentation
42 (although the relative one is preserved). They also always end with
43 a single newline character.
45 If, for a given type, no function is found, that element or object
46 type will simply be ignored, along with any blank line or white
47 space at its end. The same will happen if the function returns the
48 nil value. If that function returns the empty string, the type will
49 be ignored, but the blank lines or white spaces will be kept.
51 In addition to element and object types, one function can be
52 associated to the ~template~ symbol and another one to the
55 The former returns the final transcoded string, and can be used to
56 add a preamble and a postamble to document's body. It must accept
57 two arguments: the transcoded string and the property list
58 containing export options.
60 The latter, when defined, is to be called on every text not
61 recognized as an element or an object. It must accept two
62 arguments: the text string and the information channel. It is an
63 appropriate place to protect special chars relative to the back-end.
66 Optionally, the function can set-up back-end specific properties (like
67 values from specific buffer keywords) accessible from every translator
68 function with the ~:options-alist~ keyword. See
69 ~org-export-options-alist~ for details on the structure of the value.
71 As an example, the following excerpt from ~latex~ back-end
72 definition introduces three new buffer keywords (and their
73 headline's property counterpart), and redefine ~DATE~ default value:
75 #+BEGIN_SRC emacs-lisp
76 (org-export-define-backend 'latex
78 :options-alist '((:date "DATE" nil "\\today" t)
79 (:date-format nil nil org-latex-date-timestamp-format)
80 (:latex-class "LATEX_CLASS" nil org-latex-default-class t)
81 (:latex-class-options "LATEX_CLASS_OPTIONS" nil nil t)
82 (:latex-header-extra "LATEX_HEADER" nil nil newline)
83 (:latex-hyperref-p nil "texht" org-latex-with-hyperref t)))
86 Eventually ~org-export-define-backend~ allows to define back-ends
87 specific filters. Refer to [[#filter-system][The Filter System]] section for more
90 If the new back-end shares most properties with another one, use
91 ~org-export-define-derived-backend~ to simplify the creation
92 process. In the example below, we implement a new back-end which
93 behaves like ~latex~ except for headlines and the template.
95 #+BEGIN_SRC emacs-lisp
96 (org-export-define-derived-backend 'my-latex 'latex
97 :translate-alist '((headline . my-latex-headline-translator)
98 (template . my-latex-template)))
101 Back-ends defined with either function can be registered in the export
102 dispatcher using special keyword =:menu-entry=. See defuns docstrings
103 for more information.
105 Eventually, you can create an anonymous back-end with
106 ~org-export-create-backend~. It can inherit from an existing
107 back-end or define everything from scratch.
109 Such a back-end doesn't appear in any user-facing menu, however. It
110 is meant to be used as an argument for ~org-export-with-backend~ and
111 ~org-export-data-with-backend~, for exporting rules with a limited
114 For example, entries in a table of contents usually link to headings
115 in the document. As a consequence, targets, footnote references,
116 and external links may be ignored from the table of contents. As an
117 example, the HTML export back-end prunes various link-like types
118 from table of contents' entries -- here ~toc-entry~ -- with the
121 #+BEGIN_SRC emacs-lisp
122 (org-export-data-with-backend
124 (org-export-create-backend
126 :transcoders `((footnote-reference . ,#'ignore)
127 (link . ,(lambda (l c i)
130 (org-element-property :raw-link l)
132 (radio-target . ,(lambda (_r c _i) c))
133 (target . ,#'ignore)))
137 Since this is a common anonymous back-end, the above is readily
138 available calling ~org-export-toc-entry-backend~.
140 * The Communication Channel
142 :CUSTOM_ID: communication
145 During export process, every function has access to a number of
146 properties. They are of two types:
148 1. Environment options are collected once at the very beginning of
149 the process, out of the original buffer and configuration.
150 Collecting them is handled by ~org-export-get-environment~
153 Most environment options are defined through the
154 ~org-export-options-alist~ variable.
156 2. Tree properties are extracted directly from the parsed tree, just
157 before export, by ~org-export-collect-tree-properties~.
159 This is the full list of properties available during transcode
160 process, with their category (=option= or =tree=) and their value
172 Current back-end used for transcoding.
179 String to write as creation information.
186 String to use as date.
193 Description text for the current data.
207 Tags for exclusion of sub-trees from export process.
210 - type :: list of strings
214 List of export options available for current process.
217 - type :: list of symbols, among ~subtree~, ~body-only~ and
222 Hash table used to memoize results from [[#data][~org-export-data~]].
229 List of global tags for buffer. Used by [[#get-tags][~org-export-get-tags~]] to
230 get tags with inheritance.
233 - type :: list of strings
235 ** ~:headline-levels~
237 :CUSTOM_ID: headline-levels
240 Maximum level being exported as an headline. Comparison is done
241 with the relative level of headlines in the parse tree, not
242 necessarily with their actual level.
247 ** ~:headline-numbering~
249 Alist between headlines' beginning position and their numbering, as
250 a list of numbers – cf. [[#get-headline-number][~org-export-get-headline-number~]].
253 - type :: alist (INTEGER . LIST)
255 ** ~:headline-offset~
257 Difference between relative and real level of headlines in the
258 parse tree. For example, a value of -1 means a level 2 headline
259 should be considered as level 1 —
260 cf. [[#get-relative-level][~org-export-get-relative-level~]].
267 List of elements and objects that will be unconditionally ignored
271 - type :: list of elements
275 Alist between ID strings and destination file's path, relative to
279 - type :: alist (STRING . STRING)
283 Original buffer name.
290 Full path to input file, if any.
293 - type :: string or nil
297 List of keywords attached to data.
304 Default language used for translations.
311 Full path to output file, if any.
314 - type :: string or nil
318 Whole parse tree, available at any time during transcoding.
321 - type :: list (as returned by ~org-element-parse-buffer~)
323 ** ~:preserve-breaks~
325 Non-nil means transcoding should preserve all line breaks.
328 - type :: symbol (nil, t)
330 ** ~:section-numbers~
332 Non-nil means transcoding should add section numbers to headlines.
335 - type :: symbol (nil, t)
339 :CUSTOM_ID: select-tags
342 List of tags enforcing inclusion of sub-trees in transcoding. When
343 such a tag is present, sub-trees without it are /de facto/ excluded
344 from the process. See [[#use-select-tags][~:use-select-tags~]].
347 - type :: list of strings
349 ** ~:time-stamp-file~
351 Non-nil means transcoding should insert a time stamp in the output.
354 - type :: symbol (nil, t)
356 ** ~:translate-alist~
358 Alist between element and object types and transcoding functions
359 relative to the current back-end. Special keys ~template~ and
360 ~plain-text~ are also possible.
363 - type :: alist (SYMBOL . FUNCTION)
365 ** ~:use-select-tags~
367 :CUSTOM_ID: use-select-tags
370 When non-nil, a select tags has been found in the parse tree.
371 Thus, any headline without one will be filtered out. See
372 [[#select-tags][~:select-tags~]].
375 - type :: integer or nil
377 ** ~:with-archived-trees~
379 Non-nil when archived sub-trees should also be transcoded. If it
380 is set to the ~headline~ symbol, only the archived headline's name
384 - type :: symbol (nil, t, ~headline~)
388 Non-nil means author's name should be included in the output.
391 - type :: symbol (nil, t)
395 Non-nil means clock keywords should be exported.
398 - type :: symbol (nil, t)
402 Non-nil means a creation sentence should be inserted at the end of
403 the transcoded string. If the value is ~comment~, it should be
407 - type :: symbol (~comment~, nil, t)
411 Non nil means output should contain a date.
414 - type :: symbol (nil, t)
418 Non-nil means drawers should be exported. If its value is a list
419 of names, only drawers with such names will be transcoded.
422 - type :: symbol (nil, t) or list of strings
426 Non-nil means output should contain author's email.
429 - type :: symbol (nil, t)
433 Non-nil means emphasized text should be interpreted.
436 - type :: symbol (nil, t)
438 ** ~:with-fixed-width~
440 Non-nil if transcoder should interpret strings starting with
441 a colon as a fixed-with — verbatim — area.
444 - type :: symbol (nil, t)
448 Non-nil if transcoder should interpret footnotes.
451 - type :: symbol (nil, t)
455 Non-nil means ~latex-environment~ elements and ~latex-fragment~
456 objects should appear in export output. When this property is set
457 to ~verbatim~, they will be left as-is.
460 - type :: symbol (~verbatim~, nil, t)
464 Non-nil means transcoding should include planning info.
467 - type :: symbol (nil, t)
471 Non-nil means transcoding should include priority cookies.
474 - type :: symbol (nil, t)
476 ** ~:with-smart-quotes~
478 Non-nil means activate smart quotes during export.
481 - type :: symbol (nil ,t)
483 ** ~:with-special-strings~
485 Non-nil means transcoding should interpret special strings in plain
489 - type :: symbol (nil, t)
491 ** ~:with-sub-superscript~
493 Non-nil means transcoding should interpret subscript and
494 superscript. With a value of ~{}~, only interpret those using
498 - type :: symbol (nil, ~{}~, t)
502 Non-nil means transcoding should interpret tables.
505 - type :: symbol (nil, t)
509 Non-nil means transcoding should keep tags in headlines.
510 A ~not-in-toc~ value will remove them from the table of contents,
514 - type :: symbol (nil, t, ~not-in-toc~)
518 Non-nil means transcoding should include headlines with a TODO
519 keyword. A ~todo~ value will only include headlines with a TODO
520 type keyword while a ~done~ value will do the contrary. If a list
521 of strings is provided, only tasks with keywords belonging to that
525 - type :: symbol (t, ~todo~, ~done~, nil) or list of strings
527 ** ~:with-timestamps~
529 Non-nil means transcoding should include time stamps. Special
530 value ~active~ (resp. ~inactive~) ask to export only active
531 (resp. inactive) timestamps. Otherwise, completely remove them.
534 - type :: symbol: (~active~, ~inactive~, t, nil)
538 Non-nil means that a table of contents has to be added to the
539 output. An integer value limits its depth.
542 - type :: symbol (nil, t or integer)
544 ** ~:with-todo-keywords~
546 Non-nil means transcoding should include TODO keywords.
549 - type :: symbol (nil, t)
553 :CUSTOM_ID: filter-system
556 Filters sets are lists of functions. They allow to alter parse tree
557 before export and to post-process output of each transcoded object
560 Each function in a set must accept three arguments: a string (or
561 a parse tree as a special case), a symbol representing the current
562 back-end, and the communication channel, as a plist.
564 As an exception, functions in options filter only accept two
565 arguments: the property list containing the export options and the
566 back-end, as a symbol.
568 From the developer side, filters sets can be installed using
569 ~:filters-alist~ keyword while defining the back-end with
570 ~org-export-define-derived-backend~. Each association has a key
571 among the following symbols and a function or a list of functions as
574 - ~:filter-babel-call~
576 - ~:filter-center-block~
580 - ~:filter-dynamic-block~
582 - ~:filter-example-block~
583 - ~:filter-export-block~
584 - ~:filter-export-snippet~
585 - ~:filter-final-output~
586 - ~:filter-fixed-width~
587 - ~:filter-footnote-definition~
588 - ~:filter-footnote-reference~
590 - ~:filter-horizontal-rule~
591 - ~:filter-inline-babel-call~
592 - ~:filter-inline-src-block~
593 - ~:filter-inlinetask~
597 - ~:filter-latex-environment~
598 - ~:filter-latex-fragment~
599 - ~:filter-line-break~
601 - ~:filter-node-property~
603 - ~:filter-paragraph~
604 - ~:filter-parse-tree~
605 - ~:filter-plain-list~
606 - ~:filter-plain-text~
608 - ~:filter-property-drawer~
609 - ~:filter-quote-block~
610 - ~:filter-quote-section~
611 - ~:filter-radio-target~
613 - ~:filter-special-block~
614 - ~:filter-src-block~
615 - ~:filter-strike-through~
616 - ~:filter-statistics-cookie~
617 - ~:filter-subscript~
618 - ~:filter-superscript~
620 - ~:filter-table-cell~
621 - ~:filter-table-row~
623 - ~:filter-timestamp~
624 - ~:filter-underline~
626 - ~:filter-verse-block~
629 For example, ~ascii~ back-end implements a filter that makes sure
630 headlines end with two blank lines:
632 #+BEGIN_SRC emacs-lisp
633 (org-export-define-backend 'ascii
635 :filters-alist '((:filter-headline . org-ascii-filter-headline-blank-lines)
636 (:filter-section . org-ascii-filter-headline-blank-lines)))
638 (defun org-ascii-filter-section-blank-lines (headline back-end info)
639 "Filter controlling number of blank lines after a section."
640 (let ((blanks (make-string 2 ?\n)))
641 (replace-regexp-in-string "\n\\(?:\n[ \t]*\\)*\\'" blanks headline)))
649 A whole set of tools is available to help build new exporters. Any
650 function general enough to have its use across a couple of back-ends
653 Many of them are high-level access to properties from the
654 communication channel. As such, they should be preferred to
655 straight access to communication channel, when possible.
657 ** ~org-export-activate-smart-quotes~
659 :CUSTOM_ID: activate-smart-quotes
662 Transform quotes and apostrophes into their "smart" counterpart in
665 It should be used after a check against ~:with-smart-quotes~ value
666 in communication channel.
668 Since this function needs the original string, it may be useful to
669 apply others transformations (i.e. characters protection) on a copy
670 of that string and provide the pristine original string as the
673 For example, in ~html~ back-end, it is necessary to protect "<",
674 ">" and "&" characters before calling this function. Here's an
675 excerpt of its ~plain-text~ transcoder:
677 #+BEGIN_SRC emacs-lisp
679 ;; Protect following characters: <, >, &.
680 (setq output (org-html-encode-plain-text output))
681 ;; Handle smart quotes. Be sure to provide original string since
682 ;; OUTPUT may have been modified.
683 (when (plist-get info :with-smart-quotes)
684 (setq output (org-export-activate-smart-quotes output :html info text)))
690 ** ~org-export-collect-figures~
692 :CUSTOM_ID: collect-figures
695 Return a list of all exportable figures in parse tree.
697 Used to build a table of figures.
699 See also: [[#collect-headlines][~org-export-collect-headlines~]],
700 [[#collect-tables][~org-export-collect-tables~]], [[#collect-listings][~org-export-collect-listings~]].
702 ** ~org-export-collect-footnote-definitions~
704 :CUSTOM_ID: collect-footnote-definitions
707 List actually used footnotes definitions in order to add footnote
708 listings throughout the transcoded data.
710 Feed it with the whole parse tree to get the full footnote listing.
711 Feed it with the current headline to get partial footnote listing
712 relative to that headline.
714 Number, label, if any, and definition are provided.
716 See also: [[#footnote-first-reference-p][~org-export-footnote-first-reference-p~]],
717 [[#get-footnote-definition][~org-export-get-footnote-definition~]],
718 [[#get-footnote-number][~org-export-get-footnote-number~]].
720 ** ~org-export-collect-headlines~
722 :CUSTOM_ID: collect-headlines
725 Return a list of all exportable headlines, possibly limited to
728 Used to build a table of contents, e.g., when a "#+TOC: headlines
729 2" keyword value pair is specified.
731 See also: [[#collect-tables][~org-export-collect-tables~]],
732 [[#collect-figures][~org-export-collect-figures~]], [[#collect-listings][~org-export-collect-listings~]],
733 [[#excluded-from-toc-p][~org-export-excluded-from-toc-p~]].
735 ** ~org-export-collect-listings~
737 :CUSTOM_ID: collect-listings
740 Return a list of all exportable source blocks with a caption or
741 a name in parse tree.
743 Used to build a table of listings, e.g., when a "#+TOC: listings"
744 keyword value pair is specified.
746 See also: [[#collect-headlines][~org-export-collect-headlines~]],
747 [[#collect-tables][~org-export-collect-tables~]], [[#collect-figures][~org-export-collect-figures~]].
749 ** ~org-export-collect-tables~
751 :CUSTOM_ID: collect-tables
754 Return a list of all exportable tables with a caption or a name in
757 Used to build a table of tables, e.g., when a "#+TOC: tables"
758 keyword value pair is specified.
760 See also: [[#collect-headlines][~org-export-collect-headlines~]],
761 [[#collect-figures][~org-export-collect-figures~]], [[#collect-listings][~org-export-collect-listings~]].
768 Transcode a given element, object, secondary string or string using
771 It is used primarily to transcode secondary strings, like ~:title~.
772 For example ~beamer~ back-end uses the following:
774 #+BEGIN_SRC emacs-lisp
775 (defun org-beamer-template (contents info)
776 (let ((title (org-export-data (plist-get info :title) info)))
780 ** ~org-export-data-with-backend~
782 :CUSTOM_ID: data-with-backend
785 Recursively convert some data (an element, an object, a secondary
786 string or a string) using another backend.
788 See also: [[#with-backend][~org-export-with-backend~]],
789 [[#toc-entry-backend][~org-export-toc-entry-backend~]].
791 ** ~org-export-excluded-from-toc-p~
793 :CUSTOM_ID: excluded-from-toc-p
796 Non-nil if a headline must not appear in a table of contents.
798 See also : [[#collect-headlines][~org-export-collect-headlines~]].
800 ** ~org-export-file-uri~
805 Return URI associated to a given filename.
807 ** ~org-export-first-sibling-p~
809 :CUSTOM_ID: first-sibling-p
812 Non-nil if an element or object is the first of its siblings.
814 It may be used to know when to start a list if headline's relative
815 level is below the one specified in [[#headline-levels][~:headline-levels~]] property.
817 See also: [[#get-relative-level][~org-export-get-relative-level~]],
818 [[#number-to-roman][~org-export-number-to-roman~]], [[#last-sibling-p][~org-export-last-sibling-p~]].
820 ** ~org-export-footnote-first-reference-p~
822 :CUSTOM_ID: footnote-first-reference-p
825 Non-nil when a footnote reference if the first reference relative
828 Used when a back-end needs to attach the footnote definition only
829 to the first occurrence of the corresponding label.
831 Its scope can be arbitrary narrowed, e.g., to a headline.
833 See also: [[#collect-footnote-definitions][~org-export-collect-footnote-definitions~]],
834 [[#get-footnote-definition][~org-export-get-footnote-definition~]],
835 [[#get-footnote-number][~org-export-get-footnote-number~]].
837 ** ~org-export-format-code~
839 :CUSTOM_ID: format-code
842 Helper function to format source code. It applies a given function
843 on each line of the code, passing current line number and
844 associated code reference label, if any, as arguments.
846 See also: [[#format-code-default][~org-export-format-code-default~]], [[#get-loc][~org-export-get-loc~]],
847 [[#unravel-code][~org-export-unravel-code~]].
849 ** ~org-export-format-code-default~
851 :CUSTOM_ID: format-code-default
854 Return contents of a =src-block= or =example-block= element in
855 a format suited for raw text or verbatim output. More
856 specifically, it takes care of line numbering and labels
857 integration depending of element's switches, but no formatting is
858 otherwise applied to source code.
860 See also: [[#format-code][~org-export-format-code~]], [[#unravel-code][~org-export-unravel-code~]].
862 ** ~org-export-get-alt-title~
864 :CUSTOM_ID: get-alt-title
867 Return the alternative title for a given headline as a secondary
868 string. If no such title is found, it will return its main title.
870 This function is useful when building a table of contents.
872 ** ~org-export-get-caption~
874 :CUSTOM_ID: get-caption
877 Return the caption of a given element, as a secondary string. With
878 an optional argument, return the short caption instead.
880 As an example, ~ascii~ back-end, when creating a list of listings,
883 #+BEGIN_SRC emacs-lisp
884 (defun org-ascii--list-listings (keyword info)
885 (let ((title (org-ascii--translate "List of Listings" info)))
891 ;; Use short name in priority, if available.
892 (let ((caption (or (org-export-get-caption src-block t)
893 (org-export-get-caption src-block))))
894 (org-export-data caption info)
896 (org-export-collect-listings info) "\n"))))
899 See also: [[#read-attribute][~org-export-read-attribute~]].
901 ** ~org-export-get-category~
903 :CUSTOM_ID: get-category
906 Return category associated to a given element or object. Unlike to
907 the ~:category~ property from headlines and inlinetasks, this
908 function handles inheritance and ~CATEGORY~ keywords. Therefore,
909 it should be the preferred way to retrieve a category during
912 See also: [[#get-node-property][~org-export-get-node-property~]].
914 ** ~org-export-get-coderef-format~
916 :CUSTOM_ID: get-coderef-format
919 Return an appropriate format string for code reference links.
921 See also: [[#resolve-coderef][~org-export-resolve-coderef~]].
923 ** ~org-export-get-date~
928 Returns a date, as a string or a secondary string. It handles
929 ~org-export-date-timestamp-format~.
931 Note that ~:with-date~ property in [[#communication][communication channel]] should be
932 checked prior to use this, as shown in the following example
933 extracted from ~ox-latex.el~:
935 #+BEGIN_SRC emacs-lisp :exports code
936 (let ((date (and (plist-get info :with-date) (org-export-get-date info))))
937 (format "\\date{%s}\n" (org-export-data date info)))
940 ** ~org-export-get-footnote-definition~
942 :CUSTOM_ID: get-footnote-definition
945 Retrieve the footnote definition relative to a given footnote
948 If the footnote definition in inline, it is returned as a secondary
949 string. Otherwise, it is full Org data.
951 See also: [[#collect-footnote-definitions][~org-export-collect-footnote-definitions~]],
952 [[#footnote-first-reference-p][~org-export-footnote-first-reference-p~]],
953 [[#get-footnote-number][~org-export-get-footnote-number~]].
955 ** ~org-export-get-footnote-number~
957 :CUSTOM_ID: get-footnote-number
960 Return the ordinal attached to a footnote reference or definition.
962 Its scope can be arbitrary narrowed, e.g., to get the numbering
963 relative to a headline.
965 See also: [[#collect-footnote-definitions][~org-export-collect-footnote-definitions~]],
966 [[#footnote-first-reference-p][~org-export-footnote-first-reference-p~]],
967 [[#get-footnote-definition][~org-export-get-footnote-definition~]].
969 ** ~org-export-get-headline-number~
971 :CUSTOM_ID: get-headline-number
974 Return the section number of an headline, as a list of integers.
976 See also: [[#headline-numbered-p][~org-export-headline-numbered-p~]],
977 [[#number-to-roman][~org-export-number-to-roman~]].
979 ** ~org-export-get-loc~
984 Return count of accumulated lines of code from previous
985 line-numbered =example-block= and =src-block= elements, according
986 to current element's switches.
988 In other words, the first line of code in the current block is
989 supposed to be numbered as the returned value plus one, assuming
990 its ~:number-lines~ properties is non-nil.
992 See also: [[#format-code][~org-export-format-code~]], [[#unravel-code][~org-export-unravel-code~]].
994 ** ~org-export-get-next-element~
996 :CUSTOM_ID: get-next-element
999 Return element (resp. object or string) after an element
1000 (resp. object), or nil.
1002 See also: [[#get-parent][~org-export-get-parent~]],
1003 [[#get-parent-headline][~org-export-get-parent-headline~]],
1004 [[#get-parent-paragraph][~org-export-get-parent-paragraph~]],
1005 [[#get-previous-element][~org-export-get-previous-element~]].
1007 ** ~org-export-get-node-property~
1009 :CUSTOM_ID: get-node-property
1012 Return the node property associated to an element or object. If
1013 the element is an headline, this is equivalent to reading the
1014 property with ~org-element-property~.
1016 Though, this function can optionally handle inheritance.
1018 See also: [[#get-category][~org-export-get-category~]].
1020 ** ~org-export-get-ordinal~
1022 :CUSTOM_ID: get-ordinal
1025 Associate a sequence number to any object or element. It is meant
1026 to be used to build captions.
1028 Also, it could be applied on a fuzzy link's destination, since such
1029 links are expected to be replaced with the sequence number of their
1030 destination, provided they have no description.
1032 Taken from ~ascii~ back-end, the following example shows how fuzzy
1033 links could be handled :
1035 #+BEGIN_SRC emacs-lisp :exports code
1036 (let ((type (org-element-property :type link)))
1039 ;; Do not apply a special syntax on fuzzy links pointing to targets.
1040 ((string= type "fuzzy")
1041 (let ((destination (org-export-resolve-fuzzy-link link info)))
1042 ;; If link has a description, use it.
1043 (if (org-string-nw-p desc) desc
1045 (let ((number (org-export-get-ordinal destination info)))
1047 (if (atom number) (number-to-string number)
1048 (mapconcat 'number-to-string number "."))))))))
1052 See also : [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]]
1054 ** ~org-export-get-parent~
1056 :CUSTOM_ID: get-parent
1059 Return closest element containing current element or object, if
1060 any. Return nil otherwise.
1062 See also: [[#get-next-element][~org-export-get-next-element~]],
1063 [[#get-parent-paragraph][~org-export-get-parent-paragraph~]],
1064 [[#get-parent-headline][~org-export-get-parent-headline~]],
1065 [[#get-previous-element][~org-export-get-previous-element~]].
1067 ** ~org-export-get-parent-element~
1069 :CUSTOM_ID: get-parent-paragraph
1072 Return the first element containing provided object, if any.
1073 Return nil otherwise.
1075 See also: [[#get-parent][~org-export-get-parent~]],
1076 [[#get-parent-headline][~org-export-get-parent-headline~]],
1077 [[#get-previous-element][~org-export-get-previous-element~]], [[#get-next-element][~org-export-get-next-element~]].
1079 ** ~org-export-get-parent-headline~
1081 :CUSTOM_ID: get-parent-headline
1084 Return the headline containing provided element or object, if any.
1085 Return nil otherwise.
1087 See also: [[#get-next-element][~org-export-get-next-element~]], [[#get-parent][~org-export-get-parent~]],
1088 [[#get-parent-paragraph][~org-export-get-parent-paragraph~]],
1089 [[#get-previous-element][~org-export-get-previous-element~]].
1091 ** ~org-export-get-previous-element~
1093 :CUSTOM_ID: get-previous-element
1096 Return element (resp. object or string) before an element
1097 (resp. object), or nil.
1099 See also: [[#get-next-element][~org-export-get-next-element~]], [[#get-parent][~org-export-get-parent~]],
1100 [[#get-parent-headline][~org-export-get-parent-headline~]],
1101 [[#get-parent-paragraph][~org-export-get-parent-paragraph~]].
1103 ** ~org-export-get-reference~
1105 :CUSTOM_ID: get-reference
1108 Return unique reference associated to an element or an object, as
1111 Since it consists of alphanumerical characters only, it can be used
1112 as internal references for back-ends needing them.
1114 For example, =ox-latex.el= uses it to translate radio targets into
1115 ~\label{}~ and links to radio targets into ~\hyperref{}~:
1117 #+BEGIN_SRC emacs-lisp
1118 (defun org-latex-radio-target (radio-target text info)
1119 (format "\\label{%s}%s" (org-export-get-reference radio-target info) text))
1121 (defun org-latex-link (link desc info)
1122 (let ((type (org-element-property :type link)))
1125 ((string= type "radio")
1126 (let ((destination (org-export-resolve-radio-link link info)))
1127 (if (not destination) desc
1128 (format "\\hyperref[%s]{%s}"
1129 (org-export-get-reference destination info)
1134 See also: [[#inline-image-p][~org-export-inline-image-p~]],
1135 [[#resolve-id-link][~org-export-resolve-id-link~]], [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]],
1136 [[#resolve-radio-link][~org-export-resolve-radio-link~]].
1138 ** ~org-export-get-relative-level~
1140 :CUSTOM_ID: get-relative-level
1143 Return headline level, relatively to the lower headline level in
1144 the parsed tree. It is meant to be used over ~:level~ headline's
1147 See also:[[#first-sibling-p][~org-export-first-sibling-p~]],
1148 [[#get-headline-number][~org-export-get-headline-number~]],[[#headline-numbered-p][~org-export-headline-numbered-p~]],
1149 [[#last-sibling-p][~org-export-last-sibling-p~]].
1151 ** ~org-export-get-table-cell-at~
1153 :CUSTOM_ID: get-table-cell-at
1156 Return exportable cell object at a given position, or nil. Hence,
1157 position ~(0 . 0)~ will always point to the first exportable cell
1160 See also: [[#table-cell-address][~org-export-table-cell-address~]],
1161 [[#table-dimensions][~org-export-table-dimensions~]].
1163 ** ~org-export-get-tags~
1165 :CUSTOM_ID: get-tags
1168 Return list of exportable tags attached to a given headline or
1169 inlinetask element. With an optional argument, tags are inherited
1170 from parent headlines and ~FILETAGS~ keywords.
1172 In particular, it removes select tags and exclude tags. The
1173 function also accepts an arbitrary list of tags for further
1176 For example, ~latex~ back-end uses the following snippet in the
1177 inlinetask transcode function.
1179 #+BEGIN_SRC emacs-lisp
1180 (let ((title (org-export-data (org-element-property :title inlinetask) info))
1181 (todo (and (plist-get info :with-todo-keywords)
1182 (let ((todo (org-element-property :todo-keyword inlinetask)))
1183 (and todo (org-export-data todo info)))))
1184 (todo-type (org-element-property :todo-type inlinetask))
1185 (tags (and (plist-get info :with-tags)
1186 (org-export-get-tags inlinetask info)))
1187 (priority (and (plist-get info :with-priority)
1188 (org-element-property :priority inlinetask))))
1192 ** ~org-export-headline-numbered-p~
1194 :CUSTOM_ID: headline-numbered-p
1197 Non nil when a given headline should be numbered.
1199 See also: [[#get-headline-number][~org-export-get-headline-number~]],
1200 [[#get-relative-level][~org-export-get-relative-level~]].
1202 ** ~org-export-inline-image-p~
1204 :CUSTOM_ID: inline-image-p
1207 Non-nil when the link provided should be considered as an inline
1208 image. Note that it always return nil when the link has
1211 It accepts an optional set of rules in order to tweak the
1212 definition of an inline image, which is, by default, any link
1213 targeting a local file whose extension is either "png", "jpeg",
1214 "jpg", "gif", "tiff", "tif", "xbm", "xpm", "pbm", "pgm" or "ppm".
1216 A set of rules consists in an alist whose key is a type of link, as
1217 a string, and whose value is a regexp matching link's path. As an
1218 example, ~html~ back-end uses the following rules:
1220 #+BEGIN_SRC emacs-lisp
1221 '(("file" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'")
1222 ("http" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'")
1223 ("https" . "\\.\\(jpeg\\|jpg\\|png\\|gif\\|svg\\)\\'"))
1226 See also: [[#get-reference][~org-export-get-reference~]],
1227 [[#get-coderef-format][~org-export-get-coderef-format~]], [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]].
1229 ** ~org-export-last-sibling-p~
1231 :CUSTOM_ID: last-sibling-p
1234 Non-nil if an element or object is the last of its siblings.
1236 It may be used to know when to close a list if headline's relative
1237 level is below the one specified in [[#headline-levels][~:headline-levels~]] property.
1239 See also: [[#get-relative-level][~org-export-get-relative-level~]],
1240 [[#number-to-roman][~org-export-number-to-roman~]], [[#first-sibling-p][~org-export-first-sibling-p~]].
1242 ** ~org-export-number-to-roman~
1244 :CUSTOM_ID: number-to-roman
1247 Convert numbers to roman numbers. It can be used to provide roman
1248 numbering for headlines and numbered lists.
1250 See also: [[#get-headline-number][~org-export-get-headline-number~]].
1252 ** ~org-export-read-attribute~
1254 :CUSTOM_ID: read-attribute
1257 Read a property from a given element as a plist. It can be used to
1258 normalize affiliated keywords' syntax. For example, the following
1259 affiliated keywords:
1262 ,#+ATTR_HTML: :width 10 :height 5
1263 ,#+ATTR_HTML: :file filename.ext
1266 would be returned as:
1268 #+BEGIN_SRC emacs-lisp
1269 '(:width "10" :height "5" :file "filename.ext")
1272 See also: [[#get-caption][~org-export-get-caption~]].
1274 ** ~org-export-resolve-coderef~
1276 :CUSTOM_ID: resolve-coderef
1279 Search for a code reference within ~src-block~ and ~example-block~
1280 elements. Return corresponding --possibly accumulated-- line
1281 number, or reference itself, depending on container's switches.
1283 See also : [[#get-coderef-format][~org-export-get-coderef-format~]],
1284 [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]], [[#resolve-id-link][~org-export-resolve-id-link~]],
1285 [[#resolve-radio-link][~org-export-resolve-radio-link~]].
1287 ** ~org-export-resolve-fuzzy-link~
1289 :CUSTOM_ID: resolve-fuzzy-link
1292 Search destination of a fuzzy link — i.e. it has a ~fuzzy~ ~:type~
1293 attribute – within the parsed tree, and return that element or
1296 See also: [[#get-ordinal][~org-export-get-ordinal~]], [[#resolve-coderef][~org-export-resolve-coderef~]],
1297 [[#resolve-id-link][~org-export-resolve-id-link~]], [[#resolve-radio-link][~org-export-resolve-radio-link~]],
1298 [[#get-reference][~org-export-get-reference~]].
1300 ** ~org-export-resolve-id-link~
1302 :CUSTOM_ID: resolve-id-link
1305 Search headline targeted by an id link --- i.e. it has a ~id~ or
1306 ~custom-id~ ~:type~ attribute --- within the parse tree. Return
1307 the matching headline in the tree, the name of the external file,
1310 See also : [[#resolve-coderef][~org-export-resolve-coderef~]],
1311 [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]], [[#resolve-radio-link][~org-export-resolve-radio-link~]],
1312 [[#get-reference][~org-export-get-reference~]].
1314 ** ~org-export-resolve-radio-link~
1316 :CUSTOM_ID: resolve-radio-link
1319 Return first radio target object matching a radio link --- that is
1320 with a ~radio~ ~:type~ attribute --- in the parse tree, or nil.
1322 Typically, target's contents are exported through ~org-export-data~
1323 and used as link description, as in the following excerpt from
1326 #+BEGIN_SRC emacs-lisp
1327 (defun org-latex-link (link desc info)
1328 (let* ((type (org-element-property :type link))
1332 ((string= type "radio")
1333 (let ((destination (org-export-resolve-radio-link link info)))
1335 (format "\\hyperref[%s]{%s}"
1336 (org-export-get-reference destination info)
1337 (org-export-data (org-element-contents destination) info)))))
1341 See also : [[#resolve-coderef][~org-export-resolve-coderef~]],
1342 [[#resolve-fuzzy-link][~org-export-resolve-fuzzy-link~]], [[#resolve-id-link][~org-export-resolve-id-link~]],
1343 [[#get-reference][~org-export-get-reference~]].
1345 ** ~org-export-table-cell-address~
1347 :CUSTOM_ID: table-cell-address
1350 Return row and column of a given cell object. Positions are
1351 0-indexed and only exportable rows and columns are considered. The
1352 function returns nil if called on a non-exportable cell.
1354 See also: [[#get-table-cell-at][~org-export-get-table-cell-at~]],
1355 [[#table-dimensions][~org-export-table-dimensions~]].
1357 ** ~org-export-table-cell-alignment~
1359 :CUSTOM_ID: table-cell-alignment
1362 Return expected alignment for the contents of a given cell object.
1363 It can be either ~left~, ~right~ or ~center~.
1365 See also: [[#table-cell-borders][~org-export-table-cell-borders~]],
1366 [[#table-cell-width][~org-export-table-cell-width~]].
1368 ** ~org-export-table-cell-borders~
1370 :CUSTOM_ID: table-cell-borders
1373 Indicate expected borders for a given cell object. When non-nil,
1374 return value is a list of symbols among ~top~, ~bottom~, ~above~,
1375 ~below~, ~left~ and ~right~.
1377 Special values ~top~ and ~bottom~ only happen for cells in,
1378 respectively, the first and the last exportable rows.
1380 See also: [[#table-cell-alignment][~org-export-table-cell-alignment~]],
1381 [[#table-cell-width][~org-export-table-cell-width~]].
1383 ** ~org-export-table-cell-ends-colgroup-p~
1385 :CUSTOM_ID: table-cell-ends-colgroup-p
1388 Non-nil when a table cell object ends a column group.
1390 See also: [[#table-cell-starts-colgroup-p][~org-export-table-cell-starts-colgroup-p~]].
1392 ** ~org-export-table-cell-starts-colgroup-p~
1394 :CUSTOM_ID: table-cell-starts-colgroup-p
1397 Non-nil when a table cell object starts a column group.
1399 See also: [[#table-cell-ends-colgroup-p][~org-export-table-cell-ends-colgroup-p~]].
1401 ** ~org-export-table-cell-width~
1403 :CUSTOM_ID: table-cell-width
1406 Return expected width for contents of a given cell object.
1408 Only width specified explicitly through meta-data is considered.
1409 If no such information can be found, return nil instead.
1411 Some back-end may still need to know the actual width of exported
1412 cell's contents in order to compute column's width. In that case,
1413 every cell in the column must be transcoded in order to find the
1414 widest one. The snippet below, extracted from =ox-ascii.el=
1415 illustrates a possible implementation.
1417 #+BEGIN_SRC emacs-lisp
1418 (or (org-export-table-cell-width table-cell info)
1419 (let* ((max-width 0)
1420 (table (org-export-get-parent-table table-cell info))
1421 (specialp (org-export-table-has-special-column-p table))
1422 (col (cdr (org-export-table-cell-address table-cell info))))
1426 ;; For each exportable row, get the cell at column COL and
1427 ;; transcode its contents. Then compare its length with
1428 ;; MAX-WIDTH and keep the greater of two.
1432 (org-element-contents
1433 (elt (if specialp (car (org-element-contents row))
1434 (org-element-contents row))
1442 See also: [[#table-cell-alignment][~org-export-table-cell-alignment~]],
1443 [[#table-cell-borders][~org-export-table-cell-borders~]].
1445 ** ~org-export-table-dimensions~
1447 :CUSTOM_ID: table-dimensions
1450 Return the number of exportable rows and columns in a given table.
1452 See also: [[#get-table-cell-at][~org-export-get-table-cell-at~]],
1453 [[#table-cell-address][~org-export-table-cell-address~]].
1455 ** ~org-export-table-has-header-p~
1457 :CUSTOM_ID: table-has-header-p
1460 Non-nil when table has at least two row groups.
1462 See also: [[#table-has-special-column-p][~org-export-table-has-special-column-p~]],
1463 [[#table-row-is-special-p][~org-export-table-row-is-special-p~]].
1465 ** ~org-export-table-has-special-column-p~
1467 :CUSTOM_ID: table-has-special-column-p
1470 Non-nil when first column in the table only contains meta-data.
1472 See also: [[#table-has-header-p][~org-export-table-has-header-p~]],
1473 [[#table-row-is-special-p][~org-export-table-row-is-special-p~]].
1475 ** ~org-export-table-row-ends-header-p~
1477 :CUSTOM_ID: table-row-ends-header-p
1480 Non-nil when a table row element ends table's header.
1482 See also: [[#table-row-ends-rowgroup-p][~org-export-table-row-ends-rowgroup-p~]],
1483 [[#table-row-group][~org-export-table-row-group~]],
1484 [[#table-row-starts-header-p][~org-export-table-row-starts-header-p~]],
1485 [[#table-row-starts-rowgroup-p][~org-export-table-row-starts-rowgroup-p~]],
1486 [[#table-row-in-header-p][~org-export-table-row-in-header-p~]].
1488 ** ~org-export-table-row-ends-rowgroup-p~
1490 :CUSTOM_ID: table-row-ends-rowgroup-p
1493 Non-nil when a a table row element ends a rowgroup, header
1496 See also: [[#table-row-ends-header-p][~org-export-table-row-ends-header-p~]],
1497 [[#table-row-group][~org-export-table-row-group~]],
1498 [[#table-row-starts-header-p][~org-export-table-row-starts-header-p~]],
1499 [[#table-row-starts-rowgroup-p][~org-export-table-row-starts-rowgroup-p~]].
1501 ** ~org-export-table-row-group~
1503 :CUSTOM_ID: table-row-group
1506 Return row group number for a given table row element.
1508 See also: [[#table-row-ends-header-p][~org-export-table-row-ends-header-p~]],
1509 [[#table-row-ends-rowgroup-p][~org-export-table-row-ends-rowgroup-p~]],
1510 [[#table-row-starts-header-p][~org-export-table-row-starts-header-p~]],
1511 [[#table-row-starts-rowgroup-p][~org-export-table-row-starts-rowgroup-p~]].
1513 ** ~org-export-table-row-in-header-p~
1515 :CUSTOM_ID: table-row-in-header-p
1518 Non-nil if a given table row element belongs to table's header.
1519 Always nil if the table contains no header or the row is
1522 See also: [[#table-has-header-p][~org-export-table-has-header-p~]],
1523 [[#table-row-starts-header-p][~org-export-table-row-starts-header-p~]],
1524 [[#table-row-ends-header-p][~org-export-table-row-ends-header-p~]].
1527 ** ~org-export-table-row-is-special-p~
1529 :CUSTOM_ID: table-row-is-special-p
1532 Non-nil if a given table row element only contains meta-data.
1534 See also: [[#table-has-header-p][~org-export-table-has-header-p~]],
1535 [[#table-has-special-column-p][~org-export-table-has-special-column-p~]].
1537 ** ~org-export-table-row-starts-header-p~
1539 :CUSTOM_ID: table-row-starts-header-p
1542 Non-nil when a table row element starts table's header.
1544 See also: [[#table-row-ends-header-p][~org-export-table-row-ends-header-p~]],
1545 [[#table-row-ends-rowgroup-p][~org-export-table-row-ends-rowgroup-p~]],
1546 [[#table-row-group][~org-export-table-row-group~]],
1547 [[#table-row-starts-rowgroup-p][~org-export-table-row-starts-rowgroup-p~]],
1548 [[#table-row-in-header-p][~org-export-table-row-in-header-p~]].
1550 ** ~org-export-table-row-starts-rowgroup-p~
1552 :CUSTOM_ID: table-row-starts-rowgroup-p
1555 Non-nil when a table row element starts a rowgroup, header
1558 See also: [[#table-row-ends-header-p][~org-export-table-row-ends-header-p~]],
1559 [[#table-row-ends-rowgroup-p][~org-export-table-row-ends-rowgroup-p~]],
1560 [[#table-row-group][~org-export-table-row-group~]],
1561 [[#table-row-starts-header-p][~org-export-table-row-starts-header-p~]].
1563 ** ~org-export-toc-entry-backend~
1565 :CUSTOM_ID: toc-entry-backend
1568 Generate an anonymous export back-end appropriate for entries in table
1571 See also: [[#data-with-backend][~org-export-data-with-backend~]].
1573 ** ~org-export-translate~
1575 Translate a string, i.e. "Table of Contents", according to language
1578 Refer to ~org-export-dictionary~ variable for the list of all
1581 ** ~org-export-unravel-code~
1583 :CUSTOM_ID: unravel-code
1586 Clean source code from an =example-block= or a =src-block= element
1587 and extract code references out of it.
1589 Its purpose is to allow to transform raw source code first and then
1590 integrate line numbers or references back into the final output.
1591 That final task can be achieved with the help of
1592 ~org-export-format-code~ function.
1594 See also: [[#format-code][~org-export-format-code~]],
1595 [[#format-code-default][~org-export-format-code-default~]], [[#get-loc][~org-export-get-loc~]].
1597 ** ~org-export-with-backend~
1599 :CUSTOM_ID: with-backend
1602 Export an element or object using locally another back-end.
1604 In a derived back-end, it may be used as a fall-back function once
1605 all specific cases have been handled. Thus, ~beamer~ back-end,
1606 derived from ~latex~, takes care of every internal link type and
1607 delegates everything else to its parent back-end:
1609 #+BEGIN_SRC emacs-lisp
1610 (let ((type (org-element-property :type link))
1611 (path (org-element-property :path link)))
1613 ;; Handle every internal link type, but be careful to ignore "id"
1614 ;; type links pointing to external files.
1615 ((equal type "radio") ...)
1616 ((and (member type '("custom-id" "fuzzy" "id"))
1617 (let ((destination (if (string= type "fuzzy")
1618 (org-export-resolve-fuzzy-link link info)
1619 (org-export-resolve-id-link link info))))
1620 (pcase (org-element-type destination)
1623 ;; Otherwise, use `latex' back-end.
1624 (t (org-export-with-backend 'latex link contents info))))
1627 See also: [[#data-with-backend][~org-export-data-with-backend~]].
1629 ** ~org-timestamp-translate~
1631 :CUSTOM_ID: timestamp-translate
1634 Translate a timestamp object according to
1635 ~org-time-stamp-custom-formats~, which see.
1637 It should be used whenever exported timestamps are expected to
1638 comply to user-defined display. As an example, in the following
1639 excerpt from, =ox-html.el=, the timestamp object is first turned
1640 into a custom string:
1642 #+BEGIN_SRC emacs-lisp
1643 (defun org-html-timestamp (timestamp contents info)
1644 "Transcode a TIMESTAMP object from Org to HTML.
1645 CONTENTS is nil. INFO is a plist holding contextual
1647 (let ((value (org-html-plain-text
1648 (org-timestamp-translate timestamp) info)))
1649 (format "<span class=\"timestamp-wrapper\"><span class=\"timestamp\">%s</span></span>"
1650 (replace-regexp-in-string "--" "–" value))))
1653 * Interactive functions
1655 :CUSTOM_ID: interactive
1658 Once the back-end is complete, interactive functions have to be
1659 offered for the user to use it. Depending on the desired output,
1660 three functions are provided to help in this task, along with
1661 a wrapper function allowing to make export asynchronous.
1663 Hence, ~org-export-to-buffer~ may be used if the expected output is
1664 a temporary buffer whereas ~org-export-to-file~ will be used when
1665 exporting to a file. In the latter case,
1666 ~org-export-output-file-name~ can be useful to guess the name of the
1667 output file --- though, don't use it in an external process, since
1668 it will ask the user for a file name when guessing fails. At the
1669 lowest level, ~org-export-as~ returns the output as a string.
1671 While it is suggested to have a look at their respective docstring,
1672 the following examples illustrate how to combine all these
1675 1. Export to a temporary buffer:
1677 #+BEGIN_SRC emacs-lisp
1679 (defun org-latex-export-as-latex
1680 (&optional async subtreep visible-only body-only ext-plist)
1682 (org-export-to-buffer 'latex "*Org LATEX Export*"
1683 async subtreep visible-only body-only ext-plist (lambda () (LaTeX-mode))))
1686 2. Export to a file:
1688 #+BEGIN_SRC emacs-lisp
1690 (defun org-latex-export-to-latex
1691 (&optional async subtreep visible-only body-only ext-plist)
1693 (let ((outfile (org-export-output-file-name ".tex" subtreep)))
1694 (org-export-to-file 'latex outfile
1695 async subtreep visible-only body-only ext-plist)))
1698 It may also be interesting to provide a publishing function for the
1699 back-end. Such function must accept three arguments: a plist
1700 containing properties relative to the project being exported, the
1701 name of the current file being published and the publishing
1702 directory. It often is a simple wrapper around ~org-publish-org-to~
1703 function defined in =ox-publish.el=, as shown in the following
1706 #+BEGIN_SRC emacs-lisp
1707 (defun org-html-publish-to-html (plist filename pub-dir)
1708 (org-publish-org-to 'html filename ".html" plist pub-dir))
1713 # sentence-end-double-space: t