Velocity Site News

The Velocity Site News plugin 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.

Creating news items

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.

Displaying news items

There are three ways to include news items in your site.

Display as a page

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).

Display as part of a page

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 name="news" id="news" count="3" /> on an xdoc page (note that the id field must be changed if you want to include the macro multiple times on a page).

Display as RSS feed

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.

Adding the Velocity Site News Plugin to your POM

Due to the fact that Maven-2 is an incredible flexible platform and that the plugin needs to access three different parts of the maven build cycle (site building, reporting and site rendering), the plugin must be added in three different locations to your POM:

  • As a reporting plugin to generate the news report
  • As a dependency to the site plugin to allow access to the Doxia Macro.
  • As a build plugin to read the news file
    <project>
    ...
      <reporting>
        <plugins>
          <plugin>
            <groupId>org.apache.velocity.site</groupId>
            <artifactId>velocity-site-news-plugin</artifactId>
            <configuration>
              <baseUrl>http://velocity.apache.org/</baseUrl>
            </configuration>
          </plugin>
        </plugins>
      </reporting>
    ...
      <build>
        <plugins>
          <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <dependencies>
             <dependency>
              <groupId>org.apache.velocity.site</groupId>
              <artifactId>velocity-site-news-plugin</artifactId>
              <version>1.2.0-SNAPSHOT</version>
             </dependency>
            </dependencies>
          </plugin>
    ...
          <plugin>
            <groupId>org.apache.velocity.site</groupId>
            <artifactId>velocity-site-news-plugin</artifactId>
            <executions>
              <execution>
                <goals>
                  <goal>pre-site</goal>
                </goals>
              </execution>
            </executions>
            <configuration>
              <newsfile>news</newsfile>
            </configuration>
          </plugin>
        </plugins>
      </build>
    ...
    </project>

Configuration of the reporting plugin

  • baseUrl - As RSS feeds must have an absolute path for their links and the maven site build tries to use relative links everywhere, you must configure the final deployment location of your site here so that the RSS generator can put absolute links into the RSS feed. The baseUrl should end with a /.

Configuration of the news plugin

  • newsfile (default is news) - The base name to look up the XML file to parse and to generate the full news page and the RSS feed. The default looks for src/site/news.xml, generates news.html and a feed under rss/news.rss.