Render Kroxylicious AsciiDoc on the website with Jekyll

[gracegrimwood]

Adds rendering of the docs using jekyll-asciidoc (#44).

Also modifies site-wide code highlighting styles to better align with the highlighting used by the development docs (it has better contrast and readability than what we were using before).

Some notes:

• Code highlighting doesn't work on the docs unless the source highlighter is changed to rouge in the AsciiDoc files (in index.adoc and custom-filters.adoc), and Jekyll will produce a non-fatal warning on build if this is not done. Alternatively we could install pygments specifically for the AsciiDoc pages, but I thought it was preferential to not have two code highlighters installed (Jekyll uses rouge).
• If we want to add a version number to the page to indicate which version's docs we're rendering, we would change that in the AsciiDoc too (i.e. by changing the title in index.adoc).
• The nav now directs to this new docs page, which then contains a link to the development docs. We could probably make that nav tile into a dropdown with both links, but I wasn't sure I wanted to tackle the CSS for that in this PR.
• The docs files in this PR were sourced from the v0.5.1 tag in the Kroxylicious repository.

[gracegrimwood]

There are issues with the workflow rendering the a2s images. Marking as draft until I fix that.

[gracegrimwood]

Fixed workflow so AsciiToSVG images now render correctly. I have had to add Go to the workflow to do this.

[SamBarker]

I think that looks a lot better when I check locally.

Excuse the huge screenshot but I think its helpful to provide a side by side comparison.

Code highlighting doesn't work on the docs unless the source highlighter is changed to rouge in the AsciiDoc files (in index.adoc and custom-filters.adoc), and Jekyll will produce a non-fatal warning on build if this is not done. Alternatively we could install pygments specifically for the AsciiDoc pages, but I thought it was preferential to not have two code highlighters installed (Jekyll uses rouge).

Lets update the adoc to use rouge. One formatter to rule them all....

If we want to add a version number to the page to indicate which version's docs we're rendering, we would change that in the AsciiDoc too (i.e. by changing the title in index.adoc).

Also worth doing, but I was expecting the website to maintain docs for each version not just a single copy of the current release docs. So /docs/0.5.0 & /docs/0.3.0 would work was my expectation. That said I'm fine with this PR just fixing the rendering and sorting versioning in a separate PR.

[SamBarker]

Local builds also show a couple of warnings

asciidoctor: WARNING: available-filters/record-encryption/record-encryption.adoc: line 158: section title out of sequence: expected level 4, got level 5
asciidoctor: WARNING: available-filters/record-encryption/record-encryption.adoc: line 158: section title out of sequence: expected level 4, got level 5

I presume those are also issues in the runtime source tree?

[gracegrimwood]

Local builds also show a couple of warnings

asciidoctor: WARNING: available-filters/record-encryption/record-encryption.adoc: line 158: section title out of sequence: expected level 4, got level 5
asciidoctor: WARNING: available-filters/record-encryption/record-encryption.adoc: line 158: section title out of sequence: expected level 4, got level 5

I presume those are also issues in the runtime source tree?

Yeah, those warnings are coming out of Asciidoctor (not the jekyll-asciidoc plugin, but the actual Asciidoctor text processor that the plugin invokes). When you build these docs with maven in the Kroxylicious repository you get the exact same warning:

[INFO] ----------------< io.kroxylicious:kroxylicious-parent >-----------------
[INFO] Building Parent POM 0.5.1                                         [1/24]
[INFO]   from pom.xml
[INFO] --------------------------------[ pom ]---------------------------------
[INFO] 
[INFO] --- asciidoctor:3.0.0:process-asciidoc (convert-to-html) @ kroxylicious-parent ---
Downloading from central: https://repo.maven.apache.org/maven2/org/asciidoctor/asciidoctor-maven-commons/3.0.0/asciidoctor-maven-commons-3.0.0.pom
Downloaded from central: https://repo.maven.apache.org/maven2/org/asciidoctor/asciidoctor-maven-commons/3.0.0/asciidoctor-maven-commons-3.0.0.pom (1.9 kB at 9.1 kB/s)
Downloading from central: https://repo.maven.apache.org/maven2/org/asciidoctor/asciidoctor-maven-commons/3.0.0/asciidoctor-maven-commons-3.0.0.jar
Downloaded from central: https://repo.maven.apache.org/maven2/org/asciidoctor/asciidoctor-maven-commons/3.0.0/asciidoctor-maven-commons-3.0.0.jar (19 kB at 86 kB/s)
[INFO] asciidoctor: DEBUG: overview.adoc: line 31: unknown style for literal block: a2s
[INFO] asciidoctor: DEBUG: overview.adoc: line 96: unknown style for literal block: a2s
[INFO] asciidoctor: DEBUG: overview.adoc: line 118: unknown style for literal block: a2s
[INFO] asciidoctor: DEBUG: overview.adoc: line 171: unknown style for literal block: a2s
[INFO] asciidoctor: WARN: available-filters/record-encryption/record-encryption.adoc: line 158: section title out of sequence: expected level 4, got level 5
[INFO] asciidoctor: DEBUG: custom-filters.adoc: line 288: unknown style for literal block: a2s
[INFO] Converted /Users/ggrimwoo/workspace/kroxylicious/docs/index.adoc

I think it's something to do with the include::hashicorp-vault/service.adoc[leveloffset=3] statement right above a level 4 heading (lines 156-158). Note that further down that file where we're including another file, we're including it at leveloffset=3 above a level 3 heading.

Either way, it's not a fatal error, just a warning about some weird formatting.

[gracegrimwood]

Lets update the adoc to use rouge. One formatter to rule them all....

It would be worth checking if that's a supported option for the development docs, as we use legacy GitHub Pages (based on very old versions of Jekyll and Ruby) for those, and installing custom gems is not an option with that. I know that the old version of Jekyll used by legacy GH Pages uses pygments as a code highlighter, and Asciidoctor only supports rouge versions >=2.x, but I don't know if there's any actual docs on specifically what code highlighters are supported.

~If we can't use rouge with the development docs, we will have to modify this property in these files every time they get pushed into the website repo.~ I can override this globally in _config.yml, so we don't need to change anything.

Also worth doing, but I was expecting the website to maintain docs for each version not just a single copy of the current release docs. So /docs/0.5.0 & /docs/0.3.0 would work was my expectation. That said I'm fine with this PR just fixing the rendering and sorting versioning in a separate PR.

...I might be able to make that work. The difficulty will be that Jekyll isn't actually handling the AsciiDoc files, the jekyll-asciidoc plugin is offloading that rendering to Asciidoctor and largely just using Jekyll as a source of configs and styles before ultimately shoving Asciidoctor's rendered HTML into Jekyll's serving directory. That means Jekyll's whole convention around directories and how they translate to URI fragments only kind of applies to AsciiDoc files. Asciidoctor has its own logic around directories which overrides Jekyll's behaviour, which may mean adding extra metadata to the .adoc files to make this work.

Anyway, I'll see how difficult it is to do and either update this PR or create a new one for that.

[SamBarker]

Re asciidoc warnings, yeah thats fine. My only concern was if it was a change of behaviour between repos.

[gracegrimwood]

I've created a PR against this branch to add the ability to render multiple docs versions and navigate to them sensibly, see here: https://github.com/gracegrimwood/kroxylicious.github.io/pull/1

ETA: Finally got a demo working here https://gracegrimwood.github.io/kroxylicious.github.io/docs/v0.5.1/

[k-wall]

nice work @gracegrimwood. I notice the anchoring icon has been lost. I value this feature. It is really useful to be able to easily point someone at a specific part of the documentation during a support interaction. Is it possible to restore it?

[gracegrimwood]

I notice the anchoring icon has been lost. I value this feature. It is really useful to be able to easily point someone at a specific part of the documentation during a support interaction. Is it possible to restore it?

I've added this to the multiple docs versions PR, and it should be live on the demo site now.