I'm definitely +1 on AsciiDoc to replace Markdown.

I am not sure if there is a nice way to make a full coherent site out of
AsciiDoc pages; I haven't found a good way to link these pages with
something like a shared top navigation menu or so.
I end up creating a section (which shows up in the left-hand navigation
menu) which contains almost no text other than a link to another page.
For example: http://picocli.info/#_github_project  ,
http://picocli.info/#_issue_tracker  etc.
Workable but could be better.

On Sat, Apr 7, 2018 at 1:50 AM, Ralph Goers <ralph.go...@dslextreme.com>
wrote:

> I’ve had some trouble with Markdown as it seems the version supported by
> Maven is limited. I’m happy to switch to something that works better. That
> said, I am perfectly comfortable writing xdoc as well.
>
> Ralph
>
> > On Apr 6, 2018, at 9:29 AM, Matt Sicker <boa...@gmail.com> wrote:
> >
> > I've been using AsciiDoc for the Scala site, and I know others here have
> > used it as well. I was thinking it would be nice to standardize on it.
> > There is an asciidoctor plugin for maven-site-plugin, so we can use it
> with
> > our existing layout for now as well for Log4j.
> >
> > One major advantage for us is that you can easily include source file
> > snippets via macros. This would make our documentation more easily
> > maintainable as it wouldn't get out of sync. There could be some other
> > documentation generators explored later for Log4j plugins and such which
> > would be pretty neat, too. Another advantage is that asciidoc has its own
> > macros and such which are more useful than velocity.
> >
> > What do you think? If there aren't any objections, I'll supersede my
> > earlier markdown efforts with asciidoc instead.
> >
> > --
> > Matt Sicker <boa...@gmail.com>
>
>
>

Reply via email to