jekyll-theme-docsteer 1.0.0

data/_sass/docsteer/_tokens.scss

@@ -0,0 +1,96 @@
+// ── Design tokens (type, sizing, radius, motion) ─────────────
+// Colours are NOT here — see _skins.scss.
+
+:root {
+  // Type — system stack, ordered so each OS lands on its best UI face.
+  // No webfont request: nothing to block, nothing to FOUT.
+  --font-sans: "Inter var", Inter, -apple-system, BlinkMacSystemFont,
+    "Segoe UI Variable Text", "Segoe UI", Roboto, "Helvetica Neue", Arial,
+    "Apple Color Emoji", "Segoe UI Emoji", sans-serif;
+  --font-display: var(--font-sans);
+  --font-mono: ui-monospace, "SF Mono", SFMono-Regular, "Cascadia Code",
+    "JetBrains Mono", Menlo, Consolas, "Liberation Mono", monospace;
+
+  --fs-root: 16px;
+  --lh-body: 1.7;      // long-form reading
+  --lh-tight: 1.25;    // headings
+  --measure: 74ch;     // max comfortable line length
+
+  // Type scale (major third-ish, fluid at the top end)
+  --fs-xs:   0.75rem;
+  --fs-sm:   0.8125rem;
+  --fs-base: 1rem;
+  --fs-md:   1.0625rem;
+  --fs-lg:   1.1875rem;
+  --fs-h4:   1.0625rem;
+  --fs-h3:   1.3125rem;
+  --fs-h2:   clamp(1.4rem, 1.2rem + 0.7vw, 1.65rem);
+  --fs-h1:   clamp(1.95rem, 1.55rem + 1.7vw, 2.6rem);
+
+  // Tracking — tighter as type grows
+  --tr-tight: -0.022em;
+  --tr-snug:  -0.014em;
+  --tr-wide:   0.06em;
+
+  // Spacing scale
+  --sp-1: 4px;
+  --sp-2: 8px;
+  --sp-3: 12px;
+  --sp-4: 16px;
+  --sp-5: 24px;
+  --sp-6: 32px;
+  --sp-7: 48px;
+  --sp-8: 64px;
+  --sp-9: 96px;
+
+  // Radius
+  --r-sm: 6px;
+  --r-md: 10px;
+  --r-lg: 14px;
+  --r-xl: 20px;
+  --r-pill: 999px;
+
+  // Layout metrics
+  --nav-h: 60px;
+  --sidebar-w: 282px;
+  --toc-w: 232px;
+  --content-max: 78ch;
+  --shell-max: 1440px;
+
+  // Motion
+  --ease: cubic-bezier(.4, 0, .2, 1);
+  --ease-out: cubic-bezier(.16, 1, .3, 1);
+  --dur: .16s;
+  --dur-lg: .28s;
+
+  // Elevation — hairline-first. Shadows stay tight and tinted per skin,
+  // so cards read as crisp rather than blurry.
+  --shadow-sm: 0 1px 2px hsl(var(--shadow-color) / .06);
+  --shadow-md:
+    0 1px 2px hsl(var(--shadow-color) / .06),
+    0 6px 16px -4px hsl(var(--shadow-color) / .10);
+  --shadow-lg:
+    0 1px 2px hsl(var(--shadow-color) / .07),
+    0 12px 32px -8px hsl(var(--shadow-color) / .16);
+
+  --focus-ring:
+    0 0 0 2px var(--bg),
+    0 0 0 4px hsl(var(--brand-h) var(--brand-s) 55% / .55);
+
+  color-scheme: light;
+}
+
+:root[data-mode="dark"],
+:root:not([data-mode="light"]) {
+  @media (prefers-color-scheme: dark) { color-scheme: dark; }
+}
+:root[data-mode="dark"] { color-scheme: dark; }
+
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: .001ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: .001ms !important;
+    scroll-behavior: auto !important;
+  }
+}

data/_sass/docsteer/_utilities.scss

@@ -0,0 +1,18 @@
+// ── Utilities ────────────────────────────────────────────────
+.visually-hidden {
+  position: absolute !important;
+  width: 1px; height: 1px;
+  padding: 0; margin: -1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+  border: 0;
+}
+.text-center { text-align: center; }
+.text-soft { color: var(--text-soft); }
+.mt-0 { margin-top: 0 !important; }
+.mb-0 { margin-bottom: 0 !important; }
+.grid-2 { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: var(--sp-4); }
+.grid-3 { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: var(--sp-4); }
+.no-lightbox { cursor: default; }
+.lead { font-size: 1.12rem; color: var(--text-soft); }

data/_sass/docsteer.scss

@@ -0,0 +1,22 @@
+// DocSteer — main stylesheet
+// All colour values live in _skins.scss. Sizing tokens live in _tokens.scss.
+
+@import "docsteer/tokens";
+@import "docsteer/skins";
+@import "docsteer/reset";
+@import "docsteer/base";
+@import "docsteer/layout";
+@import "docsteer/navbar";
+@import "docsteer/sidebar";
+@import "docsteer/toc";
+@import "docsteer/content";
+@import "docsteer/components";
+@import "docsteer/faq";
+@import "docsteer/footer";
+@import "docsteer/home";
+@import "docsteer/search";
+@import "docsteer/lightbox";
+@import "docsteer/syntax";
+@import "docsteer/utilities";
+@import "docsteer/responsive";
+@import "docsteer/print";

data/assets/css/main.scss

@@ -0,0 +1,4 @@
+---
+# Jekyll processes this file. Keep the front matter.
+---
+@import "docsteer";

data/assets/images/favicon.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="DocSteer">
+  <title>DocSteer</title>
+  <defs>
+    <linearGradient id="ds-bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#1668f0"/>
+      <stop offset="1" stop-color="#00b4d8"/>
+    </linearGradient>
+  </defs>
+  <rect width="64" height="64" rx="14" fill="url(#ds-bg)"/>
+  <!-- Compass needle: solid north, translucent south. One shape, so it still
+       reads at 16px where a letterform would turn to mush. -->
+  <path d="M32 11 L42 32 L22 32 Z" fill="#ffffff"/>
+  <path d="M22 32 L42 32 L32 53 Z" fill="#ffffff" opacity=".45"/>
+</svg>

data/assets/images/logo.svg

@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="DocSteer">
+  <title>DocSteer</title>
+  <defs>
+    <linearGradient id="ds-logo-bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#1668f0"/>
+      <stop offset="1" stop-color="#00b4d8"/>
+    </linearGradient>
+  </defs>
+  <!-- Same mark as the favicon. The navbar renders this beside the site title,
+       so it is the mark only — never a wordmark, or the name shows twice. -->
+  <rect width="64" height="64" rx="14" fill="url(#ds-logo-bg)"/>
+  <path d="M32 11 L42 32 L22 32 Z" fill="#ffffff"/>
+  <path d="M22 32 L42 32 L32 53 Z" fill="#ffffff" opacity=".45"/>
+</svg>

data/assets/js/lightbox.js

@@ -0,0 +1,96 @@
+/* DocSteer — image lightbox (no dependencies) */
+(function () {
+  "use strict";
+  var DocSteer = window.DocSteer || {};
+  if (!DocSteer.lightbox) return;
+
+  var box = document.getElementById("lightbox");
+  if (!box) return;
+
+  var scope = document.querySelector(".doc-content") || document.querySelector(".prose");
+  if (!scope) return;
+
+  var imgs = Array.prototype.slice.call(scope.querySelectorAll("img"))
+    .filter(function (img) {
+      return !img.classList.contains("no-lightbox") &&
+        !img.closest("a") &&
+        (img.naturalWidth === 0 || img.naturalWidth > 40);
+    });
+  if (!imgs.length) return;
+
+  var current = 0;
+  var lastFocus = null;
+
+  imgs.forEach(function (img, i) {
+    img.classList.add("lightbox-trigger");
+    img.setAttribute("role", "button");
+    img.setAttribute("tabindex", "0");
+    img.addEventListener("click", function () { openAt(i); });
+    img.addEventListener("keydown", function (e) {
+      if (e.key === "Enter" || e.key === " ") { e.preventDefault(); openAt(i); }
+    });
+  });
+
+  function caption(img) {
+    return img.getAttribute("alt") ||
+      (img.closest("figure") && img.closest("figure").querySelector("figcaption")
+        ? img.closest("figure").querySelector("figcaption").textContent : "");
+  }
+
+  function build() {
+    box.innerHTML =
+      '<button class="lightbox__close" aria-label="Close (Esc)"><i class="fa-solid fa-xmark"></i></button>' +
+      '<span class="lightbox__count"></span>' +
+      '<figure class="lightbox__figure">' +
+        (imgs.length > 1 ? '<button class="lightbox__btn lightbox__prev" aria-label="Previous"><i class="fa-solid fa-chevron-left"></i></button>' : "") +
+        '<img class="lightbox__img" alt="">' +
+        (imgs.length > 1 ? '<button class="lightbox__btn lightbox__next" aria-label="Next"><i class="fa-solid fa-chevron-right"></i></button>' : "") +
+        '<figcaption class="lightbox__caption"></figcaption>' +
+      "</figure>";
+
+    box.querySelector(".lightbox__close").addEventListener("click", close);
+    var p = box.querySelector(".lightbox__prev");
+    var n = box.querySelector(".lightbox__next");
+    if (p) p.addEventListener("click", function (e) { e.stopPropagation(); show(current - 1); });
+    if (n) n.addEventListener("click", function (e) { e.stopPropagation(); show(current + 1); });
+    box.addEventListener("click", function (e) {
+      if (e.target === box || e.target.classList.contains("lightbox__figure")) close();
+    });
+  }
+
+  function show(i) {
+    current = (i + imgs.length) % imgs.length;
+    var src = imgs[current];
+    var full = src.getAttribute("data-full") || src.currentSrc || src.src;
+    var big = box.querySelector(".lightbox__img");
+    big.src = full;
+    big.alt = caption(src);
+    box.querySelector(".lightbox__caption").textContent = caption(src);
+    var count = box.querySelector(".lightbox__count");
+    count.textContent = imgs.length > 1 ? (current + 1) + " / " + imgs.length : "";
+  }
+
+  function openAt(i) {
+    lastFocus = document.activeElement;
+    if (!box.dataset.built) { build(); box.dataset.built = "1"; }
+    show(i);
+    box.classList.add("is-open");
+    box.setAttribute("aria-hidden", "false");
+    document.body.style.overflow = "hidden";
+    box.querySelector(".lightbox__close").focus();
+  }
+
+  function close() {
+    box.classList.remove("is-open");
+    box.setAttribute("aria-hidden", "true");
+    document.body.style.overflow = "";
+    if (lastFocus && lastFocus.focus) lastFocus.focus();
+  }
+
+  document.addEventListener("keydown", function (e) {
+    if (!box.classList.contains("is-open")) return;
+    if (e.key === "Escape") close();
+    else if (e.key === "ArrowLeft") show(current - 1);
+    else if (e.key === "ArrowRight") show(current + 1);
+  });
+})();

data/assets/js/main.js

@@ -0,0 +1,275 @@
+/* DocSteer — core interactions (no dependencies) */
+(function () {
+  "use strict";
+  var DocSteer = window.DocSteer || {};
+  var root = document.documentElement;
+  var $ = function (s, c) { return (c || document).querySelector(s); };
+  var $$ = function (s, c) { return Array.prototype.slice.call((c || document).querySelectorAll(s)); };
+
+  /* ---------- Dark / light mode ---------- */
+  function currentMode() {
+    return root.getAttribute("data-mode") ||
+      (window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
+  }
+  var modeToggle = $("#modeToggle");
+  if (modeToggle) {
+    modeToggle.addEventListener("click", function () {
+      var next = currentMode() === "dark" ? "light" : "dark";
+      root.setAttribute("data-mode", next);
+      try { localStorage.setItem("docsteer-mode", next); } catch (e) {}
+    });
+  }
+
+  /* ---------- Skin picker ---------- */
+  var picker = $("#skinPicker");
+  if (picker) {
+    var pbtn = picker.querySelector("button[aria-haspopup]");
+    var setActive = function () {
+      var cur = root.getAttribute("data-skin");
+      $$(".skin-picker__opt", picker).forEach(function (o) {
+        o.setAttribute("aria-checked", o.dataset.skinSet === cur);
+      });
+    };
+    pbtn.addEventListener("click", function (e) {
+      e.stopPropagation();
+      var open = picker.classList.toggle("is-open");
+      pbtn.setAttribute("aria-expanded", open);
+      setActive();
+    });
+    $$(".skin-picker__opt", picker).forEach(function (o) {
+      o.addEventListener("click", function () {
+        root.setAttribute("data-skin", o.dataset.skinSet);
+        try { localStorage.setItem("docsteer-skin", o.dataset.skinSet); } catch (e) {}
+        picker.classList.remove("is-open");
+        pbtn.setAttribute("aria-expanded", "false");
+      });
+    });
+    document.addEventListener("click", function () {
+      picker.classList.remove("is-open");
+      pbtn.setAttribute("aria-expanded", "false");
+    });
+  }
+
+  /* ---------- Mobile sidebar drawer ---------- */
+  var sidebar = $("#sidebar");
+  var sTog = $("#sidebarToggle");
+  var scrim = $("#sidebarScrim");
+  function closeSidebar() {
+    if (!sidebar) return;
+    sidebar.classList.remove("is-open");
+    if (scrim) scrim.hidden = true;
+    if (sTog) sTog.setAttribute("aria-expanded", "false");
+    document.body.style.overflow = "";
+  }
+  if (sTog && sidebar) {
+    sTog.addEventListener("click", function () {
+      var open = sidebar.classList.toggle("is-open");
+      if (scrim) scrim.hidden = !open;
+      sTog.setAttribute("aria-expanded", open);
+      document.body.style.overflow = open ? "hidden" : "";
+    });
+  }
+  if (scrim) scrim.addEventListener("click", closeSidebar);
+  $$(".sidebar__link").forEach(function (l) { l.addEventListener("click", closeSidebar); });
+
+  /* ---------- Collapsible sidebar groups ---------- */
+  $$(".sidebar__group-title").forEach(function (btn) {
+    btn.addEventListener("click", function () {
+      var group = btn.closest(".sidebar__group");
+      var collapsed = group.classList.toggle("is-collapsed");
+      btn.setAttribute("aria-expanded", !collapsed);
+    });
+  });
+
+  /* ---------- Heading anchors + TOC ---------- */
+  var content = $("#doc-content") || $(".doc-content");
+  if (content) {
+    var heads = $$("h2, h3", content).filter(function (h) { return h.id || h.textContent.trim(); });
+    heads.forEach(function (h) {
+      if (!h.id) {
+        h.id = h.textContent.trim().toLowerCase()
+          .replace(/[^\w\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-");
+      }
+      var a = document.createElement("a");
+      a.href = "#" + h.id;
+      a.className = "heading-anchor";
+      a.setAttribute("aria-label", "Link to this section");
+      a.innerHTML = '<i class="fa-solid fa-link" aria-hidden="true"></i>';
+      h.appendChild(a);
+    });
+
+    var tocNav = $("#tocNav");
+    if (DocSteer.toc && DocSteer.toc.enabled && tocNav && heads.length >= (DocSteer.toc.min || 2)) {
+      var frag = document.createDocumentFragment();
+      heads.forEach(function (h) {
+        var link = document.createElement("a");
+        link.href = "#" + h.id;
+        link.textContent = h.firstChild ? h.firstChild.textContent.trim() : h.textContent.trim();
+        link.className = "lvl-" + (h.tagName === "H3" ? "3" : "2");
+        link.dataset.target = h.id;
+        frag.appendChild(link);
+      });
+      tocNav.appendChild(frag);
+
+      var tocLinks = $$("a", tocNav);
+      var spy = new IntersectionObserver(function (entries) {
+        entries.forEach(function (en) {
+          if (!en.isIntersecting) return;
+          tocLinks.forEach(function (l) {
+            l.classList.toggle("is-active", l.dataset.target === en.target.id);
+          });
+        });
+      }, { rootMargin: "-80px 0px -70% 0px", threshold: 0 });
+      heads.forEach(function (h) { spy.observe(h); });
+
+      tocLinks.forEach(function (l) {
+        l.addEventListener("click", function () {
+          tocLinks.forEach(function (x) { x.classList.remove("is-active"); });
+          l.classList.add("is-active");
+        });
+      });
+    } else if (tocNav) {
+      var tocAside = $("#toc");
+      if (tocAside) tocAside.style.display = "none";
+    }
+  }
+
+  /* ---------- Code blocks: header bar, language label, copy ---------- */
+  var LANG_NAMES = {
+    js: "JavaScript", javascript: "JavaScript", ts: "TypeScript", typescript: "TypeScript",
+    rb: "Ruby", ruby: "Ruby", py: "Python", python: "Python", sh: "Shell", bash: "Bash",
+    shell: "Shell", console: "Terminal", powershell: "PowerShell", yaml: "YAML", yml: "YAML",
+    json: "JSON", html: "HTML", css: "CSS", scss: "SCSS", sass: "Sass", md: "Markdown",
+    markdown: "Markdown", liquid: "Liquid", diff: "Diff", sql: "SQL", go: "Go", rust: "Rust",
+    java: "Java", php: "PHP", xml: "XML", toml: "TOML", ini: "INI", text: "", plaintext: ""
+  };
+
+  function langOf(el) {
+    var host = el.closest("[class*='language-']") || el;
+    var m = /language-([\w+#-]+)/.exec(host.className || "");
+    if (!m) return "";
+    var key = m[1].toLowerCase();
+    return LANG_NAMES.hasOwnProperty(key) ? LANG_NAMES[key] : m[1];
+  }
+
+  if (content) {
+    $$("div.highlighter-rouge, div.highlight, figure.highlight", content).forEach(function (block) {
+      // Only wrap the outermost Rouge container
+      if (block.closest(".code-wrap")) return;
+      if (block.parentNode.closest && block.parentNode.closest(".highlighter-rouge")) return;
+
+      var wrap = document.createElement("div");
+      wrap.className = "code-wrap";
+      block.parentNode.insertBefore(wrap, block);
+
+      var bar = document.createElement("div");
+      bar.className = "code-wrap__bar";
+      var label = langOf(block);
+      bar.innerHTML = '<span class="code-wrap__lang">' + (label || "Code") + "</span>";
+      wrap.appendChild(bar);
+      wrap.appendChild(block);
+
+      if (!DocSteer.codeCopy || !navigator.clipboard) return;
+
+      var IDLE = '<i class="fa-regular fa-copy" aria-hidden="true"></i><span>Copy</span>';
+      var DONE = '<i class="fa-solid fa-check" aria-hidden="true"></i><span>Copied</span>';
+      var btn = document.createElement("button");
+      btn.className = "code-copy";
+      btn.type = "button";
+      btn.setAttribute("aria-label", "Copy code to clipboard");
+      btn.innerHTML = IDLE;
+      bar.appendChild(btn);
+
+      btn.addEventListener("click", function () {
+        var code = block.querySelector("code") || block.querySelector("pre") || block;
+        navigator.clipboard.writeText(code.innerText.replace(/\n+$/, "")).then(function () {
+          btn.classList.add("is-done");
+          btn.innerHTML = DONE;
+          setTimeout(function () {
+            btn.classList.remove("is-done");
+            btn.innerHTML = IDLE;
+          }, 1800);
+        });
+      });
+    });
+
+    /* ---------- Tables: wrap so wide ones scroll, not the page ---------- */
+    $$("table", content).forEach(function (t) {
+      if (t.closest(".table-scroll")) return;
+      var box = document.createElement("div");
+      box.className = "table-scroll";
+      t.parentNode.insertBefore(box, t);
+      box.appendChild(t);
+    });
+  }
+
+  /* ---------- External links ---------- */
+  $$(".doc-content a[href^='http']").forEach(function (a) {
+    if (a.hostname !== location.hostname) {
+      a.setAttribute("target", "_blank");
+      a.setAttribute("rel", "noopener noreferrer");
+    }
+  });
+
+  /* ---------- FAQ accordion ---------- */
+  // Opening and closing is native <details> behaviour; this only adds the
+  // "expand all" control and makes #question deep links actually open the item.
+  var faq = $("#faq");
+  if (faq) {
+    var faqItems = $$(".faq-item", faq);
+
+    var openFromHash = function () {
+      var id = decodeURIComponent(location.hash.slice(1));
+      if (!id) return;
+      var target = document.getElementById(id);
+      if (!target || !target.classList.contains("faq-item")) return;
+      target.open = true;
+      target.scrollIntoView({ block: "start" });
+    };
+    openFromHash();
+    window.addEventListener("hashchange", openFromHash);
+
+    // Keep the URL pointing at the question being opened, without piling up
+    // history entries the Back button would have to walk through.
+    faqItems.forEach(function (d) {
+      var sum = $("summary", d);
+      if (!sum) return;
+      sum.addEventListener("click", function () {
+        if (!d.open && d.id) history.replaceState(null, "", "#" + d.id);
+      });
+    });
+
+    var faqAll = $("#faqToggleAll");
+    if (faqAll) {
+      faqAll.addEventListener("click", function () {
+        var expand = faqAll.dataset.expanded !== "true";
+        faqItems.forEach(function (d) { d.open = expand; });
+        faqAll.dataset.expanded = expand;
+        $("span", faqAll).textContent = expand ? "Collapse all" : "Expand all";
+        $("i", faqAll).className = expand
+          ? "fa-solid fa-angles-up"
+          : "fa-solid fa-angles-down";
+      });
+    }
+  }
+
+  /* ---------- Back to top ---------- */
+  var toTop = $("#toTop");
+  if (toTop) {
+    var onScroll = function () {
+      var show = window.scrollY > 600;
+      toTop.hidden = !show;
+      toTop.classList.toggle("is-visible", show);
+    };
+    window.addEventListener("scroll", onScroll, { passive: true });
+    onScroll();
+    toTop.addEventListener("click", function () {
+      window.scrollTo({ top: 0, behavior: "smooth" });
+    });
+  }
+
+  /* ---------- Esc closes drawers ---------- */
+  document.addEventListener("keydown", function (e) {
+    if (e.key === "Escape") closeSidebar();
+  });
+})();