Documenting Macros

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):

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