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 &amp; Gotchas
 
-This document collects some infos about specific issues and 
&apos;gotchas&apos; 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 &apos;\#&apos;.
+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
 
-![Doxia Framework](images/architecture.png) 
+<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.
+
+![Doxia Framework](images/architecture.png)
 
-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|![Yes](/images/icon_success_sml.gif)|![Yes](/images/icon_success_sml.gif)|`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()`|![Yes](/images/icon_success_sml.gif)|![No](/images/icon_error_sml.gif)|`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|![Yes](/images/icon_success_sml.gif)|![No](/images/icon_error_sml.gif)|`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|![Yes](/images/icon_success_sml.gif)|![No](/images/icon_error_sml.gif)|`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|![Yes](/images/icon_success_sml.gif)|![No](/images/icon_error_sml.gif)|`fml`|`fml`|[`doxia-module-fml`](../doxia/doxia-modules/doxia-module-fml/)|`fml`|
 |[Markdown](./markdown-format.html)|Markdown markup 
language|![Yes](/images/icon_success_sml.gif)|![Yes](/images/icon_success_sml.gif)|`markdown`|`md`,
 
`markdown`|[`doxia-module-markdown`](../doxia/doxia-modules/doxia-module-markdown/)|`markdown`|
 |[Xdoc](./xdoc-format.html)|XML Documentation 
Format|![Yes](/images/icon_success_sml.gif)|![Yes](/images/icon_success_sml.gif)|`xdoc`|`xml`|[`doxia-module-xdoc`](../doxia/doxia-modules/doxia-module-xdoc/)|`xdoc`|
 |[XHTML5](../modules/index.html#XHTML)|Extensible Hypertext Markup Language, 
HTML5 
serialisation|![Yes](/images/icon_success_sml.gif)|![Yes](/images/icon_success_sml.gif)|`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.

Reply via email to