Skip to main content

13.5 Macro Replacement

Macros replace text snippets during export. Macros are defined globally in org-export-global-macros, or document-wise with the following syntax:

#+MACRO: name   replacement text; $1, $2 are arguments

which can be referenced using ‘{{{name(arg1, arg2)}}}’1. For example

#+MACRO: poem Rose is $1, violet's $2. Life's ordered: Org assists you.
{{{poem(red,blue)}}}

becomes

Rose is red, violet's blue. Life's ordered: Org assists you.

As a special case, Org parses any replacement text starting with ‘(eval’ as an Emacs Lisp expression and evaluates it accordingly. Within such templates, arguments become strings. Thus, the following macro

#+MACRO: gnustamp (eval (concat "GNU/" (capitalize $1)))

turns ‘{{{gnustamp(linux)}}}’ into ‘GNU/Linux’ during export.

Org recognizes macro references in following Org markup areas: paragraphs, headlines, verse blocks, tables cells and lists. Org also recognizes macro references in keywords, such as ‘CAPTION’, ‘TITLE’, ‘AUTHOR’, ‘DATE’, and for some back-end specific export options.

Org comes with following pre-defined macros:

‘{{{keyword(NAME)}}}’​

‘{{{title}}}’​

‘{{{author}}}’​

‘{{{email}}}’​

The ‘keyword’ macro collects all values from NAME keywords throughout the buffer, separated with white space. ‘title’, ‘author’ and ‘email’ macros are shortcuts for, respectively, ‘{{{keyword(TITLE)}}}’, ‘{{{keyword(AUTHOR)}}}’ and ‘{{{keyword(EMAIL)}}}’.

‘{{{date}}}’​

‘{{{date(FORMAT)}}}’​

This macro refers to the ‘DATE’ keyword. FORMAT is an optional argument to the ‘date’ macro that is used only if ‘DATE’ is a single timestamp. FORMAT should be a format string understood by format-time-string.

‘{{{time(FORMAT)}}}’​

‘{{{modification-time(FORMAT, VC)}}}’​

These macros refer to the document’s date and time of export and date and time of modification. FORMAT is a string understood by format-time-string. If the second argument to the modification-time macro is non-nil, Org uses ‘vc.el’ to retrieve the document’s modification time from the version control system. Otherwise Org reads the file attributes.

‘{{{input-file}}}’​

This macro refers to the filename of the exported file.

‘{{{property(PROPERTY-NAME)}}}’​

‘{{{property(PROPERTY-NAME, SEARCH OPTION)}}}’​

This macro returns the value of property PROPERTY-NAME in the current entry. If SEARCH-OPTION (see Search Options) refers to a remote entry, use it instead.

‘{{{n}}}’​

‘{{{n(NAME)}}}’​

‘{{{n(NAME, ACTION)}}}’​

This macro implements custom counters by returning the number of times the macro has been expanded so far while exporting the buffer. You can create more than one counter using different NAME values. If ACTION is ‘-’, previous value of the counter is held, i.e., the specified counter is not incremented. If the value is a number, the specified counter is set to that value. If it is any other non-empty string, the specified counter is reset to 1. You may leave NAME empty to reset the default counter.

Moreover, inline source blocks (see Structure of Code Blocks) use the special ‘results’ macro to mark their output. As such, you are advised against re-defining it, unless you know what you are doing.

The surrounding brackets can be made invisible by setting org-hide-macro-markers to a non-nil value.

Org expands macros at the very beginning of the export process.

  1. Since commas separate the arguments, commas within arguments have to be escaped with the backslash character. So only those backslash characters before a comma need escaping with another backslash character.↩