WG - Convert quarkus.io site to Roq

[holly-cummins]

Objective:

The main objective of this working group is to convert our Jekyll-based website to one built on Roq.

The Problem

Although Quarkus promotes a Quarkus-based static site generator, our own website uses a Ruby-based static site generator. As well as being reputationally awkward (why aren't we eating our own dogfood?), the Ruby-based generator has several practical limitations:

• It is difficult for the Java experts in the Quarkus team to make changes to the Ruby site code, to add dynamic features. This means many enhancements get ruled out at the design stage.
• The site build is temperamental. Local Ruby installations can break, and even the container-based build can break.

The proposed Solution

Add support to Roq for the range of features used in quarkus.io, and also add migration scripts for converting Jekyll to Quarkus. Once these are done, the quarkus.io site can be converted to Roq.

Definition of Done

This working group is complete when the live quarkus.io site is based on Roq.

Scope of Work

Visual changes to the website are outside the scope of this work. Conversion of some of the smaller satellite sites, such as https://quarkiverse.io/, could be in scope to act as prototypes. It is assumed that the quarkus.io contents that use asciidoc will continue to do so.

Organizing the Work

Communication and Transparency:

Issues will be split between the https://github.com/quarkusio/quarkusio.github.io and https://github.com/quarkiverse/quarkus-roq repositories. Zulip will be used for coordination.

Point of Contact:

@holly-cummins and @ia3andy

Expected Timeline:

I expect about six months is a suitable timescale.

As always, we will aim for an incremental delivery, although the final switch will be big-bang.

• Support building Roq sites in quarkus.io preview
• Develop conversion scripts
• Maintain a long-running PR, with scripts
• Fill functionality gaps in Roq
• (possibly) Split site and and ship some sub-sections as Roq, some as Jekyll

Potential Outcomes & Deliverables

The deliverables of this working group include:

• An easy-to-build, high-quality, dog-fooded website
• Technical improvements to Roq to support the range of features required for a site as complex as quarkus.io
• A set of documentation and scripts which will help other people do Jekyll to Roq conversions

Existing issues

• Old site converter to Roq quarkiverse/quarkus-roq#366
• Need docs page on converting to Jekyll quarkiverse/quarkus-roq#780
• i18n Support quarkiverse/quarkus-roq#650
• Roq Plugin AsciiDoc Java version ignores admonition blocks quarkiverse/quarkus-roq#516
• support asciidoctor page variables quarkiverse/quarkus-roq#335
• Support for sharp integration and image resizing quarkiverse/quarkus-roq#107

[omatheusmesmo]

Let's build this together!

[maxandersen]

This should include answers/solutions to:

• how to deal with all the l10n localized sites (cn,jp,es,etc)
• impact of productization of docs
• consider split of website from docs
• multiversion archival of docs

IMO if done right it wont have to be a big bang - but lets see how far we can get.

My main recommendation is to not try and make roq do everything; lets also keep options on table to split the approaches up.

[omatheusmesmo]

Maybe we can start here: quarkiverse/quarkus-roq#650

[cescoffier]

I will create the WG on monday.

[cescoffier]

WG started: WG - Convert quarkus.io to Roq (view)