You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maven.apache.org by sl...@apache.org on 2026/08/09 22:20:57 UTC
(maven-site) branch master updated: Lead with Markdown in the site and plugin documentation guides
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 9e865353 Lead with Markdown in the site and plugin documentation guides
9e865353 is described below
commit 9e8653534c2f6b6e5898b2c5009be6249ea8a65e
Author: Sylwester Lachiewicz <sl...@apache.org>
AuthorDate: Fri Aug 7 22:50:49 2026 +0200
Lead with Markdown in the site and plugin documentation guides
The site guide listed apt first and described it as the format 'like this one',
which stopped being true when that guide became Markdown. It now lists markdown
first, says plainly that new documentation should use it, and describes apt as a
format that predates Maven's Markdown support - still supported, but the Maven
project has moved its own documentation off it - with a pointer to doxia-converter.
The plugin documentation guide gave a full APT template for src/site/apt/index.apt,
so a plugin author following it started in APT. It now shows the same page as
src/site/markdown/index.md, and explains the front matter and the ## trap for
anyone whose page needs Velocity.
The sample is wrapped in an unparsed block: the guide is itself a Velocity
template, and without it Velocity reads the sample's own ## headings as line
comments and deletes them - which it did, until the built page was checked.
---
.../development/guide-plugin-documentation.md.vm | 102 +++++++++++----------
content/markdown/guides/mini/guide-site.md | 12 +--
2 files changed, 59 insertions(+), 55 deletions(-)
diff --git a/content/markdown/guides/development/guide-plugin-documentation.md.vm b/content/markdown/guides/development/guide-plugin-documentation.md.vm
index ba7e38ec..e7bd7e8e 100644
--- a/content/markdown/guides/development/guide-plugin-documentation.md.vm
+++ b/content/markdown/guides/development/guide-plugin-documentation.md.vm
@@ -202,57 +202,61 @@ Below is the suggested site descriptor template (with maven-fluido-skin).
- Introduction
- The introduction is the front page of the plugin documentation. This is a good place to put any section and pages that need to be emphasized. The generated plugin parameter configuration should be linked here. Below is the suggested `src/site/apt/index.apt` template:
+ The introduction is the front page of the plugin documentation. This is a good place to put any section and pages that need to be emphasized. The generated plugin parameter configuration should be linked here. Below is the suggested `src/site/markdown/index.md` template:
+ ```markdown
+ #[[
+ ---
+ title: Introduction
+ author:
+ - Author
+ date: YYYY-MM-DD
+ ---
+
+ # Plugin Name
+
+ Plugin introduction, description, and other relevant information.
+
+ ## Goals Overview
+
+ General information about the goals.
+
+ - [prefix:goal](<goal>.html) short description for this plugin goal.
+
+ ## Usage
+
+ General instructions for using the Plugin Name can be found on the [usage page](usage.html). Some more
+ specific use cases are described in the examples given below. Last but not least, users occasionally contribute
+ additional examples, tips or errata to the plugin's wiki page.
+
+ If you have questions regarding the plugin, consult the [FAQ](faq.html) and feel
+ free to contact the [user mailing list](mailing-lists.html). Posts to the mailing list are archived and might
+ already contain the answer to your question. Hence, it is also worth browsing/searching
+ the [mail archive](mailing-lists.html).
+
+ If you think the plugin is missing a feature or has a defect, you can file a feature request or bug report in the
+ [issue management system](issue-management.html). When creating a new issue, please provide a comprehensive description of your
+ concern. Especially for fixing bugs, it is crucial that the developers can reproduce your problem. For this reason,
+ entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated.
+ Of course, patches are welcome, too. Contributors can check out the project from our
+ [source repository](scm.html) and will find supplementary information in the
+ [guide to helping with Maven](/guides/development/guide-helping.html).
+
+ ## Examples
+
+ To help you understand some usages of the Plugin Name,
+ you can take a look at the following examples:
+
+ - [Example Description One](./examples/example-one.html)
+ - [Example Description Two](./examples/example-two.html)
+ ]]#
```
- ------
- Introduction
- ------
- Author
- ------
- YYYY-MM-DD
- ------
-
-
- Plugin Name
-
- Plugin introduction, description, and other relevant information.
-
- * Goals Overview
-
- General information about the goals.
-
- * {{{<goal>.html}prefix:goal}} short description for this plugin goal.
-
- * Usage
-
- General instructions for using the Plugin Name can be found on the {{{usage.html}usage page}}. Some more
- specific use cases are described in the examples given below. Last but not least, users occasionally contribute
- additional examples, tips or errata to the plugin's wiki page.
-
- If you have questions regarding the plugin, consult the {{{faq.html}FAQ}} and feel
- free to contact the {{{mailing-lists.html}user mailing list}}. Posts to the mailing list are archived and might
- already contain the answer to your question. Hence, it is also worth browsing/searching
- the {{{mailing-lists.html}mail archive}}.
-
- If you think the plugin is missing a feature or has a defect, you can file a feature request or bug report in the
- {{{issue-management.html}issue management system}}. When creating a new issue, please provide a comprehensive description of your
- concern. Especially for fixing bugs, it is crucial that the developers can reproduce your problem. For this reason,
- entire debug logs, POMs or most preferably little demo projects attached to the issue are very much appreciated.
- Of course, patches are welcome, too. Contributors can check out the project from our
- {{{scm.html}source repository}} and will find supplementary information in the
- {{{/guides/development/guide-helping.html}guide to helping with Maven}}.
-
- * Examples
-
- To help you understand some usages of the Plugin Name,
- you can take a look at the following examples:
-
- * {{{./examples/example-one.html}Example Description One}}
-
- * {{{./examples/example-two.html}Example Description Two}}
-
- ```
+
+ The `---` block at the top carries the page title, author and date; the site skin turns
+ them into the document title and its `author` and `date` meta tags. If the page needs
+ Velocity — to interpolate a version into an example POM, say — name it `index.md.vm`
+ instead, and keep headings below level one away from `##`, which Velocity reads as a
+ line comment.
- Goals
diff --git a/content/markdown/guides/mini/guide-site.md b/content/markdown/guides/mini/guide-site.md
index 9df520d9..fe56dc4e 100644
--- a/content/markdown/guides/mini/guide-site.md
+++ b/content/markdown/guides/mini/guide-site.md
@@ -26,11 +26,11 @@ The first step to creating your site is to create some content. In Maven, the si
```
+- src/
+- site/
- +- apt/
- | +- index.apt
- !
+- markdown/
- | +- content.md
+ | +- index.md
+ |
+ +- apt/
+ | +- content.apt
|
+- fml/
| +- general.fml
@@ -46,8 +46,8 @@ You will notice there is now a `${project.basedir}/src/site` directory within wh
Let's take a look at the examples of the various document types:
-- `apt`: the APT format, "Almost Plain Text", is a wiki-like format that allows you to write simple, structured documents (like this one) very quickly. A full reference of the [APT Format](/doxia/references/apt-format.html) is available,
-- `markdown`: the well known [Markdown](https://en.wikipedia.org/wiki/Markdown) format,
+- `markdown`: the well known [Markdown](https://en.wikipedia.org/wiki/Markdown) format, and the one this page is written in. It is what new documentation should use,
+- `apt`: the APT format, "Almost Plain Text", a wiki-like format that predates Maven's support for Markdown. It is still supported, but the Maven project itself has moved its own documentation off it; see the [APT Format](/doxia/references/apt-format.html) reference if you are maintaining an existing page, and [doxia-converter](/doxia/doxia-tools/doxia-converter/) if you would like to convert one,
- `fml`: the FML format is the [FAQ format](/doxia/references/fml-format.html),
- `xdoc`: an XML document conforming to a small and simple set of tags, see the [full reference](/doxia/references/xdoc-format.html).