migrate documentation to Antora (jetty-10.0.x)

[mojavelinux]

No description provided.

[sbordet]

@mojavelinux I could build the documentation, but the plantuml diagrams are not rendered.

I do have dot installed on my system.

For example:
https://webtide.github.io/jetty.website/docs/jetty/10/operations-guide/protocols/index.html#http2

Before and after the paragraph starting with Nowadays there are 2 diagrams, but they are not rendered as they make an external request to kroki.io?

For the locally built documentation, the diagram source code is rendered instead.

Can we build the diagrams locally, store the images locally, and render them in the documentation as local image files?

[mojavelinux]

Generating the diagrams is handled by Kroki via a remote requests. Relying on Kroki ensures you don't have to have any diagram tools installed on your machine. But the local branch preview does not load asciidoctor-kroki in order to make the preview as fast as possible. It could be added though. To do so, the playbook template at https://github.com/jetty/jetty.website/blob/main/lib/playbook-templates/per-branch-antora-playbook.yml must be modified.

First, asciidoctor-kroki needs to be added to the package line. Then, asciidoctor-kroki needs to be added to the list of asciidoc.extensions. If that is what you prefer, we can proceed with that change.

[sbordet]

I prefer the site to not perform any external request.

Last time I tried https://webtide.github.io/jetty.website/, kroki.io was down or super-slow, so the site kinda hung, and the diagrams were not there, so bad experience.

I can live with previews or local to remotely call kroki.io, but the "production" site should have local images and not do any external request.

We already require a bunch of tools to build the website anyway, so one more is ok.

Please proceed with the change. Thanks!

[mojavelinux]

I can live with previews or local to remotely call kroki.io, but the "production" site should have local images and not do any external request.

Currently, there's no other option when using Antora unless you set up your own kroki server. Even then, Antora has to make calls to the kroki URL (whether it is your own or the shared one) to generate diagrams.

[mojavelinux]

Please proceed with the change. Thanks!

See jetty/jetty.website#27

[sbordet]

Currently, there's no other option when using Antora unless you set up your own kroki server. Even then, Antora has to make calls to the kroki URL (whether it is your own or the shared one) to generate diagrams.

I'm not sure where this limitation come from?
Asciidoctor can generate the diagrams locally, so I would imagine Antora would just delegate to it?

[mojavelinux]

I'm not sure where this limitation come from?
Asciidoctor can generate the diagrams locally, so I would imagine Antora would just delegate to it?

Asciidoctor cannot generate diagrams on its own. It relies on extensions to do that. When using Asciidoctor (Ruby) or AsciidoctorJ, that responsibility is handled by Asciidoctor Diagram. Asciidoctor Diagram generates diagrams using local tools. However, Asciidoctor Diagram is not available for Asciidoctor.js, which is what Antora uses. That's why in Antora, we use Asciidoctor Kroki. The reason Asciidoctor Kroki works across all environments is because it delegates to a service (the Kroki service) to generate the diagrams. This is currently the only way to generate diagrams when using Antora.

[mojavelinux]

Given how Kroki is configured by default, the build won't make any requests to Kroki.io. It will only happen when the page that contains the diagram is viewed. It's a remote image.

[gregw]

@mojavelinux @jmcc0nn3ll Sorry if I'm late to the review party... but I've just gone through the new website as running https://jetty.github.io/jetty.website/ and here is some feedback:

• The home page has contents in the top right, whilst the Documentation pages have the contents on the left boundary. We should be consistent and I much prefer the left boundary approach.....

  • Oh I see, there are also Contents pages on the right of the Documentation, but only on pages that have sections. So the left is a menu and the right is page contents? Maybe we need a left Menu on the home page for Documentation, Github, Eclipse, Webtide etc.

• There are no links out from the homepage to: the blogs; eclipse; github; webtide; etc. There is one buried link to the documentation, but it is not very prominent. I don't think we need a paragraph saying how good our blogs are, we just need an entry in the Contents saying "Jetty Blogs" that is a link directly to the blog page. Likewise we need prominent links in the Contents to Documentation, Gitub project, Webtide. The home page is our landing page and it has to be easy to navigate from.... in fact the primary purpose of that page should be to navigate to other pages... few will read the text.

• On the front page of the Jetty Documentation, in the resources column can we add links to issues

• The documentation pages do not use wide windows. All the text is in a narrow column with lots of whitespace either side.

• On a mobile device, it is kind of strange that the left menu is collapsed, by the the page contents is always listed. Can we make the Contents display collapsed on a small device, as often you only need the contents links to skip the contents that fills the first page.

• The titles for the top level pages of Jetty-10, Jetty-11 and Jetty-12 should have the version number in the title. e.g on https://jetty.github.io/jetty.website/docs/jetty/10/index.html it is only apparently we are looking at Jetty-10 by the small selector top right and by reading the body of the first line. Put it in the title, so it will appear on the left menu, top of the page and tab/page title.

[mojavelinux]

This not the correct place to be providing feedback. This is an automated PR generated by the migration. Discussions should be directed to the issues in the jetty.website repository.