Doxia Developers Centre

This documentation centre is for those that are developing Doxia modules or macro.

Create a New Doxia Module

First, you need to create a POM with doxia-modules as parent:

<project>
  <parent>
    <groupId>org.apache.maven.doxia</groupId>
    <artifactId>doxia-modules</artifactId>
    <version>1.0</version> <!-- Latest release -->
  </parent>
  <modelVersion>4.0.0</modelVersion>
  <artifactId>doxia-module-my</artifactId>
  <name>Doxia :: MY Module</name>

  ...
</project>

Secondly, you should implement some Doxia classes:

  • MyParser class
    import org.apache.maven.doxia.parser.AbstractParser;

/**
 * @plexus.component role="org.apache.maven.doxia.parser.Parser" role-hint="my"
 */
public class MyParser
    extends AbstractParser
{
...
}
  • MyParseException class
    import org.apache.maven.doxia.parser.ParseException;

public class MyParseException
    extends ParseException
{
...
}
  • MySiteModule class
    import org.apache.maven.doxia.module.site.AbstractSiteModule;

/**
 * @plexus.component role="org.apache.maven.doxia.module.site.SiteModule" role-hint="my"
 */
public class MySiteModule
    extends AbstractSiteModule
{
...
}
  • MySink class
    import org.apache.maven.doxia.sink.SinkAdapter;

/**
 * @plexus.component
 */
public class MySink
    extends SinkAdapter
{
...
}

Create a New Doxia Macro

You need to add the following plugin configuration to generate the correct Plexus component.xml file for the project containing your macro:

<project>
  ...
  <build>
    ...
    <plugins>
      <plugin>
        <groupId>org.codehaus.plexus</groupId>
        <artifactId>plexus-maven-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>descriptor</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
      ...
    </plugins>
  ...
  </build>
  ...
</project>

You should implement the AbstractMacro class:

import org.apache.maven.doxia.macro.AbstractMacro;

/**
 * @plexus.component role="org.apache.maven.doxia.macro.Macro" role-hint="my"
 */
public class MyMacro
    extends AbstractMacro
{
...
    public void execute( Sink sink, MacroRequest request )
        throws MacroExecutionException
    {
        String myValue = (String) request.getParameter( "myParam" );
...
    }
...
}

To use it, you need to write the following markups:

  • APT
    %{my|myParam=myValue} <!-- my is the macro name defined by role-hint -->
  • XDoc
    <macro name="my"> <!-- my is the required macro name defined by role-hint -->
  <param name="myParam" value="myValue"/>
</macro>

References