Create User Guide documentation with Maven

Question

I need to write and build easy maintainable, goodlooking, esay to change documentation in pdf and html 5 format. The source format must be easy to edit. This maven plugin has to support my company organziation theam(fonts, colors, pictures etc.), TOC generation, separation of chapters in different files, integration of images files, easy way to put code snipets in the documentation. I have Maven build and I was wondering what is the current best descision to do that?

I was investigate two options:

• Doxia - using md(markdown) as input format. There is WSWG md free editor, support a lot of the aforemention stuffs, etc. Need external repo for its artifacts.
• Asciidoctor - use asdcii doc as input format. Support templating using fragments etc.

What are the advantages and disadvantaes of using this plugins? Are there any other good solutions?

Answer 1

From my attempts to build the documentation first with Doxia and then with AsciiDoc I realised that Asciidoc is the better. It allows

• Easy styling using yaml files. Default styling is also very good.
• Asciidoc as a mark-up language is very good documented: Uder Guide AsciiDoc
• Has good online editors and the language is more powerful than markdown for example, and easier to write in comparison to the xml format.
• Good examples when using with Maven and ascii doc and easy to understand configurations .