The static site generators are nice but there is always some ramp-up, a barrier to contribution whereas the mvn site generation is integral. I just tried the reflow skin cited above on another project and while 'raw', it has good doc and addresses the main problem w/ mvn sites, their datedness. S
On Mon, Apr 22, 2019 at 7:50 AM Allen Wittenauer <[email protected]> wrote: > > > > On Apr 21, 2019, at 6:57 PM, Sean Busbey <[email protected]> wrote: > > > > I really like editing and authoring in markdown. Is there a maven site > > plugin to allow that or are we back to some xml stuff? > > Settings and themes are XML and content can be in anything that > doxia supports including markdown. I helped convert Hadoop’s mvn site > driven documentation to markdown a few years ago. (They still use that > horrible fluido skin though.) > > I have two big reservations around switching to mvn site: > > * There is a good chance we’ll want to use a custom maven > skin, which could end up in us maintaining it as part of the Yetus source > tree. This isn’t necessarily a bad thing, but I’m not sure we want to be in > that business. > > * doxia tends to be a bit flaky and crash in surprising > ways. The Hadoop documentation didn't have a lot of complexity and yet it > still broke it in surprising ways. But that was also before doxia moved > from pegdown to flexmark . > > There are lots of other choices for static site generators. The > big con I can see for using one of those is that we’ll still be maintaining > code to push the javadoc, etc, into it.
