Re: APT vs Markdown formats for site docs

[David Jencks-4]

Asciidoctor Maven Tools is the more supported way of using Asciidoctor from maven, either directly or through Doxia.

https://docs.asciidoctor.org/maven-tools/latest/ <https://docs.asciidoctor.org/maven-tools/latest/> (docs)
https://github.com/asciidoctor/asciidoctor-maven-plugin <https://github.com/asciidoctor/asciidoctor-maven-plugin> (GitHub)

AsciiDoc support  in Jekyll using jekyll-asciidoc is quite good, and GitHub is rather jekyll-friendly. You do have to build the site yourself, GitHub’s built in AsciiDoc rendering is somewhat crippled for incomprehensible reasons.  I’m now the primary maintainer of jekyll-asciidoc so issues may receive prompt attention.

I think Antora is incomparable, and would certainly produce fabulous results properly used for maven documentation, but with the  investment in Doxia organization that may be a better choice.

David Jencks

> On Feb 1, 2021, at 3:34 AM, Andres Almiray <[hidden email]> wrote:
>
> FWIW Doxia supports Asciidoc pretty well. You just have to add an extra
> dependency for it to find Asciidoctorj, as demonstrated at
>
> https://github.com/kordamp/pomchecker/blob/master/pom.xml#L200-L227
>
> You can mix all kind of supported formats if needed. Or use only asciidoc,
> the choice is yours ;-)
>
> Cheers,
> Andres
>
> -------------------------------------------
> Java Champion; Groovy Enthusiast
> http://andresalmiray.com
> http://www.linkedin.com/in/aalmiray
> --
> What goes up, must come down. Ask any system administrator.
> There are 10 types of people in the world: Those who understand binary, and
> those who don't.
> To understand recursion, we must first understand recursion.
>
>
> On Mon, Feb 1, 2021 at 12:29 PM Artem Krosheninnikov <
> [hidden email]> wrote:
>
>> I agree that there are several implementations thus it may be not a good
>> choice.
>>
>> FML looks very ancient from my point of view but asciidoc is more or less a
>> standard format in docops community.
>>
>> It's not that everything should be immediately converted to another format,
>> just trying to understand whether apt is convenient for all and is a
>> standard for all maven projects.
>>
>> пн, 1 февр. 2021 г. в 13:32, Benjamin Marwell <[hidden email]>:
>>
>>> Markdown is not a "standard" or "standardized".
>>> Even worse, different implementations have different feature sets.
>>> Thus my -1 for md.
>>>
>>> But another format might be feasible, really. fml looks verbose.
>>>
>>> Asciidoc might be a sane choice here. It was specially designed for
>>> technical documentation and
>>> has neat features which are handy for exactly those cases.
>>> Besides, it is also supported on GitHub.
>>>
>>> ---
>>>
>>> A quick check revealed there was no such discussion in the last 12
>>> months on the mailing list.
>>>
>>> - Ben
>>>
>>>
>>
>> --
>> Sincerely yours,
>> Krosheninnikov Artem.
>>