Include AsciiDoc files as website input sources

[rlenferink]

Right now in the Celix source tree there are 2 different input formats: Markdown and AsciiDoc. The Markdown files are already processed by Hugo but the AsciiDoc files are not.

It seems that Hugo is able to handle AsciiDoc as input files as well, see https://gohugo.io/content-management/formats/#list-of-content-formats

Test whether this works and whether the output is available on the website.

AsciiDoc input sources:

• https://github.com/apache/celix/tree/master/bundles/pubsub/doc
• https://github.com/apache/celix/tree/master/bundles/cxx_remote_services/doc

PR apache/celix#363 adds another AsciiDoc file for PushStreams, when merged that file should preferabbly be checked as well.

[pnoltes]

Note that GitHub also supports view of asciidoc.

I think it would be nice to align the Celix documentation to 1 format: markdown or asciidoc and because asciidoc is more flexible I would prefer asciidoc.

Also note that the CLion / IntelliJ asciidoc plugin support transformation of markdown to asciidoc, which should make aligning the documentation format more easy .. if we move to asciidoc.

[rlenferink]

I think it would be nice to align the Celix documentation to 1 format: markdown or asciidoc

I agree

and because asciidoc is more flexible I would prefer asciidoc.

Just for my information: what functionality do we want for Celix that AsciiDoc is better at than Markdown?

It seems that Hugo supports AsciiDoc (see https://gohugo.io/content-management/formats/#list-of-content-formats ) when AsciiDoc is installed, but I would suggest to do some testing upfront to ensure that things will continue working

[PengZheng]

Just for my information: what functionality do we want for Celix that AsciiDoc is better at than Markdown?

I quote the following from a comprehensive article Compare AsciiDoc to Markdown:

AsciiDoc isn’t stuck in a game of whack-a-mole trying to satisfy publishing needs like Markdown. Rather, the AsciiDoc syntax was explicitly designed with the needs of publishing in mind, both print and web.

An extra little advantage of using AsciiDoc is its inline plantuml support. Unfortunately, GitHub does not support plantuml
natively. We need some extra setup to workaround this: https://docs-as-co.de/news/plantuml-markdown-code-gitlab-github-integration/

Either AciiDoc + Plantuml or Github flavored Markdown + Mermaid, I am not sure which one we should pick. @pnoltes