Doxia Macros Guide

The Doxia Core includes macro mechanisms to facilitate the documentation writing.

Macros are currently only supported for APT, Xdoc and FML formats. Starting with Doxia 1.7 (maven-site-plugin 3.5), macros are also supported for XHTML and Markdown. Macros are not (and probably will never be) supported by Confluence, Docbook and Twiki modules.

A macro in an APT source file is a non-indented line that looks like this:

%{macro_name|param1=value1|param2=value2|...}

An Xdoc or FML macro has the following syntax:

<macro name="macro_name">
  <param name="param1" value="value1"/>
  <param name="param2" value="value2"/>
  ...
</macro>

Since Doxia 1.7, an XHTML or Markdown macro has the following syntax:

<!-- MACRO{macro_name|param1=value1|param2=value2|...} -->

As of Doxia 1.7, the following macros are available:

Echo Macro

The Echo macro is a very simple macro: it prints out the key and value of any supplied parameters. For instance, in an APT file, you could write:

%{echo|param1=value1|param2=value2}

Similarly, it will be for xdoc file:

<macro name="echo">
  <param name="param1" value="value1"/>
  <param name="param2" value="value2"/>
</macro>

and it will output

  param1 ---> value1
  param2 ---> value2

Snippet Macro

The Snippet macro is a very useful macro: it prints out the content of a file or a URL. For instance, in an APT file, you could write:

%{snippet|id=myid|url=http://myserver/path/to/file.txt}

In a xdoc file, it will be:

<macro name="snippet">
  <param name="id" value="myid"/>
  <param name="url" value="http://myserver/path/to/file.txt"/>
</macro>

The id parameter is not required if you want to include the entire file. If you want to include only a part of a file, you should add start and end demarcators: any line (typically a comment) that contains the strings "START", "SNIPPET" and "myid" (where myid is the id of the snippet) is a start demarcator, and similarly "END SNIPPET myid" denotes the end of the snippet to include. For example:

  • Start and end snippets in a Java file
    public class MyClass
    {
        // START SNIPPET: myid
        public static void main( String[] args ) throws Exception
        {
            ...
        }
        // END SNIPPET: myid
    }
  • Start and end snippets in a XML file
    <project>
    ...
      <build>
        <plugins>
    <!-- START SNIPPET: myid -->
          <plugin>
            ...
          </plugin>
    <!-- END SNIPPET: myid -->
        </plugins>
      </build>
    </project>
Parameter Description
id The id of the snippet to include. If omitted the whole file/url will be included (since Doxia 1.1).
url The path of the URL to include.
file The path of the file to include (since doxia-1.0-alpha-9).
verbatim If the content should be output as verbatim escaped text. If this is set to false then the content of the snippet will not be escaped. This means that you can use it like Server-Side Includes on a webserver. Default value is true.
encoding The encoding of the file to read (since Doxia 1.6). If omitted the default JVM encoding will be used.

TOC Macro

The TOC macro prints a Table Of Content of a document. It is useful if you have several sections and subsections in your document. For instance, in an APT file, you could write:

%{toc|section=2|fromDepth=2|toDepth=3}

This displays a TOC for the second section in the document, including all subsections (depth 2) and sub-subsections (depth 3).

Note that in Doxia, apt section titles are not implicit anchors (see Enhancements to the APT format), so you need to insert explicit anchors for links to work!

In a xdoc file, it will be:

<macro name="toc">
  <param name="section" value="2"/>
  <param name="fromDepth" value="0"/>
  <param name="toDepth" value="4"/>
</macro>
Parameter Description
section Display a TOC for the specified section only, or all sections if 0. Positive int, not mandatory, 0 by default.
fromDepth Minimum section depth to include in the TOC (sections are depth 1, sub-sections depth 2, etc.). Positive int, not mandatory, 0 by default.
toDepth Maximum section depth to include in the TOC. Positive int, not mandatory, 5 by default.

From Doxia 1.1.1 on you may also specify any of the html base attributes (i.e. any of id, class, style, lang, title) as parameters, e.g.:

%{toc|class=myTOC}

This can be used for styling the TOC via css.

SWF Macro

The Swf macro prints Shockwave Flash assets in the documentation. For instance, in an APT file, you could write:

%{swf|src=swf/myfile.swf|id=MyMovie|width=600|height=200}

In a xdoc file, it will be:

<macro name="swf">
  <param name="src" value="swf/myfile.swf"/>
  <param name="id" value="MyMovie"/>
  <param name="width" value="600"/>
  <param name="height" value="200"/>
</macro>
Parameter Description
src Specifies the location (URL) of the movie to be loaded.
id Identifies the Flash movie to the host environment (a web browser, for example) so that it can be referenced using a scripting language.
width Specifies the width of the movie in either pixels or percentage of browser window.
height Specifies the height of the movie in either pixels or percentage of browser window.
quality Possible values: low, high, autolow, autohigh, best.
menu True displays the full menu, allowing the user a variety of options to enhance or control playback. False displays a menu that contains only the Settings option and the About Flash option.
loop Possible values: true, false. Specifies whether the movie repeats indefinitely or stops when it reaches the last frame. The default value is true if this attribute is omitted.
play Possible values: true, false. Specifies whether the movie begins playing immediately on loading in the browser. The default value is true if this attribute is omitted.
version Specifies the width of the movie in either pixels or percentage of browser window.
allowScript Specifies the width of the movie in either pixels or percentage of browser window.

For more information, see the SWF Macro page.

SSI Macro

Since Doxia 1.7, the SSI macro prints a server side include. For instance, in an APT file, you could write:

%{ssi|function=include|file=included-file.html}

In a xdoc file, it will be:

<macro name="ssi">
  <param name="function" value="include"/>
  <param name="file" value="included-file.html"/>
</macro>
Parameter Description
function The SSI function to insert.
any Parameter that will be added to the SSI directive.