Doxia Macros Guide

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

Macros are supported by the APT, Xdoc, FML, XHTML and Markdown formats.

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

The following macros are available:

Echo Macro
Snippet Macro
TOC Macro
Removed Macros

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 when a site is rendered, Doxia anchors each section title for you, so the entries this macro emits resolve without further work. Define an anchor explicitly (see Enhancements to the APT format) where a link has to survive the title being reworded.

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.

Removed Macros

The SWF macro, which embedded Shockwave Flash assets, and the SSI macro, which emitted a server side include, were both removed in Doxia 2.0. A document that still invokes either one fails to render.