Evaluate alternative solution

[SchettlerKoehler]

Currently, the docs are generated with asciidoctor and this extension https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/multipage-html5-converter.rb This was and is a proof of concept for multipage generation with asciidoctor. This extension was also adapted at some points to fit the needs of devonfw. The version that is currently used with all the cahnges can be found here: https://github.com/devonfw/devonfw.github.io/blob/develop/asciidoctor-extensions/multipage-html5-converter.rb Unfortunately, the use of this proof of concept version prevents us from moving to a newer asciidoctor version because it is not compatible. The good news is, that it looks like some people have picked up this proof of concept and transformed it into something more useable: https://github.com/owenh000/asciidoctor-multipage

As the switch to antora could be very expensive and maybe does not even solve our problems or will create new and different problems, we should evaluate if moving to a new asciidoctor version and the stable extension makes our lives easier.

Acceptance criteria:

• It is clear if the switch to the new extension and the new asciidoctor version improves the situation.
• It is clear if the changes done to the currently used extension can also be achieved with the new version somehow or if the change is no longer nessessary.
• There is a proof of concept pipeline implementation with the new version.

[maybeec]

Please also check the devon4j repository as one of the first repos as this currently brings a lot of issues as the asciidoc files are managed in subdirectories which seems to be a problem in link creation for the current multipage version in use.

[mustafaokyay]

Done:

• Learn the Syntax
• Raw Integration of devon4j fork (documentation)
• Navigation bar working (leveloffsets needed to change)

Next Steps:

• The build steps are made like the dude owen, change it to our build style.
• The order of the files and their leveloffsets need to be checked, some are still in the wrong order.
• Some pictures are not showing up properly. Investigate the problem.
• Check if our extension is working with this solution.
• Apply devonfw styling
• Check for show stoppers

Not Working:

• footnotes are not supported.
• Asciidoctor's --template-dir option is currently not supported

Current status can be found here: https://github.com/mustafaokyay/asciidoctor-multipage