Maven: The Complete Reference - 10.3. Customizing the Site Descriptor |
|
When you add content to the site, you are going to want to modify the left-hand navigation menu that is generated with your site. The following site descriptor customizes the logo in the upper left-hand corner of the site. In addition to customizing the header of the site, this descriptor adds a menu section to the left-hand navigation menu under the heading "Sample Project". This menu contains a single link to an overview page. An Initial Site Descriptor. <project name="Sample Project"> <bannerLeft> <name>Sonatype</name> <src>images/logo.png</src> <href>http://www.sonatype.com</href> </bannerLeft> <body> <menu name="Sample Project"> <item name="Overview" href="index.html"/> </menu> <menu ref="reports"/> </body> </project>
This site descriptor references one image. This logo.png image should be placed in ${basedir}/src/site/resources/images. In addition to the change to the site descriptor, you’ll want to create a simple index.apt page in ${basedir}/src/site/apt. Put the following content in index.apt, it will be transformed to the index.html and serve as the first page a user sees when they come to your project’s Maven-generated web site. Welcome to the Sample Project, we hope you enjoy your time on this project site. We've tried to assemble some great user documentation and developer information, and we're really excited that you've taken the time to visit this site. What is Sample Project Well, it's easy enough to explain. This sample project is a sample of a project with a Maven-generated site from Maven: The Definitive Guide. A dedicated team of volunteers help maintain this sample site, and so on and so forth. To preview the site, run $ mvn clean site $ mvn site:run Once you do this, load the page in a browser by going to http://localhost:8080. You should see something similar to the screenshot in Figure 10.2, “Customized Sample Project Web Site”. To customize the graphics which appear in the upper left-hand and
right-hand corners of the page, you can use the Adding a Banner Left and Banner Right to Site Descriptor. <project name="Sample Project"> <bannerLeft> <name>Left Banner</name> <src>images/banner-left.png</src> <href>http://www.google.com</href> </bannerLeft> <bannerRight> <name>Right Banner</name> <src>images/banner-right.png</src> <href>http://www.yahoo.com</href> </bannerRight> ... </project>
Both the To customize the contents of the navigation menu, use the Creating Menu Items in a Site Descriptor. <project name="Sample Project"> ... <body> <menu name="Sample Project"> <item name="Introduction" href="index.html"/> <item name="News" href="news.html"/> <item name="Features" href="features.html"/> <item name="Installation" href="installation.html"/> <item name="Configuration" href="configuration.html"/> <item name="FAQ" href="faq.html"/> </menu> ... </body> </project>
Menu items can also be nested. If you nest items, you will be creating a collapsible menu in the left-hand navigation menu. The following example adds a link "Developer Resources" which links to /developer/index.html. When a user is looking at the Developer Resources page, the menu items below the Developer Resources menu item will be expanded. Adding a Link to the Site Menu. <project name="Sample Project"> ... <body> ... <menu name="Sample Project"> ... <item name="Developer Resources" href="/developer/index.html" collapse="true"> <item name="System Architecture" href="/developer/architecture.html"/> <item name="Embedder's Guide" href="/developer/embedding.html"/> </item> </menu> ... </body> </project>
When an item has the |