It's better when it's simple

User Tools

Site Tools


Macros Plugin

Compatible with DokuWiki

  • 2022-07-31 "Igor" unknown
  • 2020-07-29 "Hogfather" unknown
  • 2018-04-22 "Greebo" yes
  • 2017-02-19 "Frusterick Manners" unknown

plugin Use macro expressions and conditional expressions to generate page text

Last updated on
Syntax, Action

This extension is marked as obsoleted. Therefore it is hidden in the Extension Manager and the extension listing. Furthermore, it is candidate for removal.

Similar to easyvar, fields, kixovar, replace, textinsert

Tagged with !obsolete, extension, formatting, macro

Download and Installation

Since the repository has been removed, a workaround is to download of the plugin
MD5-check 1d28e5fdb7feb05aae44820169bdbe36

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.


This plugin allows you to define custom macros that can be used to generate page text. It also processes simple conditional expressions, removes block comments and allows escaping of literal characters (those are useful features when using macros).

Syntax and Usage

Block Comments

Any text between block comment markers is simply removed:

{{## comment ##}}

Escaped Characters

A character that is preceded by a backtick ` will be rendered as a literal character. That allows use of characters that otherwise would be interpreted as markup characters:

`{`{ literal braces `}`}

Double that to render a backtick:



The format of a macro definition is:


where name is the macro identifier and definition is the macro text. The definition may contain placeholders @0, @1, … @9 for up to ten macro arguments.

Macros are used (expanded) by:

$name            (without specified arguments - equal to an empty argument list)
$name[]          (with an empty argument list)
$name[arg]       (with one argument)
$name[arg1|arg2] (with two arguments, etc.)

An example:

{{$format=**@0** @1 //@2//$}}

Produces this text: bold and italics


The plugin processes two types of conditional expressions:


expands to T if cond is not an empty string, otherwise expands to F

$?[a|b]          (shortcut for $??[a|a|b])

expands to a if a is not an empty string, otherwise expands to b


Vanishing PHP text

Unfortunately, the Macros plugin simply removes undefined macros. This clobbers PHP code, because PHP variables look a lot like macros.

There is an easy fix: in macros.php, function expand_macro_callback(), change the following code to return the original match instead of an empty string:

// a defined macro?
$res = @$this->macroDefs[$name];
if(!$res) {
	$this->undefinedMacros[] = $name;
	return $m[0];
	// return '';

Also, the macro identifying character $ can be changed to another character or a sequence of characters. In macros.php, search for and replace \$ in regular expressions.

Bug Report

1. Macros affect verbatim environments

Macro definitions go through all environments (<nowiki>, <code>, %%, <file>) and this is not only a problem (it's impossible to present the macro syntax when it is installed) but also dangerous, because it manipulates source codes which are presented on the wiki.

Any solution for that? — mubed 2012/05/24 17:32

2. Edit button disappeared

The “edit” button for page sections disappear after installing the macros plugin.

:!: one idea is to disable global $conf; $conf['maxseclevel'] = 0; in action.php »>

The author says: The plugin definitely would benefit from better integration. It was created as a quick port of a module from my own experiments with another wiki.

If a macro is processed, that changes the length of a section text. It may even generate new sections! I could not find how to make dokuwiki adjust the sections (and positions of edit buttons) properly, therefore I decided to disable the section buttons, when a macro is involved in generating page text. Like so, although this is an ugly hack, I think:

  if ($data != $event->data) {
  // disable section edit if any change took place
    global $conf; $conf['maxseclevel'] = 0;
    $event->data = $data;

If anyone, who knows well how dokuwiki environments work, could improve the plugin integration, it would be most appreciated!

And what about this one? Any better idea? — mubed 2012/05/24 17:32

I have started a thread form regarding this: — Cristian 2012/11/22

Feature Requests

add autolink2 compatibility

The plugin autolink2 substitutes defined words with corresponding internal page links.
Unfortunately the replacements through macros are not substituted.
Is there any way to change that? It will be great! Joachim 2011-11-05

seems to be working

This code, run by the latest version of the plugin, with Cristian's changes, properly links “some name” 6 times. (I do not think that the changes made it to do so - perhaps some update in the DokuWiki core?)

{{$SN=@0ome @1ame$}}

The text on the page. Blah, blah, blah...

And of course the text Some Name. Also some name is valid, as well as SOME NAME.
|The test can be in a table also| Some Name, **but** there needs to be a space after the leading`|| through a macro: $SN[S|N] |



Ian 2012-03-05

New Feature Added

Thanks to Cristian Spiescu for submitting a patch which now has been rolled into the plugin.

It is possible to specify a “global include” page (as namespace:page) in Configuration Manager/Macros Plugin Setting. Macro definitions from that page become available in the whole wiki.

plugin/macros.txt · Last modified: 2018-12-28 18:16 by Dr-Yukon

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki