Render Kroxylicious AsciiDoc on the website with Jekyll

[gracegrimwood]

It would simplify things immensely if the Kroxylicious AsciiDoc files were rendered via this repository and its workflows, using Jekyll (i.e. with the jekyll-asciidoc plugin) rather than being rendered separately via the workflow in the Kroxylicious repository. However, we don't want to move the AsciiDoc files out of the Kroxylicious repository because it is easier to keep these docs up to date when they live closer to the code.

Rendering the AsciiDoc via this repository would mean that styles can be applied uniformly across the site (rather than the very different styles currently used) and would make linking back to the main site from the docs page much easier.

This rendering could easily be added as a step in the build job before the "Build with Jekyll" step, the only question is how to get the files from the Kroxylicious repository to this one so they can be rendered. There are two ways I can think of, each with pros and cons:

1. Push AsciiDoc files into this repository from the Kroxylicious repository via GitHub Actions (this is how Strimzi does it), i.e. after every push to main
   • ✅ The site would update every single time a change is made, so nothing is missed
   • ❌ Pushes may happen too frequently (i.e. it might try to push even if no AsciiDoc changes have been made)
   • ❌ We would end up storing the same docs files in two different locations (this repo and the Kroxylicious repo)
   • ❌ We would have to give a bot the ability to push to this repository
2. Pull AsciiDoc into the GitHub Actions image at build time
   • ✅ No need to store the same docs in two different repos
   • ✅ No extra permissions for workflows or bots required, we can just clone the Kroxylicious repo
   • ✅ Don't necessarily need to modify the workflow for the main Kroxylicious repo, so there's no risk of breaking something important (like the release pipeline)
   • ✅ We could use the repository_dispatch trigger to fire off the website build pipeline after every merge to main in the main Kroxylicious repository, which would keep the website up to date whenever a change is made to the AsciiDoc.
   • ❌ There is no straightforward way to only call the repository_dispatch endpoint when AsciiDoc updates are merged (rather than whenever anything is merged in the Kroxylicious repository), so we could end up firing off the build pipeline way more often than we would prefer
   • ❌ The repository_dispatch endpoint appears to have a somewhat unstable API and much of the documentation for it references prior (incompatible) versions of this endpoint
   • ❌ The repository_dispatch trigger is asynchronous, so website builds would not necessarily be fired off instantly, and there are issues with using GITHUB_TOKEN to call it (have to use personal access tokens to do so, which isn't great), and it can only run on the main branch so we can't do anything terribly sophisticated with it
   • ❌ If we don't use the repository_dispatch trigger, the site would only update when a push is made to main in this repository, or when the workflow is manually triggered, so it may not always be up to date

(Assigning this to myself as an easy task to occupy myself with while recovering from surgery 🙂 )

[gracegrimwood]

I'm going to work on getting the AsciiDoc to build with Jekyll for now, and we can discuss how best to get the AsciiDoc files into the Jekyll build on the weekly sync call tonight

[gracegrimwood]

Update post-sync call: we're going to only render the release docs on the website using method 1 (but do it on release and not on push to main), and then the latest docs will continue to be rendered in the main Kroxylicious repository.