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-doxia.git
The following commit(s) were added to refs/heads/master by this push:
new 58305528 Describe the Doxia modules on the site index and fix code
block languages
58305528 is described below
commit 58305528b2eac36183819d4727afe0802a20faf2
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Tue Nov 17 21:22:46 2026 +0000
Describe the Doxia modules on the site index and fix code block languages
The DoxiaUtils Javadoc link is absolute on purpose: Doxia encodes the
fragment of a relative link, which would turn #encodeId(java.lang.String) into
#encodeId.28java.lang.String.29.
---
.../src/site/markdown/using-randomaccesssink.md | 4 ++--
.../doxia-module-fml/src/site/markdown/index.md | 2 +-
.../src/site/markdown/using-fml-xsd.md | 2 +-
.../src/site/markdown/index.md | 8 ++++----
.../src/site/markdown/using-xdoc-xsd.md | 2 +-
.../doxia-module-xhtml5/src/site/markdown/index.md | 4 ++--
doxia-sink-api/src/site/markdown/index.md | 4 ++--
src/site/markdown/index.md | 24 ++++++++++++++++++----
src/site/site.xml | 2 +-
9 files changed, 34 insertions(+), 18 deletions(-)
diff --git a/doxia-core/src/site/markdown/using-randomaccesssink.md
b/doxia-core/src/site/markdown/using-randomaccesssink.md
index fe6d4834..4149bd9a 100644
--- a/doxia-core/src/site/markdown/using-randomaccesssink.md
+++ b/doxia-core/src/site/markdown/using-randomaccesssink.md
@@ -28,7 +28,7 @@ under the License.
The RandomAccessSink is a Sink with the ability to add hooks. To demonstrate
its usage we can have a look at a FML (FAQ Markup Language)-page. The simple
structure of such a page can be like:
-```unknown
+```xml
<faq id="1">
<question/>
<answer/>
@@ -50,7 +50,7 @@ With a Sink you can only append and there's no option to
buffer. This would
When using the RandomAccesSink we can prepare the structure of the page
-```unknown
+```java
RandomAccessSink randomAccessSink = new RandomAccessSink(sinkFactory,
outputStream, encoding);
Sink questions = randomAccessSink.addSinkHook();
Sink qAndA = randomAccessSink.addSinkHook();
diff --git a/doxia-modules/doxia-module-fml/src/site/markdown/index.md
b/doxia-modules/doxia-module-fml/src/site/markdown/index.md
index 48bb707d..0c2b5454 100644
--- a/doxia-modules/doxia-module-fml/src/site/markdown/index.md
+++ b/doxia-modules/doxia-module-fml/src/site/markdown/index.md
@@ -36,7 +36,7 @@ already parsed as XDoc. The same page can be written in
Markdown or XDoc without
anything, and
[doxia-converter](https://maven.apache.org/doxia/doxia-tools/doxia-converter/)
converts existing `.fml` files:
-```
+```bash
java -jar doxia-converter-<version>-jar-with-dependencies.jar \
-from fml -in src/site/fml/faq.fml -to markdown -out
src/site/markdown/faq.md
```
diff --git a/doxia-modules/doxia-module-fml/src/site/markdown/using-fml-xsd.md
b/doxia-modules/doxia-module-fml/src/site/markdown/using-fml-xsd.md
index 4f61c0ed..529dfb2d 100644
--- a/doxia-modules/doxia-module-fml/src/site/markdown/using-fml-xsd.md
+++ b/doxia-modules/doxia-module-fml/src/site/markdown/using-fml-xsd.md
@@ -30,7 +30,7 @@ The FML XSD is located
[here](https://maven.apache.org/xsd/fml-1.0.1.xsd).
Your favorite IDE probably supports XSD schema's for .fml files. You need
to specify the following:
-```unknown
+```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
https://maven.apache.org/xsd/fml-1.0.1.xsd"
diff --git a/doxia-modules/doxia-module-markdown/src/site/markdown/index.md
b/doxia-modules/doxia-module-markdown/src/site/markdown/index.md
index c7540492..b1557a67 100644
--- a/doxia-modules/doxia-module-markdown/src/site/markdown/index.md
+++ b/doxia-modules/doxia-module-markdown/src/site/markdown/index.md
@@ -32,7 +32,7 @@ Markdown is a popular lightweight markup language, easy to
read and easy to writ
Although metadata was not part of the original Markdown format it is now
widely supported through multiple extensions. This modules supports the
following two metadata formats:
-- [MultiMarkdown
Metadata](http://fletcher.github.io/MultiMarkdown-5/metadata.html)
+- [MultiMarkdown
Metadata](https://fletcher.github.io/MultiMarkdown-5/metadata.html)
- [YAML front
matter](https://github.com/vsch/flexmark-java/wiki/Extensions#yaml-front-matter)
*Metadata must be placed at the beginning of the document, before any other
content.*
@@ -80,8 +80,8 @@ Note that this differs from the APT and XDoc modules, where
`+--` and `<source>`
## References
-- [Markdown project website](http://daringfireball.net/projects/markdown)
+- [Markdown project website](https://daringfireball.net/projects/markdown/)
- [CommonMark spec](https://spec.commonmark.org/)
- [GitHub Flavored Markdown](https://github.github.com/gfm)
-- [Markdown Wikipedia page](http://en.wikipedia.org/wiki/Markdown)
-- [flexmark-java](http://github.com/vsch/flexmark-java), the library used by
this Doxia module in [`Pegdown`](https://github.com/sirthias/pegdown)
compatibility mode
+- [Markdown Wikipedia page](https://en.wikipedia.org/wiki/Markdown)
+- [flexmark-java](https://github.com/vsch/flexmark-java), the library this
module uses to parse Markdown
diff --git
a/doxia-modules/doxia-module-xdoc/src/site/markdown/using-xdoc-xsd.md
b/doxia-modules/doxia-module-xdoc/src/site/markdown/using-xdoc-xsd.md
index ba9ccf45..2708a849 100644
--- a/doxia-modules/doxia-module-xdoc/src/site/markdown/using-xdoc-xsd.md
+++ b/doxia-modules/doxia-module-xdoc/src/site/markdown/using-xdoc-xsd.md
@@ -30,7 +30,7 @@ The XDOC XSD is located
[here](https://maven.apache.org/xsd/xdoc-2.0.xsd).
Your favorite IDE probably supports XSD schema's for .xml/.xdoc files.
You need to specify the following:
-```unknown
+```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
https://maven.apache.org/xsd/xdoc-2.0.xsd">
diff --git a/doxia-modules/doxia-module-xhtml5/src/site/markdown/index.md
b/doxia-modules/doxia-module-xhtml5/src/site/markdown/index.md
index 6f53d604..92784e73 100644
--- a/doxia-modules/doxia-module-xhtml5/src/site/markdown/index.md
+++ b/doxia-modules/doxia-module-xhtml5/src/site/markdown/index.md
@@ -22,11 +22,11 @@ This parser and sink digests and emits sources compliant
with the [XML syntax of
## Special handling of anchors
-Anchor ids/names need to follow a strict syntax in Doxia, therefore both
anchor names (`<a name="...">`) as well as internal link targets (`<a
href="..."`) are automatically adjusted to comply with that syntax. Further
details in
[DoxiaUtils.encodeId(...)](../../doxia-core/apidocs/org/apache/maven/doxia/util/DoxiaUtils.html#encodeId-java.lang.String-).
+Anchor ids/names need to follow a strict syntax in Doxia, therefore both
anchor names (`<a name="...">`) as well as internal link targets (`<a
href="..."`) are automatically adjusted to comply with that syntax. Further
details in
[DoxiaUtils.encodeId(...)](https://maven.apache.org/doxia/doxia/doxia-core/apidocs/org/apache/maven/doxia/util/DoxiaUtils.html#encodeId(java.lang.String)).
In order to leave internal link targets (i.e. ones not starting with a scheme)
unprocessed use attribute `rel` with value `external` like this
-```
+```html
<a href="testpage#specialanchor()" rel="external">...</a>
```
diff --git a/doxia-sink-api/src/site/markdown/index.md
b/doxia-sink-api/src/site/markdown/index.md
index cba2b1b5..a4ccee3f 100644
--- a/doxia-sink-api/src/site/markdown/index.md
+++ b/doxia-sink-api/src/site/markdown/index.md
@@ -30,7 +30,7 @@ The _Sink_ interface is a generic markup language interface
provided as a Java A
For instance, you could do things like:
-```unknown
+```java
sink.paragraph();
sink.text("my text");
sink.paragraph_();
@@ -38,7 +38,7 @@ sink.paragraph_();
similar to this HTML markup:
-```unknown
+```html
<p>my text</p>
```
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index 6f1dab55..1ec9423a 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -23,15 +23,31 @@ specific language governing permissions and limitations
under the License.
-->
+
# Doxia
-Doxia is a content generation framework that provides powerful techniques for
generating static and dynamic content, supporting [a variety of markup
languages](/doxia/references/index.html).
+This is the base component of [Doxia](https://maven.apache.org/doxia/), the
document engine behind Maven sites. It
+contains the Sink API, the parsers and sinks for each markup format, and the
built-in macros. Most users never call
+it directly: the [Maven Site
Plugin](https://maven.apache.org/plugins/maven-site-plugin/) uses it through
+[Doxia Sitetools](https://maven.apache.org/doxia/doxia-sitetools/). For an
introduction to the formats and how to use
+them, start at the [Doxia home page](https://maven.apache.org/doxia/).
+
+The component consists of the following modules.
-The actual component is the base component from the whole Doxia suite, with
the core parser and sink APIs and their implementation in supported markup
languages.
+| Module | Contents |
+|---|---|
+| [doxia-sink-api](./doxia-sink-api/) | The `Sink` interface that all parsers
write to and all output formats implement. |
+| [doxia-core](./doxia-core/) | The `Parser` API, base classes for parsers and
sinks, and the `toc`, `snippet` and `echo` macros. |
+| [doxia-module-markdown](./doxia-modules/doxia-module-markdown/) | Markdown
parser and sink, based on
[flexmark-java](https://github.com/vsch/flexmark-java). |
+| [doxia-module-apt](./doxia-modules/doxia-module-apt/) | APT (Almost Plain
Text) parser and sink. |
+| [doxia-module-xdoc](./doxia-modules/doxia-module-xdoc/) | Xdoc parser and
sink. |
+| [doxia-module-xhtml5](./doxia-modules/doxia-module-xhtml5/) | XHTML5 parser
and sink; the sink also writes the pages of a Maven site. |
+| [doxia-module-fml](./doxia-modules/doxia-module-fml/) | FML (FAQ Markup
Language) parser, deprecated since 2.2.0. |
+| [doxia-test-docs](./doxia-test-docs/) | Sample documents shared by the
module tests. |
-It is used by the [Doxia Sitetools](../doxia-sitetools) extension, that adds
site and documents support.
+The following diagram shows how the modules depend on each other.
-<img src="images/doxia-deps.png" border="0" usemap="#Doxia_dependencies" />
+<img src="images/doxia-deps.png" alt="Dependencies between the Doxia modules"
usemap="#Doxia_dependencies" />
<map name="Doxia_dependencies">
<area shape="rect" coords="0,280,122,308" href="./doxia-test-docs/" />
<area shape="rect" coords="135,231,286,261" href="./doxia-sink-api/" />
diff --git a/src/site/site.xml b/src/site/site.xml
index 5127464d..0e878589 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -38,7 +38,7 @@
<menu name="Overview">
<item name="Introduction" href="index.html"/>
<!-- According to https://issues.apache.org/jira/browse/MNGSITE-152 -->
- <item name="License" href="http://www.apache.org/licenses/"/>
+ <item name="License" href="https://www.apache.org/licenses/"/>
<item name="Download" href="download.html"/>
</menu>