About - Doxia :: Include Macro ( Maven Site Plugin )

This project extends Maven Doxia with a macro offering an advanced way of including static or dynamic content into generated technical sites & documents that are built within the Maven ecosystem.

Include Macro for Maven2 & 3 :: Doxia starts where the standard Snippet macro ends. It combines features like standard file & snippet inclusion, source code highlighting and dynamic content creation without adding additional dependencies like requiring custom site skins or modifications to the standard site templates.

At a glance "Include Macro" allows to:

  • Include arbitrary content into generated documentation, similar to the snippet macro but with enhanced path and snippet selection.
  • Highlight code, rendered to pure HTML + CSS (no client-side JavaScript nor public internet is required).
  • Include & interpret "Velocity Templates" combined with properties (dynamic content creation).
  • Invoke "Custom Java Classes" or Scripts that provide properties to templates or create the content to include directly.

Maven :: Doxia is used by the maven-site-plugin to build project sites within a Maven project. The Macro defined by this extension can be used as soon as it was registered within your own project's pom.xml (Maven - Project Object Model).

See Usage & Parameter Reference for an overview how the Macro can be used in own projects.

Quick Examples

Inclusion with Syntax Highlighting

Example

%{include|source=samples/HelloWorld.java}
1
2
3
4
5
6
7
8
9
/**
 * Hello World Class
 */
public class HelloWorld {
    @Override
    public String toString() {
        return "Hello World";
    }
}

Notes

Bundled highlighting schemes (brushes) include support for: Java, JavaFX, JavaScript, JSP, Groovy, GSP, XML/XHTML, SQL, Bash, Batch, Flex/AS3 and more.

Behind the scenes, syntax highlighting is implemented using a well known javascript library (SyntaxHighlighter) that runs on Rhino during a build. This results in good support for highlighting schemes in combination with no requirement for client side javascript.

Advanced Snippet Selection

AOP like Expressions

%{include|source=samples.HelloWorld|snippet=AJ:..toString()}
5
6
7
8
@Override
public String toString() {
    return "Hello World";
}

XPath Expressions

%{include|source=pom.xml|snippet=XP://license}
213
214
215
216
217
<license>
    <name>The Apache Software License, Version 2.0</name>
    <url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
    <distribution>repo</distribution>
</license>

Snippet Selection using Expressions

Among other options, snippets can be selected using AOP-like, XPath and Regular expressions as well as the traditional snippet IDs (similar to snippet macro).

Examples:
  • Include snippet by ID: 'snippet=#SnippetId'
  • Exclude all snippet id definitions: 'snippet=!snippet-ids'
  • Include by ID, exclude any definitions: 'snippet=#SnippetId, !snippet-ids'
  • 'grep' like syntax: 'snippet=grep:Token,!grep:NotToken'
  • 'Regular Expression' syntax: 'snippet=re:([0-9,.;\s]+)$' (all lines ending with numeric expressions)
  • 'XPath' syntax: 'snippet=xp:/html/head/title'
  • 'AOP'-like syntax: 'snippet=aj:..InnerClass, !aj:..toString()'
  • 'Token & Brace' syntax: 'snippet=tb:"json-key"{, !tb:"inner-array"['
  • Line range: 'snippet=lines:50-100'

Templates & Dynamic Content

Example Template 'hello-world.jsp.vm':

1
2
3
4
5
6
<%@ page contentType="text/html;charset=UTF-8"%>
<html>
    <body>
        <h1><% out.println("${title}"); %></h1>
    </body>
</html>
%{include|source=samples/hello-world.jsp.vm|title=Hello World 2}
1
2
3
4
5
6
<%@ page contentType="text/html;charset=UTF-8"%>
<html>
    <body>
        <h1><% out.println("Hello World 2"); %></h1>
    </body>
</html>

Notes

Any source that ends with the file extension ".vm" is considered a velocity template and processed before any inclusion and snippet extraction is applied (w. or wo. highlighting of the final results).

All call-time parameters that were specified with the Macro call are available inside the velocity template using ${paramName}.

In addition when using a source-class, dynamic content can be made available to the template which is excessively used in the bundled templates and extensions. See reference for more details on using templates and look after bundled extensions to see how this feature can be used.