[docs] enhance docs site with new Jekyll theme, organized docs and local preview

.gitignore

@@ -47,3 +47,7 @@ junit.xml
 
 # Local dev setup
 .envrc
+
+# Jekyll local preview
+_site/
+.sass-cache/

Makefile

@@ -44,6 +44,15 @@ SUBNET_KUBECONFIG_PATH	?= $(CURDIR)/subnet-testing-kubeconfig.yaml
 MGMT_KUBECONFIG_PATH    ?= $(CURDIR)/mgmt-cluster-kubeconfig.yaml
 IPV6_KUBECONFIG_PATH    ?= $(CURDIR)/ipv6-kubeconfig.yaml
 
+#####################################################################
+# Local Docs Preview Setup
+#####################################################################
+
+DOCS_IMAGE       := jekyll/jekyll:pages
+DOCS_CONTAINER   := lccm-docs
+DOCS_PORT        := 4000
+DOCS_LIVERELOAD_PORT := 35729
+
 export GO111MODULE=on
 
 .PHONY: all
@@ -260,3 +269,19 @@ helm-template:
 	@helm template foo deploy/chart --set apiToken="apiToken",region="us-east" > /dev/null
 	@helm template foo deploy/chart --set secretRef.apiTokenRef="apiToken",secretRef.name="api",secretRef.regionRef="us-east" > /dev/null
 
+.PHONY: serve-docs
+serve-docs:
+# Serve the documentation site locally with live reload
+	echo "Serving the docs on http://localhost:$(DOCS_PORT), press ctrl-c to stop"
+	docker run --rm --interactive --tty --name $(DOCS_CONTAINER) \
+		--publish $(DOCS_PORT):4000 \
+		--publish $(DOCS_LIVERELOAD_PORT):35729 \
+		--volume "$(shell pwd):/srv/jekyll" \
+		$(DOCS_IMAGE) \
+		jekyll serve --host 0.0.0.0 --livereload --force-polling
+
+.PHONY: build-docs
+build-docs:
+# Build the documentation site the way GitHub Pages does
+	docker run --rm --volume "$(shell pwd):/srv/jekyll" $(DOCS_IMAGE) jekyll build
+

_config.yml

@@ -0,0 +1,39 @@
+remote_theme: just-the-docs/just-the-docs
+
+# GitHub Pages turns the plugins below on by default; a local `jekyll build`
+# does not, which is why pages that rely on them (markdown without front
+# matter, titles taken from the first heading) are missing from the local nav
+# unless they are listed here. Listing them changes nothing in production.
+plugins:
+  - jekyll-remote-theme
+  - jekyll-default-layout
+  - jekyll-optional-front-matter
+  - jekyll-readme-index
+  - jekyll-relative-links
+  - jekyll-titles-from-headings
+
+title: Kubernetes Cloud Controller Manager for Linode
+search_enabled: true
+heading_anchors: true
+color_scheme: dark
+
+
+# Everything that is not documentation. Without this the site carries the whole
+# Go tree, and CHANGELOG.md is published as a stray page nothing links to.
+exclude:
+  - bin/
+  - CHANGELOG.md
+  - cloud/
+  - codecov.yml
+  - coverage.out
+  - deploy/
+  - e2e/
+  - examples/
+  - go.mod
+  - go.sum
+  - hack/
+  - main.go
+  - Makefile
+  - mise.toml
+  - renovate.json5
+  - sentry/

_includes/head_custom.html

@@ -0,0 +1,100 @@
+{%- comment -%}
+  Color scheme preference: light, dark, or follow the OS ("system"). The script
+  runs in the document head so the stored choice is applied before the page
+  paints. The toggle button itself is in header_custom.html.
+
+  Two constraints on the script below:
+
+  1. Block comments only. The theme renders pages through
+     _layouts/vendor/compress.html, which strips newlines, so a `//` comment
+     would swallow the rest of the script.
+  2. Never write a literal `head` element tag in it. Jekyll's `--livereload`
+     server injects its reload snippet at that string, and the snippet's closing
+     script tag would end the script early, dumping the rest of the code onto
+     the page as text.
+
+  Long notes like this one belong in a Liquid comment: Jekyll strips it at build
+  time, so it never ships to the browser with every page.
+{%- endcomment -%}
+<script>
+  window.jtdTheme = (function () {
+    var STORAGE_KEY = 'jtd-color-scheme';
+    var prefersDark = window.matchMedia('(prefers-color-scheme: dark)');
+    /* The scheme compiled into just-the-docs-default.css. */
+    var applied = {% if site.color_scheme and site.color_scheme != "nil" %}'{{ site.color_scheme }}'{% else %}'light'{% endif %};
+    /* The link element carrying it, once swapStylesheet has replaced it. */
+    var sheet = null;
+
+    /* localStorage throws when cookies are blocked, so never let it break the page. */
+    function preference() {
+      try {
+        return localStorage.getItem(STORAGE_KEY) || 'system';
+      } catch (e) {
+        return 'system';
+      }
+    }
+
+    function resolved() {
+      var pref = preference();
+      if (pref === 'light' || pref === 'dark') {
+        return pref;
+      }
+      return prefersDark.matches ? 'dark' : 'light';
+    }
+
+    /* Insert the new sheet after the current one, where it wins the cascade,
+       then retire the current one once the new one has loaded. Mutating the live
+       sheet's href instead (what jtd.setTheme() does) drops the rules the page
+       is showing and paints raw HTML until the replacement arrives. */
+    function swapStylesheet(scheme) {
+      /* Tracked rather than re-queried, so a second click before the first
+         sheet loads still inserts the newest sheet last. */
+      var current = sheet || document.querySelector('link[rel="stylesheet"]');
+      var next = document.createElement('link');
+      next.rel = 'stylesheet';
+      /* Derived from the current href, so this holds under a site.baseurl. */
+      next.href = current.getAttribute('href').replace(/just-the-docs-[\w-]+\.css$/, 'just-the-docs-' + scheme + '.css');
+      next.addEventListener('load', function () {
+        if (current.parentNode) {
+          current.parentNode.removeChild(current);
+        }
+      });
+      current.parentNode.insertBefore(next, current.nextSibling);
+      sheet = next;
+      applied = scheme;
+    }
+
+    function applyTheme() {
+      var scheme = resolved();
+      /* Nothing to replace when the page already loaded this scheme. */
+      if (scheme !== applied) {
+        swapStylesheet(scheme);
+      }
+      /* Keeps native controls and scrollbars in step with the page. */
+      document.documentElement.style.colorScheme = scheme;
+    }
+
+    function set(pref) {
+      try {
+        localStorage.setItem(STORAGE_KEY, pref);
+      } catch (e) { /* not persisted, but the page still switches */ }
+      applyTheme();
+    }
+
+    /* Track the OS only while the preference is "system". MediaQueryList did not
+       inherit from EventTarget until Safari 14, and this listener is the one
+       optional part of the module: without the guard its TypeError would abort
+       everything below, leaving the toggle dead rather than just untracked. */
+    if (prefersDark.addEventListener) {
+      prefersDark.addEventListener('change', function () {
+        if (preference() === 'system') {
+          applyTheme();
+        }
+      });
+    }
+
+    applyTheme();
+
+    return { preference: preference, set: set };
+  })();
+</script>

_includes/header_custom.html

@@ -0,0 +1,66 @@
+<div class="theme-switcher">
+  <!-- aria-label is refined by the script below; this default covers a failed or disabled script. -->
+  <button type="button" id="theme-toggle" class="theme-switcher-btn btn-reset" aria-label="Color scheme">
+    <!-- Feather icons, matching the set the theme already uses. MIT License: https://github.com/feathericons/feather/blob/master/LICENSE -->
+    <svg class="theme-switcher-icon" data-scheme="system" viewBox="0 0 24 24" aria-hidden="true">
+      <rect x="2" y="3" width="20" height="14" rx="2" ry="2"></rect>
+      <line x1="8" y1="21" x2="16" y2="21"></line>
+      <line x1="12" y1="17" x2="12" y2="21"></line>
+    </svg>
+    <svg class="theme-switcher-icon" data-scheme="light" viewBox="0 0 24 24" aria-hidden="true" hidden>
+      <circle cx="12" cy="12" r="5"></circle>
+      <line x1="12" y1="1" x2="12" y2="3"></line>
+      <line x1="12" y1="21" x2="12" y2="23"></line>
+      <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
+      <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
+      <line x1="1" y1="12" x2="3" y2="12"></line>
+      <line x1="21" y1="12" x2="23" y2="12"></line>
+      <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
+      <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
+    </svg>
+    <svg class="theme-switcher-icon" data-scheme="dark" viewBox="0 0 24 24" aria-hidden="true" hidden>
+      <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"></path>
+    </svg>
+  </button>
+</div>
+
+{%- comment -%}
+  Cycles the color scheme preference (System, Light, Dark) and shows the matching
+  icon. Block comments only in the script below, and no literal element tags: see
+  the notes in head_custom.html.
+{%- endcomment -%}
+<script>
+  (function () {
+    var ORDER = ['system', 'light', 'dark'];
+    var LABELS = { system: 'follow system', light: 'light', dark: 'dark' };
+    var button = document.getElementById('theme-toggle');
+    var icons = button.querySelectorAll('.theme-switcher-icon');
+
+    function render() {
+      var pref = window.jtdTheme.preference();
+      if (ORDER.indexOf(pref) < 0) {
+        pref = 'system';
+      }
+      for (var i = 0; i < icons.length; i++) {
+        /* setAttribute, not .hidden: the hidden IDL property is on
+           HTMLElement, so assigning it to an SVG element does nothing. */
+        if (icons[i].getAttribute('data-scheme') === pref) {
+          icons[i].removeAttribute('hidden');
+        } else {
+          icons[i].setAttribute('hidden', '');
+        }
+      }
+      var label = 'Color scheme: ' + LABELS[pref] + ' (click to change)';
+      button.setAttribute('title', label);
+      button.setAttribute('aria-label', label);
+    }
+
+    button.addEventListener('click', function () {
+      /* indexOf returns -1 for an unknown stored value, which lands on 'system'. */
+      window.jtdTheme.set(ORDER[(ORDER.indexOf(window.jtdTheme.preference()) + 1) % ORDER.length]);
+      render();
+    });
+
+    render();
+  })();
+</script>

_sass/custom/custom.scss

@@ -0,0 +1,62 @@
+// Overrides just-the-docs' (empty) custom stylesheet. Imported last by the
+// theme, so these rules win over the theme's own and are compiled into every
+// color scheme.
+
+// The theme pins the sidebar header to a fixed height and centers the title in
+// it, so a site title long enough to wrap (this one takes three lines) is
+// clipped and spills out of the sidebar. Let the header grow to fit instead:
+// .site-nav below it is `flex: 1 1 auto` with its own scrollbar, so it simply
+// starts lower. The theme's own min-height still applies.
+.site-header {
+  height: auto;
+  max-height: none;
+}
+
+// Color scheme toggle, rendered by _includes/header_custom.html. An icon-only
+// button styled from the theme's color variables, so it follows whichever
+// scheme is active.
+.theme-switcher {
+  display: flex;
+  align-items: center;
+  padding: $sp-2 $sp-4;
+}
+
+.theme-switcher-btn {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  padding: 0;
+  color: $body-text-color;
+  cursor: pointer;
+  border-radius: $border-radius;
+  transition: color 150ms ease, background-color 150ms ease;
+
+  &:hover {
+    // $feedback-color is what the theme uses for its own hover surfaces.
+    color: $link-color;
+    background-color: $feedback-color;
+  }
+
+  &:focus-visible {
+    outline: 2px solid $link-color;
+    outline-offset: 1px;
+  }
+}
+
+.theme-switcher-icon {
+  width: 1.125rem;
+  height: 1.125rem;
+  fill: none;
+  stroke: currentcolor;
+  stroke-width: 2;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+
+  // SVG elements are not HTML elements, so spell out what `hidden` means here
+  // rather than relying on the browser's rule for it.
+  &[hidden] {
+    display: none;
+  }
+}

docs/configuration/README.md

@@ -1,3 +1,9 @@
+---
+layout: default
+title: Configuration Guide
+nav_order: 3
+---
+
 # Configuration Guide
 
 The Linode Cloud Controller Manager (CCM) offers extensive configuration options to customize its behavior. This section covers all available configuration methods and options.

docs/configuration/annotations.md

@@ -1,3 +1,10 @@
+---
+layout: default
+title: Service Annotations
+parent: Configuration Guide
+nav_order: 2
+---
+
 # Service Annotations
 
 ## Overview
@@ -18,7 +25,7 @@ The keys and the values in [annotations must be strings](https://kubernetes.io/d
 ### Basic Configuration
 
 | Annotation (Suffix) | Values | Default | Description |
-|--------------------|--------|---------|-------------|
+| -------------------- | -------- | --------- | ------------- |
 | `throttle` | `0`-`20` (`0` to disable) | `0` | Client Connection Throttle, which limits the number of subsequent new connections per second from the same client IP |
 | `default-protocol` | `tcp`, `udp`, `http`, `https` | `tcp` | This annotation is used to specify the default protocol for Linode NodeBalancer |
 | `default-proxy-protocol` | `none`, `v1`, `v2` | `none` | Specifies whether to use a version of Proxy Protocol on the underlying NodeBalancer |

docs/configuration/environment.md

@@ -1,3 +1,10 @@
+---
+layout: default
+title: Environment Variables and Flags
+parent: Configuration Guide
+nav_order: 4
+---
+
 # Environment Variables and Flags
 
 ## Overview
@@ -96,7 +103,7 @@ spec:
 
 - Adjust cache TTL based on cluster size and update frequency
 - Monitor memory usage when modifying cache settings
-- Consider API rate limits when decreasing TTL (see [Linode API Rate Limits](@https://techdocs.akamai.com/linode-api/reference/rate-limits))
+- Consider API rate limits when decreasing TTL (see [Linode API Rate Limits](https://techdocs.akamai.com/linode-api/reference/rate-limits))
 
 ### API Settings