Commons Committers Documentation
All commons website should use maven to build. At present, the required version is v1.0.2 with the plugins described in commons-build/pluginUpdate.txt.
Previously a common site layout was achieved by linking to commons-build. This was achieved via relative file paths, and a requirements to checkout commons-build parallel with your component. This meant that a downloaded release could not be built by users. A new mechanism (March 2006) changes this.
Sharing the style
The CSS style is shared by having a single css file (project.css) in the component's xdocs/style directory. The project.css file imports the shared file http://jakarta.apache.org/style/jakarta-maven.css.
This file can be updated as and when required, and all websites will immediately update. This direct http link means that downloads can be built without a reference on commons-build previously found in maven.xml and project.properties. Previously commons-site.jsl was used - now the standard maven site.jsl is used.
The only time a user will not see the commons styled website is if they have a local copy of the site and they are currently offline. In that situation, they will see the maven standard colours (grey and red headers etc.)
This technique can be used to add a logo such as the ApacheCon easily. Simply add a background image and padding-top to the leftColumn.
Sharing the navigation
The commons community has expressed a desire to share some menu items across all components. Previously this was achieved by including a relative file path URL DOCTYPE at the top of navigation.xml and a single common-menus entity.
The new structure uses the same basic entity idea, but removes the relative dependency on commons-build. Instead, an absolute dependency on http://commons.apache.org/build/maven-build.dtd is added. To accommodate this, the entity must be changed from common-menus to commons.
As part of this change, the included section has been greatly simplified. Only items truly worth sharing have been shared.
Converting from commons-build relative
To convert a website to the new design, perform the following steps:
Delete all css files from xdocs/style
Add a project.css file to xdocs/style identical to http://svn.apache.org/viewvc/commons/proper/io/trunk/xdocs/style/project.css?rev=385205&view=markup
In maven.xml, remove the commons-build section (clearly indicated)
In project.properties, remove the maven.xdoc.jsl line
In navigation.xml, change the DOCTYPE line URL to http://commons.apache.org/build/maven-build.dtd
In navigation.xml, change the entity from &common-menus; to &commons;
In project.xml, make sure that the organization logo is the correct one. It should look like this:
<project> ... <organization> <name>The Apache Software Foundation</name> <url>http://commons.apache.org</url> <logo>http://commons.apache.org/images/logo.png</logo> </organization> ... </project>
In addition to these changes, you may wish to examine the lang/io sites to see if you can group your own menu structure in navigation.xml to be similar. The main aspect is to separate the user information from the developer information.