Org Macros

Tasks

On 2016-12-19, Nicolas Goaziou added org-export-global-macros in master. Could be interesting to use!

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

#+INCLUDE: /PATH/TO/org/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:

  {{{name-of-the-macro}}}
      

• With arguments:

  {{{name-of-the-macro(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
• color macro
• lcolor macro
• fixme macro
• highlight macro
• loremipsum macro
• newline macro
• redact macro
• kbd macro

Advanced

• dvipng-when-odt macro
• if-latex-else macro
• style macro

Generic macros

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

Layout

• 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

Author macro

The author macro outputs a list of users who have created or edited the document.

Parameters

None.

Examples

People who have created and edited this document: {{{author}}}.

See also

Option #+AUTHOR:.

Date macro

The date macro outputs the date and time specified in the document.

Parameters

1. Format string understood by format-time-string.

Examples

The date of this document is: {{{date}}} or {{{date(%Y-%m)}}}.

See also

• Option #+DATE: (for the whole document).
• Property :EXPORT_DATE: (for specific subtrees).
• modification-time macro.
• time macro.

Email macro

The email macro outputs the email of the author(s).

Parameters

None.

Examples

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

See also

Option #+EMAIL:.

Input-file macro

The input-file macro displays the name of the input Org file.

Parameters

None.

Examples

The input file name for this document is: {{{input-file}}}.

Modification-time macro

The modification-time macro outputs the modification date and time of the file being exported.

Parameters

1. Format string understood by format-time-string.

Examples

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

See also

• date macro.
• time macro.

Property macro

The property macro outputs …

Parameters

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

1. Format string understood by format-time-string.

Examples

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

See also

• date macro.
• modification-time macro.

Title macro

The title macro outputs the document title.

Parameters

None.

Examples

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

See also

Option #+TITLE:.

Basic formatting

BgColor macro

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

Code

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

Parameters

1. Color name or hexadecimal code.
2. 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, red)}}} {{{bgcolor(orange, orange)}}} {{{bgcolor(yellow, yellow)}}} {{{bgcolor(green, green)}}} {{{bgcolor(blue, blue)}}} {{{bgcolor(purple, purple)}}} {{{bgcolor(violet, violet)}}}

You can also use hexadecimal color codes:

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

See also

• color macro
• highlight macro
• hl macro

Clearpage macro

Code

#+MACRO: clearpage @@latex:\\clearpage@@@@odt:<text:p text:style-name="PageBreak"/>@@

Parameters

None.

Examples

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

1. Color name or hexadecimal code.
2. 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)}}}

See also

• bgcolor macro
• highlight macro
• hl macro

Lcolor macro

The lcolor macro is similar to color macro except (a) 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

1. Color name
2. Text you want to color.

Examples

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

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

See also

• bgcolor macro
• color macro
• highlight macro
• hl macro

Fixme macro

The fixme macro inserts a “Fix Me!” image (with adequate CSS).

Code

#+MACRO: 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 @@html:<span style="background-color: $1;">$2</span>@@

Parameters

1. Color name or hexadecimal code.
2. 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)}}}

See also

• bgcolor macro
• color macro
• hl macro

Hl macro

The hl macro allows you to highlight text with a “neon marker” effect.

Code

#+MACRO: hl {{{highlight(#FFFF00,$1)}}}

Parameters

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

Examples

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

See also

• bgcolor macro
• color macro
• highlight macro

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

Is there any way to completely redact text in HTML export, so it just looks like black boxes?

I’m not sure I fully understand, but it this what you are looking for?

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

Kbd macro

Code

#+MACRO: kbd @@html:<kbd>@@$1@@html:</kbd>@@

See menukeys for LaTeX.

Parameters

1. Text to markup.

Examples

Use {{{kbd(C-c a a)}}} to launch the agenda.

Advanced

dvipng-when-odt

Code

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

Parameters

Examples

if-latex macro

XXX

Code

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

Parameters

1. Code for LaTeX back-end.
2. Code for other back-ends.

Examples

{{{if-latex-else(latex code,something else)}}}

style

The style macro allows you to add custom style sheets to a page or import from an external URL.

Code

#+MACRO: style (eval (concat "#+HTML_HEAD_EXTRA: <style></style>"))

Parameters

URL to import an external style sheet.

Examples

<style type=”text/css”> .atb-sidebar.expanded {display:run-in;} .atb-sidebar.collapsed {display:none;visibility:collapse;} </style>

<link type=”text/css” rel=”stylesheet” href=”http://whatever.com/mystyle.css” media=”all”>

Generic

Image macro

The image macro displays an image.

Code

#+MACRO: image \includegraphics{$1}

Parameters

1. Path to image file.

Examples

{{{image}}}

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.

Examples

{{{version-history}}}

Layout

Collapse macro

The collapse macro inserts of collapsed block of text.

Code

Parameters

None.

Examples

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

Info macro

The info macro is useful for including helpful information.

Code

#+MACRO: begin_info @@html:<div class="info"><p>@@
#+MACRO: end_info @@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: BeginMiniPage @<div style="border:1px solid #aaaaaa;padding:10px;width:780px;margin-left:auto;margin-right:auto;">
#+MACRO: EndMiniPage @</div>

Parameters

Examples

Note macro

Code

#+MACRO: begin_note @@html:<div class="note"><p>@@
#+MACRO: end_note @@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 @@html:<div class="panel"><p>@@
#+MACRO: end_panel @@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 @@html:<div class="tip"><p>@@
#+MACRO: end_tip @@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 @@html:<div class="warning"><p>@@
#+MACRO: end_warning @@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.

Navigation and lists

FIXME Problem with the tab title.

Toc macro

Insert a table of contents.

Code

#+MACRO: toc #+toc: headlines $1

Parameters

1. Number of headline levels.

Remarks

The toc macro can’t be inlined in text.

Examples

Insert the TOC here, with one headline level:

{{{toc(1)}}}

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

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

Copyright (C) 2014-2022 Fabrice Niessen

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