The "markdown" syntax for marking up text is something which the mvn site build can be set up to support alongside the existing APT formatted text.
Markdown offers many advantages
- It's more widely understood.
- There's tooling support in various text editors (TextMate, an IDEA plugin and others)
- It can be directly rendered in github
- the .md files can be named .md.vm to trigger velocity preprocessing, at the expense of direct viewing in github
feature #3 is good as it means that you can point people directly at a doc via a github mirror, and have it rendered.
I propose adding the options to Maven to enable content be written as .md and .md.vm files in the directory src/site/markdown. This does not require any changes to the existing .apt files, which can co-exist and cross-reference each other.