Using XWiki to build a documentation website

Last modified by Ecaterina Moraru (Valica) on 2017/08/11

Aug 10 2017

Vincent wrote a blog post last week about XWiki vs. statically-generated site, showcasing the advantages that XWiki is bringing over a static website, 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.

maven_menu1.png

maven_menu2.png

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 its power comes from being an extensible platform. Because of its extensibility you could easily add a JIRA Macro, 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. Note that we would love for XWiki to be used for the Apache Software Foundation (ASF) and we're prepared to lead the initiative and provide all the help should the ASF be interested in trying out XWiki! emoticon_smile

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 personally at @evalica.

Tags:
Created by Ecaterina Moraru (Valica) on 2017/08/10

Get Connected