WikiNG plugin for Redmine¶

The WikiNG plugin for Redmine is aimed to extend Redmine Wiki syntax by making it more developer-ready, more emotional and social...

Syntax extensions¶

The WikiNG plugin adds the following extensions:

• New links:
  • user#<id> or user:<login> (+ @<login> since 1.1.0) → Andriy Lesyuk
  • file#<id> or file:<filename> → wiking-0.0.2.tar.bz2
  • [[wikipedia>Resource]] or [[wikipedia[lang]>Resource]] → Ruby
  • [[google>Search string]] → Redmine WikiNG plugin
  • [[redmine>Resource]] or [[redmine>#<issue>]] → #4179
• New blocks:
  • <warning> ... </warning> or warning. ...
  • <notice> ... </notice> or notice. ...
  • <tip> ... </tip> or tip. ...
• New footnote syntax:
  • Now footnotes can be written inline with double parentheses¹: ((...))
• Smileys:
  • :), =), :D, =D, :'(, :(, ;), :P, :O, :/, :S, :|, :X, :*, O:), >:), B), (!), (?), (v), (x) and @}->-
    , , , , , , , , , , , , , , , , , , , , and
• Special characters:
  • <-, <->, ->, <=, <=>, =>, -- and ---
    ←, ↔, →, ⇐, ⇔, ⇒, – and —
• Markers:
  • {TODO} →
  • {UPDATE} →
  • {FIXME} →
  • {NEW} →
  • {FREE} →
  • {BETA} →
  • {EXPERIMENTAL} →
• CSS classes:
  • shadow → drops shadow for images, e.g., !(wiking shadow).image.png!
  • mac-shadow → drops the Mac-style shadow for images, e.g., !(wiking mac-shadow).image.png!
  • pressed → embosses code blocks, e.g., <pre class="wiking pressed">...</pre>
  • button → renders a link as a button, e.g., "(wiking button)anchor":link
  • small → makes font slightly smaller, e.g., %(wiking small)small text% or p(wiking small). small paragraph
• Macros:
  • User-defined macros (see below)
    
    Macros {{version}} and {{date}} are not compatible with formatted text caching.
  • Conditional macro: {{date >= YYYY-MM-DD}} ... {{date}}
  • Conditional macro: {{version < x.x.x}} ... {{version}}
  • Macro for creating and calling custom hook: {{wiking_hook(<name>)}}

Check this page for more detailed syntax. To experiment with the syntax use the playground.

User-defined macros¶

Redmine supports the macro concept, the main idea of which is to allow adding custom macros by plugins. But, WikiNG uses it in a different way – it allows adding custom macros through the Web interface! This means, that now custom macros can be added not only by developers in their plugins, but also by administrators.

For adding custom macros WikiNG adds the new “Custom Wiki macros” menu to Administration:

For details about custom macros check this page.

Consider sharing you custom macros with the community using the forum (check Guidelines).

Mentions¶

In addition to just rendering links to user profiles since 1.0.0b of the plugin user links also produce mentions. Mentions, like activities, get listed in the user profile (to accommodate both the plugin adds the tabbed menu there). In this list a mention is a Redmine object, that contains link(s) to the user.

Each user link (and, therefore, mention) also generates the email notification (if the administrator and the mentioned user have configured Redmine accordingly). This way the mentioned user gets notified about the mention by email!

To make sure, that mentions will be emailed to mentioned users...

The administrator needs to:

• Configure Email notifications as described here.
• Enable the User mentioned action in Administration → Settings → Email notifications.

Users need to:

• Set the Email notifications option in their profiles to “For any event on all my projects”, “Only for things I watch or I’m involved in” or “Only for things I am the owner of”.

In user links you need to use the user’s numeric identifier or login name. These data are to be determined from user profile URLs, what makes usage of this feature slightly troublesome. Therefore, to help here since 1.1.0 WikiNG supports user mentions autocompletion – you type a few characters and the plugin suggests users with these characters in identifier, login, first or last name.

Adding support for mentions in third-party plugins¶

The mentioning and notification works due to the special event and mention API implemented for main Redmine objects, that support Wiki formatted text (e.g., Wiki pages, issues). In other words, similar objects in third-party plugins may fail to appear in mentions of users and to notify mentioned users.

So, you (or the author) may need to modify third-party plugins to let their objects be “mentionable”... Check this page on how to do this.

Install¶

To install the plugin do:

• Copy wiking directory to #{RAILS_ROOT}/plugins
• Run: rake redmine:plugins:migrate RAILS_ENV=production
• Restart Redmine

Contributing¶

You can contribute to the plugin by sharing your theme, if you have created one, or by improving icons/pictures, that are used for, e.g., markers.

You can also share your custom macros on the forum (see Guidelines).

Similar plugins¶

• Wiki Notes by Daniel Seifert
• Wiki Extensions by r-labs
• Redmine Mentions by Arkhitech