Overview of the Doxia framework

Doxia turns documents into other documents. A parser reads a source document and reports what it finds, a heading, a paragraph, a table cell, as a stream of events. A sink receives those events and writes them in its own output format. Any parser can feed any sink, so adding a format means writing one parser or one sink, not one converter per pair of formats.

The following figure shows the main components.

Doxia Framework

Doxia components are JSR-330 components, managed by Eclipse Sisu just like Maven's own.

Sink API

The Sink interface describes a document as a sequence of events. A method such as paragraph() opens an element, and the same name with a trailing underscore, paragraph_(), closes it:

sink.paragraph();
sink.text("my text");
sink.paragraph_();

The HTML sink writes this as:

<p>my text</p>

Maven report plugins use the Sink API directly to write their pages. See Using the Doxia Sink API and the Sink Javadoc.

Doxia Core

Doxia Core holds the parser API and the shared implementations. The central method of the Parser interface is:

void parse(Reader source, Sink sink) throws ParseException;

A ParseException carries the line and column where parsing failed, through getLineNumber() and getColumnNumber().

AbstractParser is the base class for parsers. It runs macros, which insert generated content such as a table of contents while a document is parsed. See the Doxia Macros Guide.

A ParserModule tells the site renderer which source directory and file extensions belong to a parser, for example src/site/markdown and .md for the Markdown parser.

Doxia Modules

A Doxia module implements one markup format. It provides a Parser, usually by extending AbstractParser, and a ParserModule. Most modules also provide a Sink and a SinkFactory, so they can write the format as well as read it. The format references list which modules can do what, and Create a Doxia Module shows how to write one.

Doxia Site Tools

Doxia Sitetools builds a whole site from single documents. The site renderer, used by the Maven Site Plugin, parses every source document with the matching module, writes it through the HTML sink, and decorates the result with a skin, using Apache Velocity templates. The site model describes the menus, breadcrumbs and other decoration set in site.xml.