Skip to content
Shared macros for Org mode
Find file
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
images
README.html
README.org
org-macros.setup

README.org

Org Macros

:license-gpl-blue.svg btn_donate_LG.gif

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 git@github.com:fniessen/org-macros.git

Installation

#+INCLUDE: /path/to/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

Basic formatting

Advanced

Generic macros

Layout

Navigation and lists

  • children macro (to display child pages)
  • toc macro

Dev tools


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


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


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

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

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


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, This information is important.)}}} {{{highlight(#E0E0E0, This other isn’t.)}}}

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


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


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:\\@@ @@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:</kdb>@@

See menukeys for LaTeX.

Parameters

  1. Text to markup.

Examples

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

Advanced

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

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

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.

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


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 like the org-macros project, you can show your appreciation and help support future development by making today a donation through PayPal.

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

License

Copyright (C) 2014-2015 Free Software Foundation, Inc.

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

:license-gpl-blue.svg btn_donate_LG.gif
Something went wrong with that request. Please try again.