This page last changed on May 12, 2005 by jnolen.

The Confluence notation guide is the popup window that describes all the markup and macros available within a Confluence installation. Obviously, if a macro is installed, you will want it to also appear in the notation guide.

To do this you will need to:

  1. Write a help file
  2. Tell Confluence where to find that help file

Writing the Help File

The help file is a file containing a fragment of HTML. Your HTML will be inserted into a two-columned table, so you should provide a single table row with two columns. On the left-hand side, put usage examples of your macro. On the right hand side provide a description and sample output.

The file will be rendered through Velocity, which means useful things like $req.contextPath are available to you.

Here's an example of the help file used for the {note} macro:

<tr bgcolor=ffffff>
  <!-- The left-hand table cell should contain usage examples -->
  <td>
    {note:title=Be Careful}<br />
    The body of the note here..<br />
    {note}
  </td>

  <!-- The right-hand cell describes the macro and its available arguments -->
  <!-- and may include sample output -->
  <td>
    <p>
      Prints a simple note to the user.

    <!-- Provide a list of all possible macro arguments -->
    <ul>
      <li><b>title:</b> - (optional) the title of the note.</li>
      <li><b>icon:</b> - (optional) if "false", don't display the icon.</li>
    </ul>
    </p>

    <!-- This is the sample output -->
    <div align='center'><div class='informationMacroPadding'>
    <table cellpadding='5' width='85%' cellspacing='0' class='noteMacro' border='0'>
    <tr><td width='16' valign='top'>
    <img src="$req.contextPath/images/icons/emoticons/warning.png" width="16" 
     height="16" align="absmiddle" alt="" border="0"></td><td>
     <b class="strong">Be Careful</b><br /><br/>
     The body of the note here.. $req.contextPath/images/icons/emoticons/warning.png
     </td></tr></table></div></div>
    </td>
</tr>

Configuring the help file in your macro

The help file is included in your macro as a plugin resource of type "velocity" and name "help". Here's the plugin definition of the note macro, including its help file:

<macro name='note' class='com.atlassian.confluence.extra.information.NoteMacro' key='note'>
    <description>Draws a note (yellow).</description>
    <resource type="velocity" name="help" location="templates/extra/layout/notemacro-help.vm">
        <param name="help-section" value="advanced"/>
    </resource>
</macro>

The "help-section" parameter is optional, and determines which section of the notation guide the macro will be documented in. The following sections are available (Note that regular wiki markup is also defined in here, so some sections like 'breaks' are unlikely to be appropriate for any real macro):

texteffects Macros that change the appearance of text contained within them (e.g. {color})
headings Macros that create headings within a page
breaks Macros related to line- or paragraph breaks, or rulers
links Macros related to links to other wiki or external content (e.g. {anchor})
lists Macros related to lists
images Macros for inserting or manipulating images within a page (e.g. {gallery})
tables Macros for forming static tables (e.g. {section} and {column})
advanced Macros for creating more complex structures in a page (e.g. {panel} or {info})
confluence Macros for manipulating or displaying Confluence data (e.g. {children})
external Macros for manipulating or displaying data from other systems (e.g. {rss})
misc Macros that do anything else (Try to avoid using this section)

If you don't provide a help section, your macro documentation will appear in the "Macros" section of the notation guide. (This section only appears in the notation guide if it is needed).

Why does <pre>...</pre> cause the text block to be indented in the help display? It would be nice to be able to:

<tr bgcolor=ffffff>
  <!-- The left-hand table cell should contain usage examples -->
  <td>
<pre>
{note:title=Be Careful}
The body of the note here..
{note}
{/pre>
  </td>
...

Would be even nicer to be able to use Confluence markup

Posted by jason.dillon@paybytouch.com at Jan 25, 2006 18:51

The help page currently uses the same stylesheet as Confluence does so that fonts, tables, etc. will look consistent.

If you don't need the left margin on your pre tag, you could fix this with an inline style:

<pre style="margin-left: 0">
{note:title=Be Careful}
The body of the note here..
{note}
</pre>

Using Confluence markup sounds like a nice suggestion, but I'm not sure it would support all the necessary content. If you raise it on http://jira.atlassian.com, we can investigate this for a future release.

Posted by mryall at Feb 02, 2006 17:04

I second the using Confluence markup suggestion.

Posted by olivier_dagenais@canada.com at Mar 06, 2006 16:36
Document generated by Confluence on Mar 22, 2007 21:00