Merge pull request #36 from k-wall/issue-31

Fix #31: Enable anchor links for kroxylicious.io
kroxylicious · Feb 7, 2024 · 8b00f15 · 8b00f15
2 parents 73b8256 + abc70d2
commit 8b00f15
Show file tree

Hide file tree

Showing 13 changed files with 85 additions and 12 deletions.
diff --git a/Gemfile b/Gemfile
@@ -13,6 +13,7 @@ group :jekyll_plugins do
   gem "jekyll-feed", "~> 0.12"
   gem "jekyll-sass-converter"
   gem "jekyll-seo-tag"
+  gem "jekyll-toc"
 end
 
 # Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem

diff --git a/Gemfile.lock b/Gemfile.lock
@@ -39,6 +39,9 @@ GEM
       sass-embedded (~> 1.54)
     jekyll-seo-tag (2.8.0)
       jekyll (>= 3.8, < 5.0)
+    jekyll-toc (0.18.0)
+      jekyll (>= 3.9)
+      nokogiri (~> 1.12)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
     kramdown (2.4.0)
@@ -50,9 +53,15 @@ 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.0)
+      mini_portile2 (~> 2.8.2)
+      racc (~> 1.4)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
     public_suffix (5.0.3)
+    racc (1.7.3)
+    racc (1.7.3-java)
     rake (13.1.0)
     rb-fsevent (0.11.2)
     rb-inotify (0.10.1)
@@ -94,6 +103,7 @@ DEPENDENCIES
   jekyll-feed (~> 0.12)
   jekyll-sass-converter
   jekyll-seo-tag
+  jekyll-toc
   tzinfo (>= 1, < 3)
   tzinfo-data
   wdm (~> 0.1.1)

diff --git a/_config.yml b/_config.yml
@@ -31,6 +31,7 @@ plugins:
   - jekyll-feed
   - jekyll-sass-converter
   - jekyll-seo-tag
+  - jekyll-toc
 
 # Exclude from processing.
 # The following items will not be processed, by default.

diff --git a/_layouts/default.html b/_layouts/default.html
@@ -10,9 +10,9 @@
     <script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/5.3.2/js/bootstrap.bundle.min.js" integrity="sha512-X/YkDZyjTf4wyc2Vy16YGCPHwAY8rZJY+POgokZjQB2mhIRFJCckEGc6YyX9eNsPfn0PzThEuNs+uaomE5CO6A==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
     {% seo %}
 </head>
-<body class="d-flex flex-column vh-100" data-bs-theme="light">
+<body class="d-flex flex-column" data-bs-theme="light">
 {% include nav.html %}
-<div class="container-fluid px-0" data-bs-theme="light">
+<div class="container-fluid px-0 krx-content" data-bs-theme="light">
     {{ content }}
 </div>
 {% include footer.html %}

diff --git a/_layouts/index.html b/_layouts/index.html
@@ -36,4 +36,4 @@ <h1 class="fw-bold text-body-emphasis lh-1 mb-3">Kroxylicious transparently inje
       </div>
     </div>
   </div>
-</div>
+</div>
diff --git a/_layouts/overview.html b/_layouts/overview.html
@@ -1,16 +1,17 @@
 ---
 layout: default
+toc: true
 ---
 <div class="row justify-content-center">
   <div class="col-11 col-lg-8 card shadow gx-5 gy-5 m-lg-5">
     <div class="row g-0">
       <div class="col-auto">
         <div class="card-body">
           <div class="card-text m-2">
-            {{ content | markdownify }}
+            {{ content | markdownify | inject_anchors }}
           </div>
         </div>
       </div>
     </div>
   </div>
-</div>
+</div>
diff --git a/_layouts/use-cases.html b/_layouts/use-cases.html
@@ -1,5 +1,6 @@
 ---
 layout: default
+toc: true
 ---
 
 <div class="row justify-content-center">
@@ -9,8 +10,7 @@
             <div class="row g-0">
                 <div class="col-auto">
                   {% for use_case in site.use_cases %}
-                    <h2 class="card-subtitle">{{ use_case.name }}</h2>
-                    <p class="card-text">{{ use_case.content | markdownify }}</p>
+                    <div class="card-text">{{ use_case.content | markdownify | inject_anchors}}</div>
                   {% endfor %}
                 </div>
             </div>

diff --git a/_sass/kroxylicious.scss b/_sass/kroxylicious.scss
@@ -33,6 +33,14 @@ $navbar-dark-disabled-color: rgba($white, 0.45);
 // Custom bootstrap variables must be set or imported *before* bootstrap.
 @import "./bootstrap/scss/bootstrap";
 
+body {
+  height: fit-content!important;
+}
+
+.krx-content * {
+  scroll-margin-top: 5rem!important;
+}
+
 .list-group-item:hover {
   background-color: tint-color($primary, 50%);
 }
@@ -110,6 +118,8 @@ $navbar-dark-disabled-color: rgba($white, 0.45);
   }
 }
 
+// Rouge highlighter non-theme formatting
+// (AKA any formatting for Rouge that isn't part of the generated theme)
 
 .highlighter-rouge {
   background-color: #f8f8f8!important;
@@ -130,3 +140,31 @@ div.highlighter-rouge {
   }
 }
 
+// Anchor Links
+
+h2>a.anchor, h3>a.anchor, h4>a.anchor, h5>a.anchor, h6>a.anchor {
+  font-family: bootstrap-icons!important;
+  color: rgba($primary, 0);
+  display: block;
+  margin-left: -1.5ex;
+  position: absolute;
+  text-decoration: none !important;
+  visibility: hidden;
+  z-index: 2;
+  transition:
+          visibility 1ms linear,
+          color 200ms ease-in-out;
+}
+
+h2>a.anchor::before, h3>a.anchor::before, h4>a.anchor::before, h5>a.anchor::before, h6>a.anchor::before {
+  content: "\f470";
+}
+
+h2:hover>a.anchor, h3:hover>a.anchor, h4:hover>a.anchor, h5:hover>a.anchor, h6:hover>a.anchor {
+  visibility: visible;
+  color: rgba($primary, 1);
+}
+
+h2:hover>a.anchor:hover, h3:hover>a.anchor:hover, h4:hover>a.anchor:hover, h5:hover>a.anchor:hover, h6:hover>a.anchor:hover {
+  color: rgba($secondary, 1);
+}
diff --git a/_use_cases/encryption-at-rest.markdown b/_use_cases/encryption-at-rest.markdown
@@ -2,7 +2,9 @@
 name: Encryption At Rest
 ---
 
-## Why
+### Encryption At Rest
+
+#### Why
 
 Apache Kafka&#174; does not directly support any form of encryption for data stored within a broker. This means that the contents
 of records sent to Apache Kafka are stored in the clear on the broker's disks. Anyone with sufficient access, such as a Kafka Administrator
@@ -20,7 +22,7 @@ data is now residing in the clear on the file systems of the service provider.
 |:-----------------------------------------------------------------:|
 |    *Problem: Plain text records readable by the Kafka Admins*     |
 
-### Isn't TLS sufficient?
+##### Isn't TLS sufficient?
 
 TLS encrypts the content _in transit_.  It means that someone using a network sniffer cannot intercept what is being
 sent over the wire between the application and the Kafka Broker.  However, once the network packets arrive at the broker,
@@ -29,7 +31,7 @@ of the broker and in the clear when the data is written to the file system.
 
 TLS does not change the problem.
 
-### Isn't storage volume encryption an answer?
+##### Isn't storage volume encryption an answer?
 
 With storage volume encryption, the contents of the volume are encrypted with a single key.  This approach provides some mitigations.
 If the storage device is stolen or the storage device hijacked and attached to an attacker's computer, the attacker won't have
@@ -41,7 +43,7 @@ to be able to read the data, including the Kafka confidential records.
 
 Storage volume encryption doesn't really solve the problem.
 
-### Can't the applications encrypt/decrypt the data?
+##### Can't the applications encrypt/decrypt the data?
 
 It is possible for producing applications to encrypt data before sending it to Kafka, and for consuming applications to decrypt it
 again.  With this approach the brokers never possess the records in the clear and as they don't have encryption keys, they cannot
@@ -64,7 +66,7 @@ of a design flaw or bug are significant (confidentiality breach).
 Having the applications encrypt/decrypt data themselves, whilst technically feasible, is not really a tenable solution
 at the scale required for most enterprises.
 
-# Kroxylicious Topic Encryption
+#### Kroxylicious Topic Encryption
 
 The Kroxylicious Topic Encryption feature offers a solution to the problem.  The proxy takes the responsibility
 to encrypt and decrypt the messages. In this way, the Kafka Brokers never see the plain text content of

diff --git a/css/code.css b/css/code.css
@@ -1,3 +1,15 @@
+/*
+ * This file is a generated Rouge code highlighter theme, and can be
+ * re-generated with the `rougify` command. More info about this can be found
+ * at https://rouge.jneen.net/ or https://github.com/rouge-ruby/rouge
+ *
+ * NOTE: Manual adjustments to the code highlighting colors and fonts in this
+ * file will persist as it is not re-generated at runtime.
+ * However, any formatting that is not part of the Rouge theme should NOT be
+ * put in this file, and should instead go in _sass/kroxylicious.scss as it
+ * will be overwritten if this file is ever re-generated.
+ */
+
 .highlight table td { padding: 5px; }
 .highlight table pre { margin: 0; }
 .highlight .c, .highlight .ch, .highlight .cd, .highlight .cm, .highlight .cpf, .highlight .c1 {

diff --git a/css/style.scss b/css/style.scss
@@ -1,4 +1,10 @@
 ---
 ---
+/*
+ * This file exists solely to import the _sass/kroxylicious.scss file
+ * and the Rouge code highlighter theme CSS so they can be compiled by Jekyll.
+ * Any actual formatting should go in the _sass/kroxylicious.scss file, which
+ * is compiled into CSS by jekyll-sass-converter when the site is built.
+ */
 @import "kroxylicious";
 @import "code.css";
diff --git a/overview.markdown b/overview.markdown
@@ -2,6 +2,7 @@
 layout: overview
 title: Overview
 permalink: /overview/
+toc: true
 ---
 
 This page provides an overview of how Kroxylicious works.  For more details, please refer to the [documentation](./kroxylicious).

diff --git a/use-cases.markdown b/use-cases.markdown
@@ -2,5 +2,6 @@
 layout: use-cases
 title: Use Cases
 permalink: /use-cases/
+toc: true
 ---
-Original file line number
+Diff line change
@@ Expand Up @@
           </div>
         </div>
       </div>
-    </div>
+    </div>