This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git
The following commit(s) were added to refs/heads/master by this push:
new 6ca52153 Refresh the Doxia entry pages for Doxia 2
6ca52153 is described below
commit 6ca521534e3dc17519fcfed31771cacca6fb92d3
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Tue Nov 17 21:18:27 2026 +0000
Refresh the Doxia entry pages for Doxia 2
The figure and APT link gotchas describe what Doxia 2 does today: figures
render as <figure>, and an APT link without ./ silently becomes a same-page
anchor with no log message. The FAQ no longer claims an XSD cache in
java.io.tmpdir; the cache is in memory and the Xdoc and FML schemas ship in
doxia-core.
---
content/markdown/doxia/developers/index.md | 12 ++--
.../doxia/{downloads.md => downloads.md.vm} | 19 +++++-
content/markdown/doxia/faq.md | 41 ++++---------
content/markdown/doxia/index.md.vm | 66 ++++++++++++++------
content/markdown/doxia/issues/index.md | 61 ++++++++-----------
content/markdown/doxia/modules/index.md | 65 +++++++++++---------
content/markdown/doxia/overview.md | 71 ++++++++++++----------
content/markdown/doxia/references/index.md | 2 +-
content/markdown/doxia/resources.md | 22 ++++---
9 files changed, 200 insertions(+), 159 deletions(-)
diff --git a/content/markdown/doxia/developers/index.md
b/content/markdown/doxia/developers/index.md
index 110ba473..ae8cf181 100644
--- a/content/markdown/doxia/developers/index.md
+++ b/content/markdown/doxia/developers/index.md
@@ -24,12 +24,14 @@ specific language governing permissions and limitations
under the License.
-->
+
# Doxia Developers Centre
-This documentation centre is for those that are developing Doxia modules or
macro.
+These pages are for developers who write Maven reports or extend Doxia with
new formats or macros.
-Currently you can find information on the following topics:
+- [Using the Doxia Sink API](./sink.html): write report pages and convert
documents between formats.
+- [Creating Doxia Macros](./macros.html): add a macro that generates content
while a page is parsed.
+- [Creating Doxia Modules](./modules.html): add a parser or sink for a new
markup format.
-- [Creating Doxia Modules](./modules.html)
-- [Creating Doxia Macros](./macros.html)
-- [Using the Doxia Sink API](./sink.html)
+The [Overview](../overview.html) explains how parsers, sinks and the site
renderer fit together, and the
+[Doxia Javadoc](../doxia/apidocs/) documents the API.
diff --git a/content/markdown/doxia/downloads.md
b/content/markdown/doxia/downloads.md.vm
similarity index 52%
rename from content/markdown/doxia/downloads.md
rename to content/markdown/doxia/downloads.md.vm
index 101150ec..5606b297 100644
--- a/content/markdown/doxia/downloads.md
+++ b/content/markdown/doxia/downloads.md.vm
@@ -24,8 +24,23 @@ specific language governing permissions and limitations
under the License.
-->
+
# Maven Doxia Releases
-Releases of Maven Doxia are made available in both binary and source
distributions. Individual JARs are also made available through Apache Maven
repositories.
+Doxia is published to Maven Central under the
+[`org.apache.maven.doxia`](https://central.sonatype.com/namespace/org.apache.maven.doxia)
group ID. To write a Maven
+site you don't need to download anything: the Maven Site Plugin brings Doxia
with it.
+
+To use Doxia in your own code, add the modules you need as dependencies, for
example:
+
+```xml
+<dependency>
+ <groupId>org.apache.maven.doxia</groupId>
+ <artifactId>doxia-module-markdown</artifactId>
+ <version>${doxiaVersion}</version>
+</dependency>
+```
-Releases of all Doxia sub-project components (currently Doxia, Doxia Sitetools
and Doxia Tools) may be downloaded from Maven Central in the usual way.
+Source releases of each component, with their signatures, are listed on the
download page of the component:
+[Doxia](./doxia/download.html), [Doxia
Sitetools](./doxia-sitetools/download.html) and
+[Doxia Converter](./doxia-tools/doxia-converter/download.html).
diff --git a/content/markdown/doxia/faq.md b/content/markdown/doxia/faq.md
index 7f871774..676eeb4c 100644
--- a/content/markdown/doxia/faq.md
+++ b/content/markdown/doxia/faq.md
@@ -35,8 +35,8 @@ under the License.
### How to handle style in the APT markup language?
-APT does not support style. If you need more control you should use
-[xdoc](references/xdoc-format.html) instead.
+APT does not support style. If you need more control, write the page in
+[Markdown](references/markdown-format.html), which accepts inline HTML, or in
[Xdoc](references/xdoc-format.html).
<a id="How_to_export_in_PDF"></a>
@@ -69,21 +69,15 @@ Xdoc XSD 2.0
FML XSD 1.0.1
: [https://maven.apache.org/xsd/fml-1.0.1.xsd](/xsd/fml-1.0.1.xsd)
-Book XSD 1.0
-: [https://maven.apache.org/xsd/book-1.0.0.xsd](/xsd/book-1.0.0.xsd)
-
-Document XSD 1.0.1
-: [https://maven.apache.org/xsd/document-1.0.1.xsd](/xsd/document-1.0.1.xsd)
-
Site XSD 2.1.0
: [https://maven.apache.org/xsd/site-2.1.0.xsd](/xsd/site-2.1.0.xsd)
-Your favorite IDE probably supports XSD schema's for Xdoc and FML files. You
need to specify the following:
+Most IDEs validate and complete Xdoc and FML files once the root element
declares the schema:
```xml
<document xmlns="http://maven.apache.org/XDOC/2.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
http://maven.apache.org/xsd/xdoc-2.0.xsd">
+ xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd">
...
</document>
```
@@ -91,28 +85,11 @@ Your favorite IDE probably supports XSD schema's for Xdoc
and FML files. You nee
```xml
<faqs xmlns="http://maven.apache.org/FML/1.0.1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/FML/1.0.1
http://maven.apache.org/xsd/fml-1.0.1.xsd">
+ xsi:schemaLocation="http://maven.apache.org/FML/1.0.1
https://maven.apache.org/xsd/fml-1.0.1.xsd">
...
</faqs>
```
-```xml
-<book xmlns="http://maven.apache.org/BOOK/1.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/BOOK/1.0.0
http://maven.apache.org/xsd/book-1.0.0.xsd">
- ...
-</book>
-```
-
-```xml
-<document xmlns="http://maven.apache.org/DOCUMENT/1.0.1"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/DOCUMENT/1.0.1
http://maven.apache.org/xsd/document-1.0.1.xsd"
- outputName="...">
- ...
-</document>
-```
-
```xml
<site xmlns="http://maven.apache.org/SITE/2.1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -121,7 +98,11 @@ Your favorite IDE probably supports XSD schema's for Xdoc
and FML files. You nee
</site>
```
-**Note**: for performance reasons, all XSDs/DTDs use a cache in
${java.io.tmpdir}.
+The Book and Document schemas (`book-1.0.0.xsd`, `document-1.0.1.xsd`)
belonged to the book and PDF renderers,
+which are retired; they stay online for old documents.
+
+**Note**: the Xdoc and FML modules bundle their schemas, so validating those
files needs no network access. Other
+schemas and entity sets, including the XHTML entity sets, are downloaded once
per build and kept in memory.
<a id="doxia-character-entities"></a>
@@ -146,7 +127,7 @@ For instance, you could add the following in your Xdoc XML
files to be similar t
]>
<document xmlns="http://maven.apache.org/XDOC/2.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
http://maven.apache.org/xsd/xdoc-2.0.xsd">
+xsi:schemaLocation="http://maven.apache.org/XDOC/2.0
https://maven.apache.org/xsd/xdoc-2.0.xsd">
...
</document>
```
diff --git a/content/markdown/doxia/index.md.vm
b/content/markdown/doxia/index.md.vm
index 2f2922de..29209e5d 100644
--- a/content/markdown/doxia/index.md.vm
+++ b/content/markdown/doxia/index.md.vm
@@ -3,7 +3,7 @@ title: Introduction
author:
- Jason van Zyl
- Vincent Siveton
-date: 2010-05-28
+date: 2026-11-17
---
<!--
@@ -25,34 +25,62 @@ specific language governing permissions and limitations
under the License.
-->
+
# Maven Doxia
-Doxia is a content generation framework which aims to provide its users with
powerful techniques for generating static and dynamic content: Doxia can be
used in web-based publishing context to generate static sites, in addition to
being incorporated into dynamic content generation systems like blogs, wikis
and content management systems.
+Doxia is the document engine behind every Maven site. It reads the pages you
write in Markdown, APT, Xdoc, FML or
+XHTML and the reports that plugins generate, and turns them into HTML. When
you run `mvn site`, the
+[Maven Site Plugin](/plugins/maven-site-plugin/) uses Doxia to do the work.
+
+The current release of [Doxia](./doxia/) is ${doxiaVersion}.
+
+<a id="Doxia_Reference_Pages"></a>
+
+${esc.h}${esc.h} Write a site
+
+You don't need to install or configure Doxia: the Maven Site Plugin includes
every format listed here. Put your
+pages under `src/site/<format>/` and run `mvn site`. The [guide to creating a
site](/guides/mini/guide-site.html)
+covers the whole setup.
+
+- [Choose a format](./references/index.html). Markdown is the best choice for
new pages. APT and Xdoc still work,
+ and [Migrating APT to Markdown](./migrating-apt-to-markdown.html) shows how
to move existing pages. FML is
+ deprecated since Doxia 2.2.0.
+- [Add generated content with macros](./macros/index.html), such as a table of
contents (`toc`) or a code
+ excerpt from a source file (`snippet`).
+- [Draw diagrams with Mermaid](./mermaid-diagrams.html).
+- [Check what each format can and cannot
express](./references/index.html#Limitations) before you convert a page.
+- If something renders differently from what you expect, see the
[FAQ](./faq.html) and
+ [Issues and Gotchas](./issues/index.html).
-Doxia supports [markup languages with simple
syntaxes](./references/index.html). Lightweight markup languages are used by
people who might be expected to read the document source as well as the
rendered output.
+${esc.h}${esc.h} Write a plugin report or extend Doxia
-Doxia is used extensively by [Maven](http://maven.apache.org) and it powers
the entire documentation system of Maven. It gives Maven the ability to take
any document that Doxia supports and output it any format.
+Report plugins write their output through the Doxia Sink API, which keeps them
independent of the output format.
-The current version of [Doxia base framework](./doxia/) is ${doxiaVersion}.
+- [Using the Sink API](./developers/sink.html) shows how to emit headings,
tables and links.
+- [Creating a Doxia Macro](./developers/macros.html) and [Creating a Doxia
Module](./developers/modules.html) show
+ how to add your own macro or markup format.
+- The [Overview](./overview.html) explains how parsers, sinks and the site
renderer fit together.
-${esc.h}${esc.h} Brief History
+<a id="Main_Features"></a>
-<!-- {{{http://www.xmlmind.com/aptconvert.html}Aptconvert}}-->
+${esc.h}${esc.h} Components
-Based on the (now defunct) Aptconvert project developed by
[Xmlmind](http://www.xmlmind.com/), Doxia was initially hosted by
[Codehaus](http://codehaus.org/), to become a sub-project of Maven early in
2006\.
+Doxia is released as three components.
-${esc.h}${esc.h} Main Features
+| Component | What it does |
+|---|---|
+| [Doxia](./doxia/) | The Sink API, the parsers and sinks for each format, and
the macros. |
+| [Doxia Sitetools](./doxia-sitetools/) | The site model (`site.xml`) and the
renderer that applies a skin to the pages. |
+| [Doxia Tools](./doxia-tools/) | Stand-alone tools, such as the [Doxia
Converter](./doxia-tools/doxia-converter/index.html), which converts a document
from one format to another. |
-- Developed in Java
-- [Support of several markup formats](./references/index.html): APT (Almost
Plain Text), Markdown, FML (FAQ Markup Language), XDoc (popular in Apache
land), XHTML
-- Easy to [learn the syntax of the supported markup
formats](./modules/index.html)
-- Macro support
-- No need to have a corporate infrastructure (like wiki) to host your
documentation
-- Extensible framework
-- [Site Tools extension](./doxia-sitetools/) for site or document rendering
-- [Additional Tools](./doxia-tools/) like [Doxia
Converter](./doxia-tools/doxia-converter/index.html) (see also [Migrating APT
to Markdown](./migrating-apt-to-markdown.html))
+All components are published to Maven Central under the
`org.apache.maven.doxia` group ID, see
+[Downloads](./downloads.html).
-${esc.h}${esc.h} Doxia Reference Pages
+<a id="Brief_History"></a>
-See [Doxia Markup Languages References](./references/index.html) page for a
listing of all supported markups for each format.
+${esc.h}${esc.h} History
+Doxia is based on the Aptconvert project by
[XMLmind](https://www.xmlmind.com/), was first hosted at
+Codehaus, and became a Maven subproject in 2006. Doxia 2.0, released in 2024,
moved the output to HTML5 and
+removed the PDF, LaTeX, RTF, DocBook, Confluence and TWiki modules; see
+[Former Doxia Formats](./references/index.html#Former_Doxia_Formats).
diff --git a/content/markdown/doxia/issues/index.md
b/content/markdown/doxia/issues/index.md
index fd87551e..2011d165 100644
--- a/content/markdown/doxia/issues/index.md
+++ b/content/markdown/doxia/issues/index.md
@@ -24,63 +24,56 @@ specific language governing permissions and limitations
under the License.
-->
+
# Doxia Issues & Gotchas
-This document collects some infos about specific issues and
'gotchas' when working with Doxia. Please check also the [Frequently
Asked Questions](../faq.html).
+This page collects behavior that tends to surprise authors and plugin
developers. See also the
+[Frequently Asked Questions](../faq.html) and the [limitations of each
format](../references/index.html#Limitations).
<!-- MACRO{toc|section=1|fromDepth=2|toDepth=2} -->
## <a id="Apt_anchors_and_links"></a>Apt anchors and links
-Using **Doxia 1\.1** you may see a lot of warnings when processing old Apt
source files:
-
-```text
-[WARNING] [Apt Parser] Ambiguous link: 'doxia-apt.html'. If this is a local
link, prepend "./"!
-```
-
-and
-
-```text
-[WARNING] [Apt Parser] Modified invalid link: references/doxia-apt.html
-```
+In APT, a link to another document must start with `./` or `../`. Without it,
Doxia treats the target as an anchor
+in the same page, and an internal link must _not_ start with `#`. Read the
[anchors](../references/apt-format.html#Anchors)
+and [links](../references/apt-format.html#Links) sections of the APT reference.
-The reason is that in Apt, links to other source documents have to start with
either `./` or `../` to distinguish them from internal links. Please read the
sections on [anchors](../references/doxia-apt.html#Anchors) and
[links](../references/doxia-apt.html#Links) in our Apt guide. Note in
particular that internal links in Apt do **not** start with '\#'.
+Doxia does not warn about a link that lacks the prefix. It turns the link into
an anchor in the same page, so
+`{{{doxia-apt.html}text}}` becomes `<a href="#doxia-apt.html">` and
`{{{references/doxia-apt.html}text}}` becomes
+`<a href="#references.2Fdoxia-apt.html">`. Both are broken in the output and
Doxia does not warn, so check the
+links in the generated pages, or run a link checker over `target/site`.
-**You should pay attention to these warnings since your links will most likely
be broken.** Unfortunately, the warning message cannot indicate the source file
with the broken link (see eg
[MPDF-11](https://issues.apache.org/jira/browse/MPDF-11)), however, if you run
in `DEBUG` mode, eg invoke maven with the `-X` switch, you can see which source
document is being parsed when the warning is emitted.
+Converting the page to [Markdown](../migrating-apt-to-markdown.html) avoids
the problem, since Markdown links work
+as written.
## <a id="Figure_sink_events"></a>Figure sink events
-Doxia distinguishes between figures, which are block-level elements, and
images (or icons), which are in-line elements. For instance, the following
sequence of sink events
+Doxia distinguishes between figures, which are block-level elements, and
images, which are inline. A figure is
+written as a sequence of events:
```java
-sink.figure( null );
+sink.figure();
-sink.figureGraphics( "figure.png", null );
+sink.figureGraphics("figure.png");
-sink.figureCaption( null );
-sink.text( "Figure caption", null );
+sink.figureCaption();
+sink.text("Figure caption");
sink.figureCaption_();
sink.figure_();
```
-should output the equivalent of this html snippet:
+The HTML5 sink writes this as:
-```xml
-<div class="figure">
- <p><img src="figure.png"/></p>
- <p>Figure caption</p>
-</div>
+```html
+<figure><img src="figure.png" /><figcaption>Figure
caption</figcaption></figure>
```
-while the `figureGraphics( ... );` event alone can be used to generate an
in-line image, i.e. just the `<img>` tag in case of html.
-
-**Note** that we are using the forms that take a `SinkEventAttributeSet`
above, even though we are just passing in null values. The reason is that the
alternative forms (without `SinkEventAttributeSet`) have a different behavior,
which is kept for backward compatibility (but the methods have been
deprecated). Using the same sequence of sink events as above, but omitting the
`null` method parameters, will generate
-
-```xml
-<img src="figure.png" alt="Figure caption"/>
-```
+A `figureGraphics(...)` event on its own, outside `figure()`, writes just the
inline `<img>` element. Pass the
+alternative text as the `alt` attribute in a `SinkEventAttributeSet`; a
caption is not used as alternative text.
## <a id="Empty_Generated_Page"></a>Empty Generated Page
-After running `mvn site` using your Maven reporting plugin, you see that the
generated page is empty. Be sure that the the code calls `sink.close()`.
-
+If a report page comes out empty after `mvn site`, check that the report
closes its sink with `sink.close()`. Reports
+that extend `AbstractMavenReport` from [Maven Reporting
Implementation](/shared/maven-reporting-impl/) get this
+for free, including the sub-page sinks created through the `SinkFactory`
passed to `generate()`. A report that
+implements `MavenReport` directly, or that creates sinks of its own, must
close each of them.
diff --git a/content/markdown/doxia/modules/index.md
b/content/markdown/doxia/modules/index.md
index 39f1d478..45480800 100644
--- a/content/markdown/doxia/modules/index.md
+++ b/content/markdown/doxia/modules/index.md
@@ -2,7 +2,7 @@
title: Doxia Modules Guide
author:
- Vincent Siveton
-date: 2009-06-15
+date: 2026-11-17
---
<!--
@@ -24,51 +24,60 @@ specific language governing permissions and limitations
under the License.
-->
+
# Doxia Modules Guide
-Doxia has several built-in modules that support some standard markup
languages, see the [References](../references/index.html) page for an overview.
The following is just a collection of reference links for the individual
formats.
+Each markup format is implemented by one Doxia module. All five modules below
are part of Doxia and are included in
+the Maven Site Plugin, so you can use any of them without extra configuration.
FML is deprecated. The
+[format references](../references/index.html) compare them side by side,
including which ones Doxia can also write
+and what each format cannot express.
<!-- MACRO{toc|section=1|fromDepth=2|toDepth=2} -->
-## <a id="APT"></a>APT
-
-APT (Almost Plain Text) is a legacy simple text format.
-
-**References**:
-
-- [Apt Reference](../references/apt-format.html)
+## <a id="Markdown"></a>Markdown
-## <a id="FML"></a>FML
+Use Markdown for new pages. It is the format most authors and editors already
know, it renders on GitHub, and Doxia
+can both read and write it. Doxia follows
[CommonMark](https://commonmark.org/) and adds tables, strikethrough,
+footnotes, definition lists, abbreviations and YAML front matter for the page
title, author and date.
-FML (FAQ Markup Language) is a legacy FAQ markup language based on XHTML 1.0.
+- [Markdown format reference](../references/markdown-format.html)
+- [doxia-module-markdown](../doxia/doxia-modules/doxia-module-markdown/), with
the full list of supported extensions
+- [CommonMark specification](https://spec.commonmark.org/) and
+ [GitHub Flavored Markdown specification](https://github.github.com/gfm/)
-**References**:
+## <a id="APT"></a>APT
-- [FML Reference](../references/fml-format.html)
+APT (Almost Plain Text) is the original Doxia format and predates Markdown.
Existing APT pages keep working, and
+[Migrating APT to Markdown](../migrating-apt-to-markdown.html) shows how to
convert them.
-## <a id="Markdown"></a>Markdown
+- [APT format reference](../references/apt-format.html)
+- [doxia-module-apt](../doxia/doxia-modules/doxia-module-apt/)
-[Markdown](http://en.wikipedia.org/wiki/Markdown) is a widespread Markup
language.
+## <a id="XDoc"></a>XDoc
-**References**:
+XDoc is an XML format with HTML-like body markup, long used on Apache project
sites. It gives you more control over
+the HTML than APT or Markdown, at the cost of verbose sources.
-- [Official Markdown project at Daring
Fireball](https://daringfireball.net/projects/markdown/)
-- [CommonMark specification](https://commonmark.org/)
-- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/)
+- [XDoc format reference](../references/xdoc-format.html)
+- [doxia-module-xdoc](../doxia/doxia-modules/doxia-module-xdoc/)
-## <a id="XDoc"></a>XDoc
+## <a id="FML"></a>FML
-XDoc is a legacy format for document into a styled HTML document based on
XHTML 1.0.
+FML (FAQ Markup Language) is an XML format for FAQ pages: it groups questions
into parts and generates the list of
+questions with links to the answers. Doxia can read FML but not write it.
-**References**:
+FML is deprecated since Doxia 2.2.0 and will be removed in the next major
version
+([apache/maven-doxia#1101](https://github.com/apache/maven-doxia/issues/1101)).
Write new FAQ pages in Markdown;
+the [Doxia Converter](../doxia-tools/doxia-converter/) converts existing
`.fml` files.
-- [XDoc Reference](../references/xdoc-format.html)
+- [FML format reference](../references/fml-format.html)
+- [doxia-module-fml](../doxia/doxia-modules/doxia-module-fml/)
## <a id="XHTML"></a>XHTML
-[XHTML](https://html.spec.whatwg.org/multipage/xhtml.html) is a markup
language with the same expressions as HTML, but also conforms to XML syntax.
Doxia supports it through the `doxia-module-xhtml5` module; the earlier XHTML
1\.0 module was removed in Doxia 2\.0\.
-
-**References**:
+The `doxia-module-xhtml5` module reads and writes
[XHTML](https://html.spec.whatwg.org/multipage/xhtml.html), the
+XML serialization of HTML5. Use it when a page needs HTML that the other
formats cannot produce. The HTML5 sink of
+this module also writes every page of a Maven site. The XHTML 1.0 module was
removed in Doxia 2.0.
-- [XHTML 5/Living Standard](https://html.spec.whatwg.org/multipage/xhtml.html)
-- [Outdated XHTML 1\.0 Specification](https://www.w3.org/TR/xhtml1/)
+- [doxia-module-xhtml5](../doxia/doxia-modules/doxia-module-xhtml5/)
+- [HTML Living Standard, XML
syntax](https://html.spec.whatwg.org/multipage/xhtml.html)
diff --git a/content/markdown/doxia/overview.md
b/content/markdown/doxia/overview.md
index 7898f212..9674d5c8 100644
--- a/content/markdown/doxia/overview.md
+++ b/content/markdown/doxia/overview.md
@@ -1,8 +1,8 @@
---
-title: Overview Of The Doxia Framework
+title: Overview of the Doxia framework
author:
- Vincent Siveton
-date: 2009-03-02
+date: 2026-11-17
---
<!--
@@ -24,63 +24,70 @@ specific language governing permissions and limitations
under the License.
-->
-# Overview Of The Doxia Framework
-The following figure represents the main components of the Doxia Framework.
+# Overview of the Doxia framework
-
+<a id="Overview_Of_The_Doxia_Framework"></a>
-**Note**: Just like Maven, Doxia uses
[Plexus](https://codehaus-plexus.github.io/) extensively.
+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.
-## Sink API
+The following figure shows the main components.
+
+
-The _Sink_ interface is a generic markup language interface. It contains
several methods that encapsulate common text syntax. A start tag is denoted by
_xxxx()_ method and a end of tag by _xxxx\_()_ method.
+Doxia components are [JSR-330](/maven-jsr330.html) components, managed by
Eclipse Sisu just like Maven's own.
-For instance, you could do things like:
+## 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:
```java
sink.paragraph();
-sink.text( "my text" );
-sink.paragraph_();
+sink.text("my text");
+sink.paragraph_();
```
-similar to this HTML markup:
+The HTML sink writes this as:
-```xml
+```html
<p>my text</p>
```
-To find out more about the Sink API, you could read the Javadoc
[here](http://maven.apache.org/doxia/doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html).
+Maven report plugins use the Sink API directly to write their pages. See
+[Using the Doxia Sink API](./developers/sink.html) and the
+[`Sink`
Javadoc](./doxia/doxia-sink-api/apidocs/org/apache/maven/doxia/sink/Sink.html).
## Doxia Core
-The _Core_ is the API to parse a source and populate it in a _Sink_ object.
The _Parser_ interface's central method is:
+Doxia Core holds the parser API and the shared implementations. The central
method of the `Parser` interface is:
```java
-void parse( Reader source, Sink sink )
- throws ParseException;
+void parse(Reader source, Sink sink) throws ParseException;
```
-The _ParseException_ class has the responsibility to catch all parsing
exceptions. It provides an helper method, _getLineNumber()_, which helps to
find where an error occurred.
+A `ParseException` carries the line and column where parsing failed, through
`getLineNumber()` and
+`getColumnNumber()`.
-The _AbstractParser_ class is an abstract implementation of the _Parser_. It
provides a macro mechanism to give dynamic functionalities for the parsing. For
more information on macros, read the [Doxia Macro Guide](./macros/index.html).
+`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](./macros/index.html).
-Finally, the _ParserModule_ interface is the last part of the puzzle. It
provides main definitions of a given Doxia module and it is used by the
_doxia-site-renderer_ site tools.
+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 is an implementation of a given markup language like APT or
Xdoc. Each module should implement these interfaces:
-
-- _Parser_ interface, more specifically the _AbstractParser_ class
-
-- _ParserModule_ interface
-
-Several modules provide also a _Sink_ implementation to handle a specific
output markup language.
-
-For more information on modules, read the [Doxia Module
Guide](./modules/index.html).
+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](./references/index.html) list which modules can do
what, and
+[Create a Doxia Module](./developers/modules.html) shows how to write one.
## Doxia Site Tools
-The _Site Tools_ are a collection of tools to renderer an output. The main
tool used by Maven, specifically the [Maven Site
Plugin](http://maven.apache.org/plugins/maven-site-plugin/), is the
_doxia-site-renderer_ which renders in HTML any documents written with
supported markup syntax. It uses [Velocity
templates](http://velocity.apache.org/) to customize the renderer and the
_doxia-site-model_ tool to decorate the renderer. This component describes the
layout of the site defined in the [...]
-
-
+[Doxia Sitetools](./doxia-sitetools/) builds a whole site from single
documents. The site renderer, used by the
+[Maven Site Plugin](/plugins/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](https://velocity.apache.org/)
+templates. The site model describes the menus, breadcrumbs and other
decoration set in `site.xml`.
diff --git a/content/markdown/doxia/references/index.md
b/content/markdown/doxia/references/index.md
index 774f1c88..05efb59a 100644
--- a/content/markdown/doxia/references/index.md
+++ b/content/markdown/doxia/references/index.md
@@ -39,7 +39,7 @@ The source directory is the directory under which Maven
expects source documents
|[Apt](./apt-format.html)|Almost Plain Text, predates Doxia's Markdown
support|||`apt`|`apt`|[`doxia-module-apt`](../doxia/doxia-modules/doxia-module-apt/)|`apt`|
|[AsciiDoc](https://asciidoctor.org/)|[Asciidoctor Converter Doxia
Module](https://docs.asciidoctor.org/maven-tools/latest/site-integration/converter-module-setup-and-configuration/),
only emits
`Sink.rawText()`|||`asciidoc`|`adoc`,
`asciidoc`|[`asciidoctor-converter-doxia-module`](https://github.com/asciidoctor/asciidoctor-maven-plugin#maven-site-integration)|`asciidoc`|
|[AsciiDoc](https://asciidoctor.org/)|[Asciidoctor Parser Doxia
Module](https://docs.asciidoctor.org/maven-tools/latest/site-integration/parser-module-setup-and-configuration/),
still in
beta|||`asciidoc`|`adoc`,
`asciidoc`|[`asciidoctor-parser-doxia-module`](https://github.com/asciidoctor/asciidoctor-maven-plugin#maven-site-integration)|`asciidoc`|
-|[FML](./fml-format.html)|FAQ Markup
Language|||`fml`|`fml`|[`doxia-module-fml`](../doxia/doxia-modules/doxia-module-fml/)|`fml`|
+|[FML](./fml-format.html)|FAQ Markup Language, deprecated since Doxia
2.2.0|||`fml`|`fml`|[`doxia-module-fml`](../doxia/doxia-modules/doxia-module-fml/)|`fml`|
|[Markdown](./markdown-format.html)|Markdown markup
language|||`markdown`|`md`,
`markdown`|[`doxia-module-markdown`](../doxia/doxia-modules/doxia-module-markdown/)|`markdown`|
|[Xdoc](./xdoc-format.html)|XML Documentation
Format|||`xdoc`|`xml`|[`doxia-module-xdoc`](../doxia/doxia-modules/doxia-module-xdoc/)|`xdoc`|
|[XHTML5](../modules/index.html#XHTML)|Extensible Hypertext Markup Language,
HTML5
serialisation|||`xhtml`|`xhtml`|[`doxia-module-xhtml5`](../doxia/doxia-modules/doxia-module-xhtml5/)|`xhtml`|
diff --git a/content/markdown/doxia/resources.md
b/content/markdown/doxia/resources.md
index 04c95ba2..0f752f86 100644
--- a/content/markdown/doxia/resources.md
+++ b/content/markdown/doxia/resources.md
@@ -24,20 +24,26 @@ specific language governing permissions and limitations
under the License.
-->
+
# External Resources
## Extensions
-|Name|Author|
-|:---|:---|
-|[Doxia :: Include Macro](http://doxia-include.sourceforge.net/)|Juergen
Kellerer|
+The following projects add formats or macros to Doxia. They are not maintained
by the Maven project.
+
+| Name | What it adds | Doxia line |
+|:---|:---|:---|
+| [Asciidoctor Doxia
modules](https://docs.asciidoctor.org/maven-tools/latest/site-integration/parser-module-setup-and-configuration/)
| AsciiDoc pages in a Maven site; see [Markup Languages
References](./references/index.html) for setup | 2.x |
+| [Doxia Include Macro](http://doxia-include.sourceforge.net/) | Includes
files, snippets and Velocity templates with syntax highlighting, by Juergen
Kellerer | 1.x, not updated since |
+
## Articles
-|Title|Publisher|Author|
+| Title | Publisher | Author |
|:---|:---|:---|
-|[Quick and dirty typesetting with
APT](https://www.linux.com/news/quick-and-dirty-typesetting-apt/)|linux.com|Scott
Nesbitt|
-|[Lightweight markup
language](http://en.wikipedia.org/wiki/Lightweight_markup_language)|wikipedia.org|?|
+| [Quick and dirty typesetting with
APT](https://www.linux.com/news/quick-and-dirty-typesetting-apt/) | linux.com |
Scott Nesbitt |
+| [Lightweight markup
language](https://en.wikipedia.org/wiki/Lightweight_markup_language) |
wikipedia.org | |
+
## Related External Projects
-- [XWiki](http://www.xwiki.org/) which uses Doxia in its
[rendering](http://svn.xwiki.org/svnroot/xwiki/platform/core/trunk/xwiki-rendering/xwiki-rendering-parsers/xwiki-rendering-parser-doxia/).
-- [Mylyn WikiText](http://wiki.eclipse.org/Mylyn/Incubator/WikiText)
(originally known as Textile-J).
+- [XWiki Rendering](https://github.com/xwiki/xwiki-rendering), the rendering
engine of [XWiki](https://www.xwiki.org/),
+ builds on Doxia 1.x for some of its syntaxes.