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:

Write a help file
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).

Documenting Macros

Writing the Help File

Configuring the help file in your macro

Labels

Comments (3)

Jason Dillon says:

Matt Ryall (Atlassian) says:

Olivier Dagenais says: