Render Kroxylicious AsciiDoc on the website with Jekyll (#47)

* render release docs with jekyll

* update sitewide code highlighting styles to match original docs styles

* change asciidoc code highlighter to rouge

* remove pygments from gemfile

* fix asciitosvg rendering (adds go to workflow)

* re-add missing dependencies to Gemfile.lock

* render multiple versions of Kroxylicious docs with Jekyll (also, exclude docs files from being served raw)

* add section anchors

* add readme

Author: gracegrimwood

.github/workflows/jekyll-gh-pages.yml

@@ -39,6 +39,10 @@ jobs:
         run: gem install rake
       - name: Update Bundler and Setup Jekyll
         run: bundle install && bundle update --bundler
+      - name: Setup Go
+        uses: actions/setup-go@v5
+      - name: Setup ASCIIToSVG
+        run: go install github.com/asciitosvg/asciitosvg/cmd/a2s@latest
       - name: Download Bootstrap 5 SCSS Sources
         run: ./bootstrap_setup.sh
       - name: Build with Jekyll

Gemfile

@@ -10,6 +10,8 @@ source "https://rubygems.org"
 gem "jekyll", "~> 4.3.2"
 # If you have any plugins, put them here!
 group :jekyll_plugins do
+  gem "asciidoctor-diagram"
+  gem "jekyll-asciidoc"
   gem "jekyll-feed", "~> 0.12"
   gem "jekyll-sass-converter"
   gem "jekyll-seo-tag"

Gemfile.lock

@@ -3,6 +3,14 @@ GEM
   specs:
     addressable (2.8.6)
       public_suffix (>= 2.0.2, < 6.0)
+    asciidoctor (2.0.22)
+    asciidoctor-diagram (2.3.0)
+      asciidoctor (>= 1.5.7, < 3.x)
+      asciidoctor-diagram-ditaamini (~> 1.0)
+      asciidoctor-diagram-plantuml (~> 1.2021)
+      rexml
+    asciidoctor-diagram-ditaamini (1.0.3)
+    asciidoctor-diagram-plantuml (1.2024.3)
     colorator (1.1.0)
     concurrent-ruby (1.2.3)
     em-websocket (0.5.3)
@@ -34,6 +42,9 @@ GEM
       safe_yaml (~> 1.0)
       terminal-table (>= 1.8, < 4.0)
       webrick (~> 1.7)
+    jekyll-asciidoc (3.0.1)
+      asciidoctor (>= 1.5.0, < 3.0.0)
+      jekyll (>= 3.0.0)
     jekyll-feed (0.17.0)
       jekyll (>= 3.7, < 5.0)
     jekyll-sass-converter (3.0.0)
@@ -54,8 +65,8 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.4.0)
-    mini_portile2 (2.8.5)
-    nokogiri (1.16.3)
+    mini_portile2 (2.8.6)
+    nokogiri (1.16.4)
       mini_portile2 (~> 2.8.2)
       racc (~> 1.4)
     pathutil (0.16.2)
@@ -70,16 +81,16 @@ GEM
     rexml (3.2.6)
     rouge (4.2.1)
     safe_yaml (1.0.5)
-    sass-embedded (1.74.1)
+    sass-embedded (1.75.0)
       google-protobuf (>= 3.25, < 5.0)
       rake (>= 13.0.0)
-    sass-embedded (1.74.1-arm64-darwin)
+    sass-embedded (1.75.0-arm64-darwin)
       google-protobuf (>= 3.25, < 5.0)
-    sass-embedded (1.74.1-x64-mingw32)
+    sass-embedded (1.75.0-x64-mingw32)
       google-protobuf (>= 3.25, < 5.0)
-    sass-embedded (1.74.1-x86_64-darwin)
+    sass-embedded (1.75.0-x86_64-darwin)
       google-protobuf (>= 3.25, < 5.0)
-    sass-embedded (1.74.1-x86_64-linux-gnu)
+    sass-embedded (1.75.0-x86_64-linux-gnu)
       google-protobuf (>= 3.25, < 5.0)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
@@ -100,8 +111,10 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  asciidoctor-diagram
   http_parser.rb (~> 0.6.0)
   jekyll (~> 4.3.2)
+  jekyll-asciidoc
   jekyll-feed (~> 0.12)
   jekyll-sass-converter
   jekyll-seo-tag
@@ -111,4 +124,4 @@ DEPENDENCIES
   wdm (~> 0.1.1)
 
 BUNDLED WITH
-   2.4.21
+   2.4.22

_config.yml

@@ -28,6 +28,8 @@ github_username:  kroxylicious
 
 # Build settings
 plugins:
+  - asciidoctor-diagram
+  - jekyll-asciidoc
   - jekyll-feed
   - jekyll-sass-converter
   - jekyll-seo-tag
@@ -43,6 +45,7 @@ plugins:
 #
 exclude:
   - .idea
+  - docs/README.md
 #   - .sass-cache/
 #   - .jekyll-cache/
 #   - gemfiles/
@@ -58,4 +61,20 @@ collections:
   use_cases:
     output: false
   quickstarts:
-    output: false
+    output: false
+
+keep_files:
+  - images
+
+asciidoc:
+  require_front_matter_header: true
+
+asciidoctor:
+  base_dir: :docdir
+  safe: unsafe
+  attributes:
+    imagesdir: /images
+    page-layout: docs
+    toc: preamble
+    source-highlighter: rouge
+    sectanchors: ''

_data/kroxylicious.yml

@@ -0,0 +1,13 @@
+versions:
+  - title: 'Development'
+    url: '/kroxylicious'
+  - title: 'v0.5.1'
+    url: '/docs/v0.5.1/'
+  - title: 'v0.5.0'
+    url: '/docs/v0.5.0/'
+  - title: 'v0.4.1'
+    url: '/docs/v0.4.1/'
+  - title: 'v0.4.0'
+    url: '/docs/v0.4.0/'
+  - title: 'v0.3.0'
+    url: '/docs/v0.3.0/'

_includes/nav.html

@@ -43,10 +43,17 @@
           <li class="nav-item py-lg-1 col-lg-auto">
             <div class="vr d-none d-lg-flex h-100 text-white"></div>
           </li>
-          <li class="nav-item col-6 col-lg-auto">
-            <a class="nav-link krx-nav-link py-2 px-0 px-lg-4" href="{{ '/kroxylicious' | relative_url }}">
-              Docs
-            </a>
+          <li class="nav-item dropdown col-6 col-lg-auto">
+            <a class="nav-link dropdown-toggle krx-nav-link py-2 px-0 px-lg-4" data-bs-toggle="dropdown" href="#" role="button" aria-expanded="false">Docs</a>
+            <ul class="dropdown-menu">
+              {% for version in site.data.kroxylicious.versions %}
+              <li>
+                <a class="dropdown-item {% if page.url == version.url %}active{% endif %} krx-nav-link py-2 px-0 px-lg-4" href="{{ version.url }}">
+                  {{ version.title }}
+                </a>
+              </li>
+              {% endfor %}
+            </ul>
           </li>
           <li class="nav-item py-lg-1 col-lg-auto">
             <div class="vr d-none d-lg-flex h-100 text-white"></div>

_layouts/docs.html

@@ -0,0 +1,35 @@
+---
+layout: default
+---
+<!-- _layouts/docs.html -->
+<div class="row justify-content-center gx-0">
+  <div class="col-lg-3">
+    <div class="card shadow my-lg-5 ms-lg-5 me-1">
+      <div class="card-body mx-2">
+          <h3 class="card-title">
+            {{ page.title }}
+          </h3>
+        <div class="card-text g-0">
+          <p><em>This documentation is for a stable release version of Kroxylicious. For the documentation from the latest development version of Kroxylicious, <a href="{{ '/kroxylicious' | relative_url }}">click here</a>.</small></em></p>
+          {{ page.document | tocify_asciidoc }}
+        </div>
+      </div>
+    </div>
+  </div>
+  <div class="col-lg-9">
+    <div class="card shadow my-lg-5 me-lg-5 ms-1">
+      <div class="card-body mx-2">
+        <div class="row g-0">
+          <div class="col-auto">
+            <div class="card-text m-2">
+              {% if page.version_warning %}
+              {% include bs-alert.html type="warning" content=page.version_warning %}
+              {% endif %}
+              {{ content }}
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>

_sass/kroxylicious.scss

@@ -123,11 +123,14 @@ body {
   }
 }
 
-// Rouge highlighter non-theme formatting
-// (AKA any formatting for Rouge that isn't part of the generated theme)
-
-.highlighter-rouge {
-  background-color: #f8f8f8!important;
+// Rouge highlighter additional formatting
+// Main rouge formatting is in css/code.css
+
+// ensure padding for code blocks
+.highlight {
+  text-wrap: wrap;
+  padding: 1.5em;
+  border-radius: 4px;
 }
 
 div.highlighter-rouge {