I'm looking for a part-time remote job.

Hire me

I'm the author of:

Mastering Redmine is a comprehensive guide with tips, tricks and best practices, and an easy-to-learn structure.

Check the book's project or

Buy the book

Social pages of the book:

By buying this book you also donate to Redmine (see this page).

Follow me:

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

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.

Macro form

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 %(*).
Be careful when using user-supplied variables! Check this page for some tips.

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

Let your users know, which Wiki macros are available for them under your Redmine installation, by putting the (built-in) {{macro_list}} macro on some help Wiki page and sharing it with them.

1 Redmine is written and, therefore, can be extended with Ruby

NewMacro.png - Macro form (42.4 KB) Andriy Lesyuk, 22 May 2014 09:04

Terms of use | Privacy policy