jekyll-theme-docsteer 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b49a45ae03e89044c653d5cae4fa3749d6b3c4a3d7c6837555a383242700ee3
-  data.tar.gz: 1f9b744dc050ff685596ba7d853ed230cdf08224d4aa9caceead2363470ec14e
+  metadata.gz: efd8a4dee01456dd316c9a4ba45f0762ebed0255b192413774687b8f6ce7143e
+  data.tar.gz: 7fc1744dcf4232e345625ad934ed9d9fd4468f705ca5099fe79d4233e980331a
 SHA512:
-  metadata.gz: c506de353cb020505952ca9bd4b6c7e69f1bddc933c538e0d1bbc58beaf0f01cedddf9becacf21ca7c2dc17677a6c2cb028a0a56533fa41ecba9af3463f2cfa7
-  data.tar.gz: 046a10b8e0e8814a576703ef264c368ae356464d71cb28baf83ed2bf4f2ba4cf44000912a9363a14ee162fd8c1c63445d38f51174a5cd1aff6d5e27fdafb9854
+  metadata.gz: 66657360820626321676e5100f51c159ba900fb00de2b22c253f68036889120bc9a00c8c19f9079f74ca7db6c9cdf7d84fa2e33c5669273e36f511cf250a839e
+  data.tar.gz: 39543eee91a6f6c3ed311941e5e5ab953bc7f9e0dabd8ef9feec253bd8933dc386f4924912d05aaf5ade2615b7a0d8ecef81a0b1db4828a07c96c52b1650e9e9

data/README.md

@@ -100,6 +100,12 @@ GitHub Pages (via Actions), Netlify, Vercel, Cloudflare Pages — see
 (`footer.show_credit: false` to remove it).
 Font Awesome is under its own [Free License](https://fontawesome.com/license/free).
 
+## Roadmap
+
+Planned work, deferred decisions and the release checklist live in
+[`ROADMAP.md`](ROADMAP.md). Released changes are in
+[`CHANGELOG.md`](CHANGELOG.md).
+
 ## Support
 
 If DocSteer saved you time, you can

data/_includes/doc-footer.html

@@ -33,6 +33,18 @@
 
 {% if page.tags and page.tags.size > 0 %}
 <div class="doc-tags">
-  {% for t in page.tags %}<span class="badge badge--soft">#{{ t }}</span>{% endfor %}
+  {%- comment -%}
+    Tags are already in search.json, so a tag is a search the reader has not run
+    yet: the button hands the term to the modal. With search off there is
+    nothing to hand it to, so it stays the inert badge it was.
+  {%- endcomment -%}
+  {% for t in page.tags %}
+    {%- if site.docsteer.search.enabled -%}
+      <button type="button" class="badge badge--soft doc-tag"
+              data-search-open="{{ t }}" aria-label="Search for {{ t }}">#{{ t }}</button>
+    {%- else -%}
+      <span class="badge badge--soft">#{{ t }}</span>
+    {%- endif -%}
+  {% endfor %}
 </div>
 {% endif %}

data/_includes/head.html

@@ -39,7 +39,7 @@
     {% endif %}
   {% endif %}
 
-  <link rel="stylesheet" href="{{ '/assets/css/main.css' | relative_url }}">
+  <link rel="stylesheet" href="{{ '/assets/css/main.css' | relative_url }}?v={{ ds_version }}">
 
   {% if site.feed.path %}
     <link rel="alternate" type="application/atom+xml" title="{{ site.title }}" href="{{ '/feed.xml' | relative_url }}">

data/_includes/navbar.html

@@ -1,7 +1,7 @@
 {%- assign cfg = site.docsteer -%}
 <header class="navbar" id="navbar">
   <div class="navbar__inner">
-    <button class="navbar__burger" id="sidebarToggle" aria-label="Open menu" aria-expanded="false">
+    <button class="navbar__burger" id="sidebarToggle" aria-controls="sidebar" aria-label="Open menu" aria-expanded="false">
       <i class="fa-solid fa-bars" aria-hidden="true"></i>
     </button>
 

data/_includes/scripts.html

@@ -17,6 +17,6 @@
     }
   };
 </script>
-<script src="{{ '/assets/js/main.js' | relative_url }}" defer></script>
-{% if cfg.search.enabled %}<script src="{{ '/assets/js/search.js' | relative_url }}" defer></script>{% endif %}
-{% if cfg.lightbox.enabled %}<script src="{{ '/assets/js/lightbox.js' | relative_url }}" defer></script>{% endif %}
+<script src="{{ '/assets/js/main.js' | relative_url }}?v={{ ds_version }}" defer></script>
+{% if cfg.search.enabled %}<script src="{{ '/assets/js/search.js' | relative_url }}?v={{ ds_version }}" defer></script>{% endif %}
+{% if cfg.lightbox.enabled %}<script src="{{ '/assets/js/lightbox.js' | relative_url }}?v={{ ds_version }}" defer></script>{% endif %}

data/_includes/sidebar.html

@@ -1,5 +1,13 @@
 {%- assign cfg = site.docsteer -%}
-<aside class="sidebar{% if cfg.sidebar.sticky %} is-sticky{% endif %}" id="sidebar" aria-label="Documentation navigation">
+{%- comment -%}
+  Rendered on EVERY page, because the navbar burger is shown on every page at
+  mobile widths and has to open something. `include.docs` says whether this
+  page also gets the documentation tree; when it is false the aside exists
+  only as the mobile drawer (see .sidebar--drawer-only).
+{%- endcomment -%}
+{%- assign show_docs = include.docs -%}
+<aside class="sidebar{% unless show_docs %} sidebar--drawer-only{% endunless %}{% if cfg.sidebar.sticky and show_docs %} is-sticky{% endif %}"
+       id="sidebar" aria-label="Site navigation">
   <div class="sidebar__inner">
 
     {% if cfg.search.enabled %}
@@ -9,6 +17,24 @@
     </button>
     {% endif %}
 
+    {%- comment -%}
+      The navbar's primary links are hidden below 960px, so the drawer carries
+      them. Hidden again on desktop, where the navbar shows them itself.
+    {%- endcomment -%}
+    <nav class="sidebar__primary" aria-label="Primary">
+      <a href="{{ '/' | relative_url }}"
+         class="sidebar__link{% if page.url == '/' %} is-active{% endif %}">
+        <i class="fa-solid fa-house" aria-hidden="true"></i>Home
+      </a>
+      {% for item in site.data.navigation.main %}
+        <a href="{{ item.url | relative_url }}"
+           class="sidebar__link{% if page.url contains item.url and item.url != '/' %} is-active{% endif %}">
+          {% if item.icon %}<i class="{{ item.icon }}" aria-hidden="true"></i>{% endif %}{{ item.title }}
+        </a>
+      {% endfor %}
+    </nav>
+
+    {% if show_docs %}
     <nav class="sidebar__nav">
       {% for group in site.data.navigation.sidebar %}
         {%- assign group_active = false -%}
@@ -40,6 +66,7 @@
         </div>
       {% endfor %}
     </nav>
+    {% endif %}
 
     {% if cfg.buy_me_a_coffee.username and cfg.buy_me_a_coffee.show_in contains "sidebar" %}
       <div class="sidebar__coffee">{% include buy-me-a-coffee.html %}</div>

data/_layouts/default.html

@@ -2,6 +2,13 @@
 {%- assign cfg = site.docsteer -%}
 {%- assign skin = cfg.skin | default: "aqua" -%}
 {%- assign mode = cfg.mode | default: "auto" -%}
+{%- comment -%}
+  Cache-busting token for the theme's own CSS and JS. Bumped with spec.version
+  in jekyll-theme-docsteer.gemspec: keyed to the theme's version rather than to
+  site.time so a content-only rebuild does not force every visitor to
+  re-download assets that did not change.
+{%- endcomment -%}
+{%- assign ds_version = "1.1.0" -%}
 <html lang="{{ site.lang | default: 'en' }}"
       data-skin="{{ skin }}"
       {% if mode != "auto" %}data-mode="{{ mode }}"{% endif %}>
@@ -24,8 +31,14 @@
     {%- assign show_sidebar = true -%}
   {%- endif -%}
 
+  {%- comment -%}
+    The aside is rendered on every page: below 960px it is the drawer the
+    navbar burger opens, and a page with no drawer leaves the burger dead and
+    the primary nav unreachable. Only `has-sidebar` — the desktop grid column —
+    is conditional.
+  {%- endcomment -%}
   <div class="page-shell{% if show_sidebar %} has-sidebar{% endif %}">
-    {% if show_sidebar %}{% include sidebar.html %}{% endif %}
+    {% include sidebar.html docs=show_sidebar %}
 
     <main id="main" class="page-main{% if show_sidebar %} has-sidebar{% endif %}" tabindex="-1">
       {{ content }}

data/_layouts/doc.html

@@ -10,9 +10,18 @@ layout: default
       {% if page.description %}<p class="doc-head__lead">{{ page.description }}</p>{% endif %}
 
       <div class="doc-head__meta">
-        {% if page.updated or page.date %}
+        {%- comment -%}
+          `last_modified_at` is the field jekyll-seo-tag reads for dateModified,
+          so using it here keeps this row and the structured data on one source.
+          `updated` is kept as a fallback for pages written against DocSteer 1.0.
+          `page.date` is last on purpose: Jekyll invents one equal to the build
+          time for collection documents that have none, so it is a date only in
+          the sense that it parses.
+        {%- endcomment -%}
+        {%- assign doc_date = page.last_modified_at | default: page.updated | default: page.date -%}
+        {% if doc_date %}
           <span><i class="fa-regular fa-clock" aria-hidden="true"></i>
-            Updated {{ page.updated | default: page.date | date: "%b %-d, %Y" }}</span>
+            Updated {{ doc_date | date: "%b %-d, %Y" }}</span>
         {% endif %}
         {% if page.read_time %}
           <span><i class="fa-regular fa-file-lines" aria-hidden="true"></i> {{ page.read_time }} min read</span>

data/_sass/docsteer/_content.scss

@@ -293,6 +293,15 @@ h4:hover > .heading-anchor, .heading-anchor:focus-visible { opacity: 1; }
 .doc-pager__title { font-weight: 600; color: var(--brand); line-height: 1.4; }
 
 .doc-tags { margin-top: var(--sp-6); display: flex; flex-wrap: wrap; gap: var(--sp-2); }
+.doc-tag {
+  transition: color var(--dur) var(--ease), background var(--dur) var(--ease),
+    border-color var(--dur) var(--ease);
+}
+.doc-tag:hover {
+  color: var(--brand-contrast);
+  background: var(--brand);
+  border-color: transparent;
+}
 
 @media (max-width: 560px) {
   .doc-pager { grid-template-columns: 1fr; }

data/_sass/docsteer/_home.scss

@@ -182,3 +182,29 @@
   .hero { padding-block: var(--sp-7) var(--sp-6); }
   .hero__search { margin-top: var(--sp-6); }
 }
+
+@media (max-width: 560px) {
+  // Narrow enough that .link-section__grid has collapsed to one column. A
+  // full-width tile with the icon stacked above two short lines is mostly
+  // empty space, so the icon moves into a left column and the tile becomes as
+  // short as its text. Tiles configured without an icon keep the stacked
+  // layout — there is no first column for them to fill.
+  // Tiles this short need the gap between them to read as bigger than the gap
+  // between a tile's own two lines, or the column reads as one block.
+  .link-section__grid { gap: var(--sp-4); }
+
+  .link-tile:has(> i) {
+    grid-template-columns: auto minmax(0, 1fr);
+    align-items: center;
+    column-gap: var(--sp-4);
+    row-gap: var(--sp-1);
+    padding: var(--sp-4);
+  }
+  .link-tile:has(> i) > i {
+    grid-row: 1 / span 2;
+    margin-bottom: 0;
+    font-size: 1.05rem;
+  }
+  .link-tile:has(> i) > .link-tile__title,
+  .link-tile:has(> i) > .link-tile__text { grid-column: 2; }
+}

data/_sass/docsteer/_lightbox.scss

@@ -28,6 +28,15 @@
   box-shadow: 0 24px 80px hsl(0 0% 0% / .5);
   animation: pop .18s var(--ease);
 }
+// An SVG carrying only a viewBox has no intrinsic size, so the rules above —
+// which cap, never grow — leave it at the browser's 300x150 default: it would
+// open SMALLER than it appears in the page. Raster images are deliberately not
+// covered, since stretching them would just upscale a small screenshot into a
+// blurry mess. Authors can also avoid this by putting width/height on the SVG.
+.lightbox__img[src$=".svg"] {
+  width: min(1100px, 94vw);
+  height: auto;
+}
 .lightbox__caption { color: hsl(0 0% 100% / .82); font-size: .88rem; text-align: center; }
 
 .lightbox__btn {

data/_sass/docsteer/_navbar.scss

@@ -164,6 +164,21 @@
   .navbar__links { display: none; }
 }
 @media (max-width: 560px) {
-  .brand__name { display: none; }
   .navbar__inner { gap: var(--sp-1); padding-inline: var(--sp-4); }
+
+  // The navbar is the only place on a phone that names the site — the hero
+  // headline is the page's title, not the project's. So the name stays and the
+  // brand is the one thing allowed to give way: the icon buttons hold their
+  // size, and a title too long for the row truncates instead of disappearing.
+  .brand { min-width: 0; }
+  .brand__name {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .navbar__burger,
+  .brand__mark,
+  .brand__logo,
+  .navbar__tools { flex: none; }
 }

data/_sass/docsteer/_sidebar.scss

@@ -8,6 +8,7 @@
   // (and runs the border the whole height of the page, which looks better).
   align-self: stretch;
 }
+.sidebar--drawer-only { display: none; }
 .sidebar.is-sticky .sidebar__inner {
   position: sticky;
   top: var(--nav-h);
@@ -53,6 +54,11 @@
 }
 .sidebar__search i { font-size: .85em; }
 
+// ── Primary nav (drawer only) ─────────────────────
+// The navbar hides its own links below 960px, so the drawer carries them.
+// Above that the navbar shows them and this would only be a duplicate.
+.sidebar__primary { display: none; }
+
 // ── Groups ───────────────────────────────────────────────────
 .sidebar__nav { display: grid; gap: var(--sp-1); }
 
@@ -156,4 +162,20 @@
   .sidebar.is-sticky .sidebar__inner { position: static; max-height: none; }
   .sidebar__inner { padding-top: calc(var(--nav-h) + var(--sp-4)); height: 100%; }
   .sidebar__link { min-height: 38px; }
+
+  // Pages with no documentation tree still render the aside, purely so the
+  // burger has a drawer to open. It exists only at drawer widths.
+  .sidebar--drawer-only { display: block; }
+
+  .sidebar__primary { display: grid; gap: 2px; }
+  .sidebar__primary .sidebar__link { gap: var(--sp-3); font-size: var(--fs-md); }
+  .sidebar__primary .sidebar__link > i { width: 1.1em; text-align: center; opacity: .8; }
+  // The active rail is drawn on the group's border-left, which this nav has no
+  // list to hang off — the marker would float in the padding.
+  .sidebar__primary .sidebar__link.is-active::before { content: none; }
+  .sidebar__primary + .sidebar__nav {
+    margin-top: var(--sp-5);
+    padding-top: var(--sp-5);
+    border-top: 1px solid var(--border);
+  }
 }

data/assets/js/search.js

@@ -17,14 +17,16 @@
 
   var MAX = parseInt(list.dataset.max, 10) || DocSteer.search.max || 8;
   var index = null;
-  var loading = false;
+  var indexPromise = null;
   var activeIdx = -1;
   var lastFocus = null;
 
+  // The in-flight promise is what gets cached, not a boolean: a second caller
+  // arriving mid-fetch has to wait for the same request, and the old `loading`
+  // flag resolved it with a null index instead.
   function loadIndex() {
-    if (index || loading) return Promise.resolve(index);
-    loading = true;
-    return fetch(list.dataset.endpoint || DocSteer.search.endpoint)
+    if (indexPromise) return indexPromise;
+    indexPromise = fetch(list.dataset.endpoint || DocSteer.search.endpoint)
       .then(function (r) { return r.json(); })
       .then(function (data) {
         index = data.map(function (d) {
@@ -37,10 +39,10 @@
               (d.category || "") + " " + (d.content || "")).toLowerCase()
           };
         });
-        loading = false;
         return index;
       })
-      .catch(function () { loading = false; return []; });
+      .catch(function () { indexPromise = null; return []; });
+    return indexPromise;
   }
 
   function scoreItem(item, terms, raw) {
@@ -118,37 +120,47 @@
     });
   }
 
+  function runSearch(raw) {
+    if (raw.length < 2) {
+      list.innerHTML = "";
+      empty.hidden = true;
+      hint.hidden = false;
+      input.setAttribute("aria-expanded", "false");
+      return;
+    }
+    loadIndex().then(function (idx) {
+      var terms = raw.split(/\s+/);
+      var scored = [];
+      for (var i = 0; i < idx.length; i++) {
+        var s = scoreItem(idx[i], terms, raw);
+        if (s > 0) scored.push({ item: idx[i], s: s });
+      }
+      scored.sort(function (a, b) { return b.s - a.s; });
+      render(scored.slice(0, MAX).map(function (x) { return x.item; }), terms);
+    });
+  }
+
   var debounce;
   function onInput() {
     clearTimeout(debounce);
     debounce = setTimeout(function () {
-      var raw = input.value.trim().toLowerCase();
-      if (raw.length < 2) {
-        list.innerHTML = "";
-        empty.hidden = true;
-        hint.hidden = false;
-        input.setAttribute("aria-expanded", "false");
-        return;
-      }
-      loadIndex().then(function (idx) {
-        var terms = raw.split(/\s+/);
-        var scored = [];
-        for (var i = 0; i < idx.length; i++) {
-          var s = scoreItem(idx[i], terms, raw);
-          if (s > 0) scored.push({ item: idx[i], s: s });
-        }
-        scored.sort(function (a, b) { return b.s - a.s; });
-        render(scored.slice(0, MAX).map(function (x) { return x.item; }), terms);
-      });
+      runSearch(input.value.trim().toLowerCase());
     }, 90);
   }
 
-  function open() {
+  // `query` opens the modal on a term rather than on an empty field — the doc
+  // footer's tags use it, so a tag lands on its results instead of on a blank
+  // search. select() leaves it highlighted, so typing still replaces it.
+  function open(query) {
     lastFocus = document.activeElement;
     modal.classList.add("is-open");
     modal.setAttribute("aria-hidden", "false");
     document.body.style.overflow = "hidden";
     loadIndex();
+    if (query) {
+      input.value = query;
+      runSearch(query.trim().toLowerCase());
+    }
     setTimeout(function () { input.focus(); input.select(); }, 20);
   }
   function close() {
@@ -159,7 +171,10 @@
   }
 
   $$("[data-search-open]").forEach(function (b) {
-    b.addEventListener("click", function (e) { e.preventDefault(); open(); });
+    b.addEventListener("click", function (e) {
+      e.preventDefault();
+      open(b.getAttribute("data-search-open"));
+    });
   });
   $$("[data-search-close]").forEach(function (b) {
     b.addEventListener("click", close);

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-theme-docsteer
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Cristian Castellari
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-01 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -168,7 +167,6 @@ metadata:
   plugin_type: theme
   source_code_uri: https://github.com/Skyflash/docsteer
   bug_tracker_uri: https://github.com/Skyflash/docsteer/issues
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -183,8 +181,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Simple, searchable docs and knowledge bases for teams.
 test_files: []