Org Macros

Tip

Transform your Emacs experience in Paris from 24 to 28 November 2025!

Unlock unparalleled productivity with my exclusive “EmacsBoost” course!*

Are you ready to supercharge your productivity and become an unstoppable Emacs ninja? This is the opportunity you’ve been waiting for!

What you’ll learn:

Expertly master Emacs from the ground up to advanced techniques that set you apart.
Maximize your editing efficiency and elevate your workflow to new heights.
Personalize Emacs to perfectly fit your unique style and needs.
And much more tips and tricks!

Who should join:

This course is designed for everyone passionate about Emacs – from curious beginners to seasoned users looking to refine their skills.

Why choose my course?

Learn from an expert instructor with over 26 years of Emacs mastery.
Engage in dynamic hands-on exercises that reinforce and enhance your learning journey.
Enjoy exclusive networking opportunities with fellow Emacs enthusiasts who share your passion.
Experience personalized guidance tailored just for you.

Seize this exceptional opportunity to elevate your Emacs skills to new levels!

Visit https://emacsboost.com/en/ for more details, course dates and locations, and to secure your place today.

Overview

Description

The macros in Org allow you to add text or code to an Org document that will be expanded during export: the text between the 3 pairs of accolades is expanded so that readers can see it in the exported versions of the document.

Some people (such as me) use it to construct complex HTML or LaTeX code.

Objectives

Using macros allows you to insert dynamic content or add extra functionality in exports of an Org document.

Features

These Org-macros have been tested for HTML exports.

FIXME They will be soon made available for PDF exports.

Code

Checkout

Use this command to check out the latest source code of the project from the Git repository hosted at GitHub:

git clone https://github.com/fniessen/org-macros

Installation

Load the macro definitions via:

#+INCLUDE:   /PATH/TO/org/setup/org-macros.setup

Usage

Once you’ve cloned Org-macros, many macros will be ready to use within your Org files.

You can invoke macros anywhere in the document (even in code examples).

Examples:

With no arguments:
```
{{{macro-name}}}
    
```
With arguments:
```
{{{macro-name(arg1,arg2)}}}
    
```

Macros

Below is a list of the few macros currently available.

Org built-ins

author macro
date macro
email macro
input-file macro
modification-time macro
property macro
time macro
title macro

Basic formatting

bgcolor macro
clearpage macro
pagebreak macro
framebreak macro
fnb macro
visfootnote macro
color macro
lcolor macro
fixme macro
highlight macro
hl macro
loremipsum macro
newline macro
redact macro
kbd macro
ikbd macro
idx macro
sup macro

Advanced

dvipng-when-odt macro
if-latex-else macro
if-html-else macro
raw-latex macro
raw-html macro
pause (Beamer overlay) macros
style macro

Generic macros

image macro
recently-updated macro
tasklist macro
git-version macro
version-history macro

Layout

vspace macro
vsp macro
collapse macro
info macro
minipage macro
note macro
panel macro
tip macro
warning macro

Navigation and lists

children macro (to display child pages)
toc macro

Dev tools

twitter-share-link-button macro

Cookie

# -*- mode: org; -*-

Org built-ins

Property macro

The property macro outputs …

Parameters

Node property name.

Examples

* TODO Do it!
:PROPERTIES:
:Effort:   1:00
:END:

This task should take no more than {{{property(Effort)}}} hours.

Time macro

The time macro outputs the current date and time when the document is being exported.

Parameters

Format string understood by format-time-string.

Examples

This document was last exported on: {{{time(%Y-%m-%d %a %H:%M)}}}.

Title macro

The title macro outputs the document title.

Parameters

None.

Examples

The title of this document is: {{{title}}}.

Basic formatting

BgColor macro

The bgcolor macro allows you to change the background color of a block of text.

Code

#+MACRO: bgcolor @@latex:\colorbox{$1}{$2}@@ @@html:<div style="background-color: $1;">$2</div>@@

Parameters

Color name or hexadecimal code.
Text you want to color.

Examples

{{{bgcolor(red, This information is important.)}}} {{{bgcolor(#E0E0E0, This other isn’t.)}}}

Common color names are supported by most Org exporters (HTML, LaTeX):

{{{bgcolor(red, Attention importante !)}}} {{{bgcolor(orange, En cours de traitement)}}} {{{bgcolor(yellow, Conseil utile)}}} {{{bgcolor(green, Action validée)}}} {{{bgcolor(blue, Information)}}} {{{bgcolor(purple, Objectif clé)}}} {{{bgcolor(violet, Particularité)}}}

You can also use hexadecimal color codes (to match an existing design palette):

{{{bgcolor(#FF6B6B, Erreur critique)}}} {{{bgcolor(#4ECDC4, Succès confirmé)}}} {{{bgcolor(#45B7D1, Lien externe)}}}

Clearpage macro

The clearpage macro forces a page break in all supported export backends.

In LaTeX, it also flushes pending floats before starting the new page.

In HTML, the page break is not visible on screen, but it is applied when printing.

Code

#+MACRO: clearpage @@latex:\clearpage@@ @@html:<div style="page-break-after: always;">&nbsp;</div>@@ @@odt:<text:p text:style-name="PageBreak"/>@@

For details on defining custom ODT styles in Org-mode, see: Creating one-off styles.

Parameters

None.

Examples

Insert a forced page break:

{{{clearpage}}}

Pagebreak macro

The pagebreak macro forces a page break without flushing floats.

Its behavior is equivalent to \newpage in LaTeX.

In HTML, the page break is not visible in the browser, but it is applied when printing.

Code

#+MACRO: pagebreak @@latex:\newpage@@ @@html:<div style="page-break-before: always;">&nbsp;</div>@@ @@odt:<text:p text:style-name="PageBreak"/>@@

Parameters

None.

Examples

Insert a simple page break:

{{{pagebreak}}}

framebreak macro

The framebreak (or framebreak---) macro inserts a Beamer frame break.

It is equivalent to the Beamer command \framebreak. It is useful to split a single frame into multiple slides at a precise point.

This macro is intended for Beamer export only. It has no effect for non-Beamer backends.

Code

#+MACRO: framebreak @@beamer:\framebreak@@
#+MACRO: framebreak--- @@beamer:\framebreak@@

Parameters

None.

Examples

Insert a frame break inside a frame:

* My slide title
:PROPERTIES:
:BEAMER_opt: allowframebreaks
:END:

First part of the frame.

{{{framebreak---}}}

Second part of the same frame (exported as the next slide).

You can also insert multiple breaks:

Part 1. {{{framebreak}}}
Part 2. {{{framebreak}}}
Part 3.

Remarks

For the “split into multiple slides” behavior, Beamer frames typically need the allowframebreaks option (for example via :BEAMER_OPT: allowframebreaks).

Without allowframebreaks, Beamer may not split the frame as expected.

Fnb (Beamer footnote) macro

The fnb macro inserts a raw LaTeX footnote using the \footnote{...} command.

Unlike Org’s native footnotes, this macro bypasses Org’s footnote processing and injects the LaTeX command directly into the exported document.

This is particularly useful in Beamer presentations, where direct control over footnote rendering may be desirable.

Code

#+MACRO: fnb @@latex:\footnote{$1}@@

Parameters

Parameter	Description
`$1`	Footnote text to insert.

Examples

Insert a footnote in a Beamer slide:

Here is some text {{{fnb(This is a footnote.)}}}.

which expands to:

Here is some text @@latex:\footnote{This is a footnote.}@@.

and produces:

\footnote{This is a footnote.}

during LaTeX/Beamer export.

Advantages

Full control over the generated LaTeX code.
Avoids potential issues with Org footnote conversion in Beamer frames.
Useful when the document is intended exclusively for LaTeX/Beamer PDF output.

Limitations

Produces no output for non-LaTeX export backends.
Not portable across export formats.

visfootnote (Beamer overlay footnote) macro

The visfootnote macro provides a shortcut for inserting Beamer footnotes that appear only on specific overlays.

It wraps a custom Beamer command based on \visible and \footnote, allowing footnotes to participate in overlay specifications in the same way as other Beamer content.

This macro is useful when revealing slide content progressively and a footnote should appear only when the associated content becomes visible.

Code

The underlying Beamer command (see beamer-only.setup):

% Footnote visible only on the specified overlays.
\newcommand<>{\visfootnote}[1]{%
  \visible#2{\footnote#2[frame]{#1}}%
}

The Org macro:

#+MACRO: visfootnote @@beamer:\visfootnote<$1>{$2}@@

Parameters

The macro accepts two parameters:

An overlay specification.
The footnote text.

Examples

Git was created by Linus Torvalds.
{{{visfootnote(2-,Initial development started in 2005.)}}}

Exports to:

Git was created by Linus Torvalds.
\visfootnote<2->{Initial development started in 2005.}

The footnote is hidden on the first overlay and becomes visible starting from overlay 2.

Typical Usage

The macro is particularly useful together with progressive disclosure:

- First point.
- Second point. {{{visfootnote(2,Additional details.)}}}
- Third point.

This ensures that the footnote appears only when the corresponding item becomes visible.

Overlay Specifications

Any valid Beamer overlay specification may be used:

Specification	Meaning
`1`	Only on overlay 1
`2`	Only on overlay 2
`2-`	From overlay 2 onward
`3-5`	Overlays 3 through 5
`1,3`	Overlays 1 and 3

For example:

{{{visfootnote(3-5,Visible on overlays 3 to 5.)}}}

Important

The macro is intended for Beamer export only.

When exporting to non-Beamer backends, the macro expands to nothing because it relies on Beamer-specific overlay commands.

The macro should be used only when a footnote must follow overlay visibility. For ordinary footnotes that are always visible, standard Org footnotes remain the preferred solution.

—

Color macro

The color macro allows you to change the foreground color of inline text.

Code

#+MACRO: color @@html:<span style="color: $1">$2</span>@@ @@latex:\textcolor{$1}{$2}@@ @@odt:<text:span text:style-name="$1">$2</text:span>@@

Parameters

Color name or hexadecimal code.
Text you want to color.

Examples

{{{color(red, This information is important.)}}} {{{color(#E0E0E0, This other isn’t.)}}}

Common color names are supported by most Org exporters (HTML, LaTeX):

{{{color(red, red)}}} {{{color(orange, orange)}}} {{{color(yellow, yellow)}}} {{{color(green, green)}}} {{{color(blue, blue)}}} {{{color(purple, purple)}}} {{{color(violet, violet)}}}

You can also use hexadecimal color codes:

{{{color(#FF0000, #FF0000)}}} {{{color(#00FF00, #00FF00)}}} {{{color(#0000FF, #0000FF)}}}

Lcolor macro

The lcolor macro is similar to color macro except it first converts org markup to latex and then applies color.

Code

#+MACRO: lcolor (eval (concat "\n#+BEGIN_EXPORT latex\n {\color{" $1 (format "}{%s}}\n#+END_EXPORT\n" (org-export-string-as $2 'latex t))))

Parameters

Color name
Text you want to color.

Examples

{{{lcolor(red, This information is **important**.)}}}

Common color names are supported by most Org exporters (HTML, LaTeX):

{{{lcolor(red, red)}}} {{{lcolor(orange, orange)}}} {{{lcolor(yellow, yellow)}}} {{{lcolor(green, green)}}} {{{lcolor(blue, blue)}}} {{{lcolor(purple, purple)}}} {{{lcolor(violet, violet)}}}

Fixme macro

The fixme macro inserts a visible “FIXME” marker, with CSS available for customizing its appearance.

Code

#+MACRO: fixme @@latex:\textcolor{red}{\textbf{FIXME}}@@ @@html:<span class="fixme">FIXME</span>@@

CSS example:

.fixme {
    background: #FFFF88 url('../images/fixme.png') no-repeat top left;
    color: #CC0000;
    display: inline-block;
    height: 16px;
    text-indent: -9999px;
    width: 82px;
}

Parameters

None.

Examples

{{{fixme}}} Delete this…

Testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing {{{fixme}}} testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing testing

Highlight macro

The highlight macro allows you to change the background color of inline text.

Code

#+MACRO: highlight @@latex:\colorbox{$1}{$2}@@ @@html:<span style="background-color: $1;">$2</span>@@

Parameters

Color name or hexadecimal code.
Text you want to color.

Examples

{{{highlight(red, Highlighting text is easy in Org mode.)}}} {{{highlight(#E0E0E0, This text isn’t important.)}}}

Common color names are supported by most Org exporters (HTML, LaTeX):

{{{highlight(red, red)}}} {{{highlight(orange, orange)}}} {{{highlight(yellow, yellow)}}} {{{highlight(green, green)}}} {{{highlight(blue, blue)}}} {{{highlight(purple, purple)}}} {{{highlight(violet, violet)}}}

You can also use hexadecimal color codes:

{{{highlight(#FF0000, #FF0000)}}} {{{highlight(#00FF00, #00FF00)}}} {{{highlight(#0000FF, #0000FF)}}}

Hl macro

The hl macro allows you to highlight text with a “neon marker” effect in both HTML and LaTeX exports.

Code

#+MACRO: hl @@latex:\hl{$1}@@ @@html:<span style="background-color:#FFFF00;">$1</span>@@

Requirements

For LaTeX or PDF export, the soul package must be loaded.

#+LATEX_HEADER: \usepackage{soul}

Optionally, to ensure a yellow highlight color:

#+LATEX_HEADER: \sethlcolor{yellow}

Parameters

The text to highlight.

Examples

{{{hl(This information is important.)}}}

LoremIpsum macro

The loremipsum macro displays one paragraph of meaningless text that you can use for demonstration purposes of visual elements such as font, typography or layout.

Code

#+MACRO: loremipsum Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Parameters

None.

Examples

This is a basic example of the Loremipsum text:

{{{loremipsum}}}

Newline macro

\\ in headlines doesn’t cause a line break, but gets exported in LaTeX to $\backslash$ .

You have to put it in a macro.

Code

#+MACRO: newline @@latex:\hspace{0pt}\\@@ @@html:<br>@@

Parameters

None.

Examples

#+TITLE: Foo {{{newline}}} bar

Redact macro

The redact macro conceals inline text in HTML export by applying a black foreground and background color, making the text appear as a black box.

Code

#+MACRO: redact @@latex:\colorbox{black}{\textcolor{black}{$1}}@@ @@html:<span class="redact" style="color:black; background-color:black;">$1</span>@@

Parameters

Text to conceal.

Examples

To {{{redact(redact)}}} or not to {{{redact(redact)}}} that is the question.

Kbd macro

The kbd macro formats an inline command, keyboard shortcut, or shell fragment.

It provides a consistent rendering across LaTeX/PDF and HTML exports.

Code

#+HTML_HEAD: <style>
#+HTML_HEAD: kbd.kbd {background:#eee;border:none;padding:0 .25em}
#+HTML_HEAD: </style>
#+MACRO: kbd @@latex:\lightcommandbox{$1}@@ @@html:<kbd class="kbd">$1</kbd>@@

Requirements

For LaTeX or PDF export, the latex-listings.setup setup file must be loaded, as it defines the \lightcommandbox command and its required dependencies.

#+SETUPFILE: ~/org/setup/latex-listings.setup

When exporting Beamer presentations, frames containing kbd or ikbd macros must be marked as fragile because the underlying implementation relies on \lstinline.

A convenient way is to enable fragile frames globally in the document:

#+BIND: org-beamer-frame-default-options "fragile"

Parameters

Text to display.

Examples

Press {{{kbd(C-x C-s)}}} to save the buffer.
Use {{{kbd(git status)}}} to display the repository status.

LaTeX export:

Renders the text using \lightcommandbox{...} (see tcolorbox)

HTML export:

Renders <kbd>...</kbd>

Ikbd macro

The ikbd macro formats an inline command, keyboard shortcut, or shell fragment and simultaneously creates an index entry when exporting to LaTeX.

It provides a unified syntax for documenting commands across LaTeX/PDF and HTML backends.

In LaTeX, it combines \index and \commandbox.

In HTML, it renders the content using the <kbd> element.

Code

#+HTML_HEAD: <style>
#+HTML_HEAD: kbd.ikbd {background:#e8f1ff;border:1px solid #4f6fb3;padding:0 .25em}
#+HTML_HEAD: </style>
#+MACRO: ikbd @@latex:\index{$1}\commandbox[$2]{$1}@@ @@html:<kbd class="ikbd">$1</kbd>@@

Requirements

For LaTeX or PDF export, the latex-listings.setup setup file must be loaded, as it defines the \commandbox command and its required dependencies.

#+SETUPFILE: ~/org/setup/latex-listings.setup

When exporting Beamer presentations, frames containing ikbd or kbd macros must be marked as fragile because the underlying implementation relies on \lstinline.

A convenient way is to enable fragile frames globally in the document:

#+BIND: org-beamer-frame-default-options "fragile"

Parameters

Text to display and index.
Optional LaTeX options passed directly to \commandbox.
This parameter is ignored for HTML export.

It is primarily intended to customize the underlying listings configuration for a specific command, for example when additional characters must be treated as part of an identifier.

Examples

Press {{{ikbd(C-c a a)}}} to launch the agenda.

Use {{{ikbd(git status)}}} to display the repository status.

Search aliases with {{{ikbd(grep-aliases,alsoletter={-})}}}.

LaTeX export:

Press \index{C-c a a}\commandbox[]{C-c a a} to launch the agenda.

Use \index{git status}\commandbox[]{git status} to display the repository status.

Search aliases with
\index{grep-aliases}\commandbox[alsoletter={-}]{grep-aliases}.

HTML export:

Press <kbd class="ikbd">C-c a a</kbd> to launch the agenda.

Use <kbd class="ikbd">git status</kbd> to display the repository status.

Search aliases with <kbd class="ikbd">grep-aliases</kbd>.

Remarks

The second parameter is LaTeX-specific and is ignored when exporting to HTML.

When omitted, the macro emits \commandbox[]..., which behaves the same as \commandbox... because the optional argument is empty.

Idx macro

The idx macro creates an index entry when exporting to LaTeX.

It is intended for situations where a term, key, or key sequence should be added to the document index without producing any visible output.

The macro is evaluated only for LaTeX export and produces no output for other backends, including HTML.

Code

#+MACRO: idx @@latex:\index{$1}@@

Parameters

Term to add to the index.

Sup macro

The sup macro produces a superscript while preventing unwanted ligatures or spacing issues in LaTeX by inserting a zero-width non-joiner before the superscript.

It is mainly intended for LaTeX-derived backends and is useful for footnote markers, ordinal indicators, or mathematical-style annotations in running text.

Code

#+MACRO: sup \zwnj^{$1}

Parameters

Text to be rendered as superscript.

Examples

E = mc{{{sup(2)}}}

LaTeX export:

E = mc\zwnj^{2}

The zero-width non-joiner prevents TeX from incorrectly joining the superscript with the preceding glyph.

Advanced

Dvipng-when-odt macro

Code

#+MACRO: dvipng-when-odt (eval (if (org-export-derived-backend-p org-export-current-backend 'odt) "#+OPTIONS: tex:dvipng" ""))

Parameters

Examples

If-latex-else macro

The if-latex-else macro conditionally expands its content depending on whether the current export backend is derived from LaTeX.

It allows writing backend-specific content inline, without duplicating sections or using export blocks.

Code

#+MACRO: if-latex-else (eval (if (org-export-derived-backend-p org-export-current-backend 'latex) "$1" "$2"))

Parameters

Code expanded when exporting to a LaTeX-derived backend (LaTeX, Beamer, etc.).
Code expanded when exporting to any other backend.

Examples

{{{if-latex-else(LaTeX stuff,other stuff)}}}

When exporting to LaTeX or Beamer, this expands to:

LaTeX stuff

When exporting to another backend, it expands to:

other stuff

If-html-else macro

The if-html-else macro conditionally expands its content depending on whether the current export backend is derived from HTML.

It allows writing backend-specific content inline, without duplicating sections or using export blocks.

Code

#+MACRO: if-html-else (eval (if (org-export-derived-backend-p org-export-current-backend 'html) "$1" "$2"))

Parameters

Code expanded when exporting to an HTML-derived backend.
Code expanded when exporting to any other backend.

Examples

{{{if-html-else(HTML stuff,other stuff)}}}

When exporting to HTML, this expands to:

HTML stuff

When exporting to another backend, it expands to:

other stuff

Raw-latex macro

The raw-latex macro inserts raw LaTeX code when exporting to a LaTeX-derived backend (LaTeX, Beamer, etc.).

It has no effect for non-LaTeX backends.

Code

#+MACRO: raw-latex @@latex:$1@@

Parameters

Raw LaTeX code to be passed verbatim to the LaTeX exporter.

Examples

{{{raw-latex(\textbf{LaTeX only})}}}

When exporting to LaTeX or Beamer, this expands to:

\textbf{LaTeX only}

For non-LaTeX backends, the macro expands to nothing.

Raw-html macro

The raw-html macro inserts raw HTML code when exporting to an HTML-derived backend.

It has no effect for non-HTML backends.

Code

#+MACRO: raw-html @@html:$1@@

Parameters

Raw HTML code to be passed verbatim to the HTML exporter.

Examples

{{{raw-html(<span class="note">HTML only</span>)}}}

When exporting to HTML, this expands to:

<span class="note">HTML only</span>

For non-HTML backends, the macro expands to nothing.

pause (Beamer overlay) macros

The pause and pausestar macros provide shortcuts for inserting inline Beamer overlay pauses in slides exported with ox-beamer.

They wrap Beamer’s \pause and \pause* commands using Org’s backend-specific inline export syntax.

These macros simplify the writing of slides where sentences, paragraphs, examples, or other content should appear progressively, without using lists, blocks, or explicit overlay specifications.

Code

#+MACRO: pause @@beamer:\pause{}@@
#+MACRO: pausestar @@beamer:\pause*{}@@

Parameters

Neither macro accepts parameters.

Each macro performs a direct textual substitution during export to the Beamer backend.

Examples

First sentence. {{{pause}}}
Second sentence. {{{pause}}}
Third sentence.

Exports to:

First sentence. \pause
Second sentence. \pause
Third sentence.

Similarly:

First sentence. {{{pausestar}}}
Second sentence.

exports to:

First sentence. \pause*
Second sentence.

Difference between `pause` and `pausestar`

{{{pause}}} expands to \pause.
{{{pausestar}}} expands to \pause*.

The starred form is provided by Beamer and behaves differently from \pause in some overlay situations. Refer to the Beamer User Guide for the precise semantics and overlay interaction rules.

Important

The Beamer \pause and \pause* commands should not be used together with frames configured with:

:BEAMER_opt: allowframebreaks

The allowframebreaks option automatically splits long frames across multiple slides and does not interact reliably with Beamer overlays. When combined with overlay commands, only part of the frame content may be displayed or exported as expected.

Choose one of the following approaches:

Use allowframebreaks for long static content that must be split automatically across several slides.
Use {{{pause}}}, {{{pausestar}}}, overlay specifications such as <+->, or explicit Beamer overlay commands when progressive disclosure is required.

Style macro

The style macro allows importing an external CSS style sheet into an HTML export.

It expands to an #+HTML_HEAD_EXTRA directive and therefore applies only to HTML-derived backends.

Code

#+MACRO: style (eval (concat "#+HTML_HEAD_EXTRA: <link type=\"text/css\" rel=\"stylesheet\" href=\"" "$1" "\" media=\"all\">"))

Parameters

URL of the external CSS style sheet.

Examples

{{{style(http://whatever.com/mystyle.css)}}}

This expands during export to:

#+HTML_HEAD_EXTRA: <link type="text/css" rel="stylesheet" href="http://whatever.com/mystyle.css" media="all">

The referenced style sheet is then loaded by the generated HTML page.

Generic

Image macro

The image macro displays an image.

Code

#+MACRO: image \includegraphics{$1}

Parameters

Path to image file.

Examples

{{{image}}}

{{{image(a.png)}}}	{{{image(b.png)}}}
{{{image(c.png)}}}	{{{image(d.png)}}}

Version-history macro

The version-history macro inserts the history of (the last 5) updates made to a document: version number, date, author and comment.

XXX + link to View Changes?

Code

#+name: version-history
#+begin_src shell :exports none :results silent :colnames '(Version Date Author Comment)
git log --pretty=format:"%h%x09%ad%x09%an%x09%s" --date=short | head -n 5
#+end_src

#+MACRO: version-history call_version-history[:eval yes]()[:eval yes :results table :colnames '(Version Date Author Comment)]

Parameters

None.

Remarks

This only will work with Git repositories.

Note also this requires org-babel with shell enabled and :eval yes allowed in the document.

Examples

{{{version-history}}}

Git-version macro

The git-version macro returns the Git version for the repository containing the exported file. It uses the nearest tag when one is available, otherwise it returns the abbreviated commit ID. A dirty working tree is marked with -dirty.

If the file is not inside a Git repository, or Git cannot provide a version, the macro returns unknown.

Code

#+MACRO: git-version (eval (let* ((file (or (and (boundp 'org-export-current-file) org-export-current-file) (buffer-file-name))) (directory (file-name-directory (or file default-directory))) (root (and directory (locate-dominating-file directory ".git")))) (if root (with-temp-buffer (if (= 0 (call-process "git" nil t nil "-C" (expand-file-name root) "describe" "--tags" "--always" "--dirty")) (replace-regexp-in-string "[\n\r]+\\'" "" (buffer-string)) "unknown")) "unknown")))

Parameters

None.

Examples

This document was generated from Git version {{{git-version}}}.

Requirements

Git must be installed and available on PATH. Macro evaluation must be enabled when exporting the document.

Layout

Vspace macro

The vspace macro adds a fixed vertical gap to your Org document when exporting.

Code

#+MACRO: vspace @@latex:\vspace{10pt}@@ @@html:<div style="margin-bottom: 10pt;"></div>@@

Parameters

None. The 10 pt value is baked into the macro definition.

Examples

Insert space between paragraphs:

First paragraph.

{{{vspace}}}

Second paragraph.

Customization

To change the gap, redefine the macro in your setup:

#+MACRO: vspace @@latex:\vspace{20pt}@@ @@html:<div style="margin-bottom: 20pt;"></div>@@

Vsp macro

The vsp macro inserts vertical space in Org-mode exports (LaTeX and HTML). It takes one optional parameter – the amount of space to insert.

Code

#+MACRO: vsp @@latex:\vspace{$1}@@ @@html:<div style="margin-bottom: $1;"></div>@@

Parameters

$1: any valid TeX/CSS length (e.g. 10pt, 1em, 2cm, 15px).

Examples

Insert space between paragraphs:

First paragraph.

{{{vsp(20pt)}}}

Second paragraph appears after 20 pt of extra space.

{{{vsp(1.5em)}}}

Collapse macro

The collapse macro inserts of collapsed block of text.

Code

#+MACRO: begin_collapse @@latex:\par\noindent\textbf{$1}\par@@ @@html:<details><summary>$1</summary>@@
#+MACRO: end_collapse @@latex:\par@@ @@html:</details>@@

Parameters

None.

Examples

{{{begin_collapse(View details…)}}} This is a block of text that is collapsed by default. It can be expanded by clicking a link. {{{end_collapse}}}

Info macro

The info macro is useful for including helpful information.

Code

#+MACRO: begin_info @@latex:\par\noindent\textbf{Info:} @@ @@html:<div class="info"><p>@@
#+MACRO: end_info @@latex:\par@@ @@html:</p></div>@@

Parameters

None.

Examples

{{{begin_info}}} Info example
Did you know… {{{end_info}}}

Remarks

You’d better use a “special block”, such as:

#+begin_info
*Info example* \\
Did you know...
#+end_info

Minipage macro

Code

#+MACRO: begin_minipage @@latex:\begin{center}\begin{minipage}{0.95\linewidth}@@ @@html:<div style="border:1px solid #aaaaaa;padding:10px;width:780px;margin-left:auto;margin-right:auto;">@@
#+MACRO: end_minipage @@latex:\end{minipage}\end{center}@@ @@html:</div>@@

Parameters

Examples

Note macro

Code

#+MACRO: begin_note @@latex:\begin{quote}\textbf{Note:} @@ @@html:<div class="note"><p>@@
#+MACRO: end_note @@latex:\end{quote}@@ @@html:</p></div>@@

Parameters

None.

Examples

{{{begin_note}}} Note example
This is a useful note… {{{end_note}}}

Remarks

You’d better use a “special block”, such as:

#+begin_note
*Note example* \\
This is a useful note...
#+end_note

Panel macro

Code

#+MACRO: begin_panel @@latex:\begin{quote}@@ @@html:<div class="panel"><p>@@
#+MACRO: end_panel @@latex:\end{quote}@@ @@html:</p></div>@@

XXX PanelHeader + PanelContent

Parameters

None.

Examples

{{{begin_panel}}} Panel example
This is a formatted block of text… {{{end_panel}}}

Remarks

You’d better use a “special block”, such as:

#+begin_panel
*Panel example* \\
This is a formatted block of text...
#+end_panel

Tip macro

Code

#+MACRO: begin_tip @@latex:\begin{quote}\textbf{Tip:} @@ @@html:<div class="tip"><p>@@
#+MACRO: end_tip @@latex:\end{quote}@@ @@html:</p></div>@@

Parameters

None.

Examples

{{{begin_tip}}} Tip example
Try doing it this way… {{{end_tip}}}

Remarks

You’d better use a “special block”, such as:

#+begin_tip
*Tip example* \\
Try doing it this way...
#+end_tip

Warning macro

Code

#+MACRO: begin_warning @@latex:\begin{quote}\textbf{Warning:} @@ @@html:<div class="warning"><p>@@
#+MACRO: end_warning @@latex:\end{quote}@@ @@html:</p></div>@@

Parameters

None.

Examples

{{{begin_warning}}} Warning example
Be careful! Check that you have… {{{end_warning}}}

Remarks

You’d better use a “special block”, such as:

#+begin_warning
*Warning example* \\
Be careful! Check that you have...
#+end_warning

Vertically aligning table row contents

I’m trying to create a simple two-column table. The left column will show images of symbols used in the document, and the right column will explain what those images mean.

{{{p(./GreenDot.png)}}}	This symbol indicates that the associated item is in a normal or successful state.
{{{p(./YellowDots.png)}}}	This symbol denotes a state of concern or potential trouble for the associated item.
{{{p(./RedDots.png)}}}	This symbol indicates that the associated item is in a severely troubled or non-functioning state.

Navigation and lists

FIXME Problem with the tab title.

Toc macro

Insert a customizable headlines table of contents (TOC) at the macro’s location during export.

Code

#+MACRO: toc (eval (concat "#+TOC: headlines " "$1" " " "$2"))

(Where $2 is optional and may contain additional #+TOC options such as local or :target #CustomID.)

Parameters

Number of headline levels to include (integer, e.g. 1, 2, 3).
(Optional) Extra option(s), such as local (for relative depth, showing only direct children of the current section) or :target #CustomID.

Remarks

The toc macro expands to a full #+TOC: keyword line, so the table of contents appears as a block (can’t be inline within a paragraph of text).

You usually need to disable the default automatic TOC with #+OPTIONS: toc:nil (or org-export-with-toc nil) to avoid duplication.

This macro is useful for placing TOCs at specific locations, inserting multiple TOCs, or creating local sub-TOCs.

Examples

Simple global TOC with 3 levels:
```
#+OPTIONS: toc:nil

{{{toc(3,)}}}
    
```
Local TOC showing only direct children of a section:
```
* My Section

{{{toc(1,local)}}}
    
```
Shows only level-2 children of “My Section”.

Listing

Dev tools

Twitter “Share a link”

Add a “Share a link” button to your website.

Code

#+MACRO: twitter-share-link-button @@html:<script src="http://platform.twitter.com/widgets.js"></script><a href="https://twitter.com/share" class="twitter-share-button" data-via="$1">Tweet</a>@@

Parameters

Username.

Examples

Insert the Twitter “Share a link” button here:

{{{twitter-share-link-button(f_niessen)}}}

Others

Keep a library of helpful CSS classes. Useful for debugging, but should be avoided in the release version (separate markup and presentation). Since you can use multiple class names (i.e. <p class="floatLeft alignLeft width75">...</p>), make use of them debugging your markup.

.width100 { width: 100%; }
.width75 { width: 75%; }
.width50 { width: 50%; }
.floatLeft { float: left; }
.floatRight { float: right; }
.alignLeft { text-align: left; }
.alignRight { text-align: right; }

.clear         { clear: both; }
.float-left    { float: left; }
.float-right   { float: right; }

.highlight     { background: #FFFFCC; }

.wrap          { width: 960px; margin: 0 auto; }

.img-left      { float: left; margin: 4px 10px 4px 0; }
.img-right     { float: right; margin: 4px 0 4px 10px; }

.nopadding     { padding: 0; }
.noindent      { margin-left: 0; padding-left: 0; }
.nobullet      { list-style: none; list-style-image: none; }

Contributing

Issues

Report issues and suggest features and improvements on the GitHub issue tracker.

Patches

I love contributions! Patches under any form are always welcome!

Donations

If you use the org-macros project and feel it is making your life better and easier, you can show your appreciation and help support future development by making today a donation through PayPal. Thank you!

Regardless of the donations, org-macros will always be free both as in beer and as in speech.

License

Author: Fabrice Niessen
Keywords: org-mode macros

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Name		Name	Last commit message	Last commit date
images		images
org/setup		org/setup
tests		tests
AGENTS.md		AGENTS.md
LICENSE		LICENSE
Makefile		Makefile
README.org		README.org
TODO-org-macros.org		TODO-org-macros.org

Latest commit

History

Folders and files

Repository files navigation

Org Macros

Transform your Emacs experience in Paris from 24 to 28 November 2025!

Overview

Description

Objectives

Features

Code

Checkout

Installation

Usage

Macros

Org built-ins

Basic formatting

Advanced

Generic macros

Layout

Navigation and lists

Dev tools

Cookie

Org built-ins

Author macro

Parameters

Examples

See also

Date macro

Parameters

Examples

See also

Email macro

Parameters

Examples

See also

Input-file macro

Parameters

Examples

Modification-time macro

Parameters

Examples

See also

Property macro

Parameters

Examples

Time macro

Parameters

Examples

See also

Title macro

Parameters

Examples

See also

Basic formatting

BgColor macro

Code

Parameters

Examples

See also

Clearpage macro

Code

Parameters

Examples

See also

Pagebreak macro

Code

Parameters

Examples

See also

framebreak macro

Code

Parameters

Examples

Remarks

See also

Fnb (Beamer footnote) macro

Code

Parameters

Examples