Custom Wiki macros¶

Redmine Wiki macros, as a feature, were implemented to make extending the Wiki syntax for Redmine developers easier. Most Wiki syntax rules just replace the simpler text with the “richer” text formatted with HTML (i.e., do no calculations and do not depend on server data). So, in fact most such extensions could be defined on the customer (administrator) side without the need to write any Ruby code¹.

That’s the approach WikiNG implements in its custom Wiki macros – it uses the Redmine macro syntax as the interface for defining custom Wiki extensions and allows Redmine administrators to define the behaviour of custom macros... This means, that with WikiNG administrators can create any number of custom macros using just the Web interface (administration area).

Thus, the plugin adds new “Custom Wiki macros” menu to Administration:

WikiNG does not come with any default custom macros! You need to add them on your own using the “New macro” link.

In the macro form you need to specify:

• The name of the macro
  This name will be used in the macro syntax as: {{name(...)}}.
• The description of the macro
  The description is to be shown in the macro list (which is produced by the built-in {{macro_list}} macro).
  You can use the Wiki formatting for this description.
• The body of the macro
  This is the HTML code the macro definition in the Wiki page is to be replaced with. This code can (and should to be useful) contain “variables” (see below)...

The Redmine macro syntax looks like:

{{macro_name(argument, named_argument=value, ...)
Long multi-line text as a special argument...
}}

Each macro argument becomes available as a variable for the custom macro:

• Named arguments are available as %{name}.
• Unnamed arguments are accessible under their position number in the argument list as %[1] (where 1 is for the first argument).
• And the macro text is available as %(*).

Check sample custom macros on the forum (there is a sample for YouTube there). Consider also sharing your custom macros there (see Guidelines).