• Articles
  • /
  • Building a personal site with Maven
 

Building a personal site with Maven

Intro

Having a website is nowadays almost a prerequisite when entering the internet. Everyone, from kids to seniors alike, has a website. Granted, there are some awful monsters out there (thank you Frontpage and Word...), but most of the site are at least browsable.

Another buzz-word is 'dynamic web pages'. Technologies like PHP, ASP and others like it have sprouted like mushrooms out of the rich soil the internet is. But one has to wonder, do we always need that degree of dynamics? Especially in the IT world, where a programmer's time is precious, sometimes we just want to be lazy and still have a nice site to boast with :). Maven

Maven is well known among Java developers. It's rising to be the best build system around, if not allready. Now what does that has to do with websites? Well, Maven supports site generation for it's projects. Developers can easily add content, and when they build their website, Maven will build the website for them.

Sometimes, you don't want a dynamic site. If you're building a website with static pages, you can resort to simple HTML. But, we're Java developers, not HTML web designers. We don't want to know HOW we're going to present our contents, we want to write those contents and don't care about layouting and such. Prequisites for this article

  • You have Maven 2 installed. If not, it's easily downloaded here

    The latest version at the time of writing this is 2.0.6. On instructions to install Maven, there are plenty of tutorials on the web. Use Google

  • You have basic knowledge of Maven 2, which means you know what a POM is. If you do not, Mergere has a great book on Maven 2: Better builds with Maven

Let's get started

First, we want make a simple site. Use Maven's archetypes, you can easily make a simple, yet complete site. Just use the following command:

mvn archetype:create 
   -DgroupId=mygroup 
   -DartifactId=mywebsite
   -DarchetypeArtifactId=maven-archetype-site-simple

After executing this command, Maven will have placed a mywebsite subdirectory in your current directory.

What is in this directory:

  • your pom.xml
  • a src/site directory, which houses all your content.

    Inside you can come across the following directories:

    • apt : this houses your content in the APT (almost plain text) format. Quick and easy to use. Recommended for this usage.
    • fml : this houses your content in the FML format. Especially used for creating FAQ documents, so mostly useless in our application.
    • xdoc : the XML brother of APT. Your content can be nicely put into a XML jacket, although my opinion is that it's too time-consuming.
    • resources : this is a special one. Maven won't compile these into HTML, but put them directly into your target folder. In here you'll put extra images and such you want to use in your content.

Now go into your mywebsite folder and execute the following command:

mvn clean site

When using the 'site' goal, Maven will start building your site using the content. The 'clean' part erases the previous generated site, which ensures you site is fully up to date. Your generated HTML files will be in the mywebsite/target/site folder. Right now you'll see a lot of html files we really don't need, especially project related stuff. We'll get rid of those shortly.

Really nice is the following command:

mvn clean site:run

This will clean your site, build it from scratch and start a webserver that houses your generated site (default URL is http://localhost:8080). To stop the webserver, simply stop the Maven command using CTRL + C.

You'll see Maven had generated the standard Maven site. Ugly isn't it, but it's a site, and we haven't even done anything.

Cleaning up the default files

Maven automatically generates the default set of reports for standard projects. We aren't building any projects, just our site, so we want to get rid of those reports. It'll also speed up our site build in the progress.

Open your pom.xml and add the following lines (doesn't matter where, as long as it is in the project root tag, although I recommend sticking to the standard tag order defined by Maven.

<reporting>
 <excludeDefaults>true</excludeDefaults>
 <plugins>
  <plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-project-info-reports-plugin</artifactId>
   <reportSets>
        <reportSet>
         <reports />
        </reportSet>
   </reportSets>
  </plugin>
 </plugins>
</reporting>

Now build your site. The index.html will now be the lonely occupant of your site. Mission accomplished

Changing the look of your site

The standard maven skin is certainly not suited for personal website use. It's cold and overly functional. People aren't attracted to your site, so nobody will ever go past your homepage.

To address that issue, Maven has skin support. You can easily switch the look of your site, depending on the skin you use. Some skin are to be found on the web, although most of them are like the standard one, cold and unpersonal. Except one. EmbedChat also has a Maven site, and a heavily customized skin. A really nice one above all! To build a skin is out of scope for this article, but I'll gladly recommend the EmbedChat creator's article on Maven skinning found here.

This site's skin is based on the Embedchat skin, combined with some styling of Daisy CMS for clarity, since I use that system on a daily basis.

To simplify things, I've made my own simple skin based on the one from EmbedChat. The skin itself is also a Maven project, so just unzip the folder and start the following command in the same folder as it's pom.xml:

mvn install

Voila, the skin is installed. Now we have to configure our site to use our new skin. In the mywebsite/src/site folder you'll find a site.xml file. This describes the menu on the left on every page generated by Maven. You can also set the skin here.

Just add the following lines directly under the project tag (not in the body tag):

<skin>
 <groupId>be.doclo.skins</groupId>
 <artifactId>standard-skin</artifactId>
 <version>1.0</version>
</skin>

Now build your site again. If all has gone well, you'll now see a completely different site layout. A lot nicer, isn't it? You can experiment with the css file of the skin or for people with even more time, edit the site.vm file that builds the HTML files from the xdoc and apt files. I bet you can whip up your own great looking skin in under half an hour! Changing the the css and the images will change your site tremendously, giving it your own identity.

Adding content

Adding content is easy. Just create APT files in the src/site/apt folder (or XDoc files in the src/site/xdoc folder). You can use subdirectories if you want, Maven will respect the directory layour when building your site. Linking your pages in the menu

As mentioned before, the site.xml also contains your menu. You can add menu's and items here. Don't forget, use the .html links here, f.e. if you have a src/site/apt/somedir/somefile.apt file, the link you have to use as an item is somedir/somefile.html.

 
2009 © Lieven Doclo