The Velocity Site News module consists of a plugin and an extension to the Maven core. It allows you to create and maintain a list of news items for your site which can be displayed as a standalone page, as part of another page or an RSS news feed.
The news items are stored in XML format in src/site/news.xml. This is an example news item:
<item id="very-important-news">
<date>2007-01-07</date>
<headline>The grass is greener over there</headline>
<categories>
<category>general</category>
<category>grass</category>
</categories>
<text><![CDATA[
The grass is greener {{{http://www.apache.org}over there}}.
]]></text>
</item>The text of a news item is actually APT formatted text, so all the formatting like links, text-formatting or lists can be used.
The formal definition for the items is available here, we also offer an XSD file to validate your news items with an XSD-capable editor.
There are three ways to include news items in your site.
All news items are rendered on a single page in reverse chronological order (latest first). This page is called news.html by default but this can be changed with a plugin setting (see below).
If you want to display some teasers on your web site cover page, you can include a Doxia macro that renders these teasers for you. Similar to Javadoc, the first full sentence (that ends with '. ' (dot - space)) is rendered as teaser.
This macro can be included as %{news|count=3} on an Apt page (note that the macro must start in the first column of your page!) or as <macro id="news" count="3" /> on an xdoc page (note that the id fields prevents you from including the macro twice on a page, this is considered a Doxia problem and might change in the future).
The news items are also available as an RSS 2.0 feed written as rss/news.rss (if you change the name of the news page above, this feed name will also change).
Due to the nature of the maven site build, all links of the site are relative. However, the RSS specification requires you to put absolute links into your feed. To make this possible, you must configure the final deploy location of your site in the news plugin (see below) if you want to use the RSS feed.
You must include both the plugin and the extension in your POM.
<project>
...
<reporting>
<plugins>
...
<plugin>
<groupId>org.apache.velocity.site</groupId>
<artifactId>velocity-site-news-plugin</artifactId>
<configuration>
<baseUrl>... your base URL here...</baseUrl>
<newsfile>... your news file name here ...</newsfile>
</configuration>
</plugin>
...
</plugins>
</reporting>
...
<build>
...
<extensions>
<extension>
<groupId>org.apache.velocity.site</groupId>
<artifactId>velocity-site-news-extension</artifactId>
<version>1.1.0</version>
</extension>
...
</extensions>
</build>
</project>Details can be found on the plugin and extension home pages.