maven - 使用 Maven 创建用户指南文档

Question

我需要编写和构建易于维护、美观、易于更改 pdf 和 html 5 格式的文档。源格式必须易于编辑。这个 maven 插件必须支持我的公司组织（字体、颜色、图片等）、TOC 生成、不同文件中的章节分离、图像文件的集成、将代码片段放入文档中的简单方法。我有 Maven 构建，我想知道目前最好的决定是什么？

我正在调查两个选项：

• Doxia - 使用 md(markdown) 作为输入格式。有 WSWG md 免费编辑器，支持很多前面提到的东西等。它的工件需要外部 repo。
• Asciidoctor - 使用 asdcii doc 作为输入格式。支持使用片段等进行模板化。

使用这个插件有什么好处和坏处？还有其他好的解决方案吗？

Answer 1

从我尝试先用 Doxia 再用AsciiDoc构建文档的过程中，我意识到 Asciidoc 更好。它允许

• 使用yaml文件轻松进行样式设置。默认样式也很好。
• Asciidoc 作为一种标记语言有很好的文档记录：Uder Guide AsciiDoc
• 拥有优秀的在线编辑器，语言比 markdown 更强大，与xml格式相比更容易编写。
• 与 Maven 和 ascii doc 一起使用时的好例子，并且易于理解的配置。