Using XWiki to build a documentation website

Version 17.1 by Ecaterina Moraru (Valica) on 2017/08/10

Aug 10 2017

This blog post is not published yet.

Vincent wrote a blog post last week about XWiki vs. statically-generated site, showcasing the advantages that XWiki is bringing, like structured content, dynamic operations on top of it and many other features.

At the end of the article he mentioned that it would be great if more open source forges, such as the Apache Software Foundation or the Eclipse Foundation, would try to see if XWiki would fit their needs. Since we are a big open source family I tried to imagine what that would look like. 

There are over 350+ open source initiatives managed by the Apache Software Foundation and many of them are used inside XWiki (Tomcat, Velocity, Groovy, Tika, Maven just to name a few). Most of the projects use their website to document their APIs and releases or to encourage users to contribute back to the project. 

I've tried to analyse and find the common needs the projects were having, and think about a skin that would incorporate them. Once you have the skin it's pretty easy to apply different color themes on top, change the logo and the content, and adapt it for any project you want.

Most of the projects needed two layouts: one for the landing page and another for the documentation / content areas. I've chosen Apache Maven as an example for this exercise since they are one of my favorite and I'm using them at least once a week (so thank you for your wonderful project). 

Landing page layout
maven_homepage_partial.png

Documentation layout
maven_doc_partial.png

The navigation was mostly done with a menu and a tree on the left side for the topics. All projects included a part where they showcase their affiliation with Apache.

Landing page layout
maven_menu1.png

Documentation layout
maven_menu2.png

If you have good bones than styling comes easily. You can experiment different banners or color themes until you find something that represents you.

Once you have the skin to visually represent the information, you can easily integrate it inside an XWiki Flavor. A Flavor's utility come from usage so I can only assume the needs, but I imagined all projects would need an integrated search, versioning, blame and changes view, backup, managing the public and private pages, etc.

XWiki is not just about styling and making things pretty easily, but it's power comes from being an extensible platform. Because of its extensibility you could easily add a Release Notes application, GitHub Stats or any other needed extension.

Hope you've liked this design exercise on top of XWiki and using content from Apache Maven project. If someone from Maven is reading this and likes the design proposal for the homepage or the documentation layout feel free to use them and create a skin based on it. 

If you find this use case interesting let us know. In the future we might want to create a Documentation Flavor, with the above features, so the feedback is appreciated.

For questions, feedback or improvements suggestions find us on forum.xwiki.org,  @xwikiorg or my personally at @evalica.

Tags:
    

Get Connected