jekyll-vitepress-theme 1.7.0 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4843e410a1321baff08b82bd739e58ad72cdb1657445c37f3b2bc30aa59c57ef
-  data.tar.gz: c974fe75def3a63663a0e2c320798882af8b6878a2fc3261549187a384ce17a8
+  metadata.gz: 7ca0f243e32e2dd051ee2c8bd0c073ec5ab1d2469d05e606531df740508a036f
+  data.tar.gz: caac258aed1a827394fdf8f6f239d81a6978b297567d5558c8433ead4504ded9
 SHA512:
-  metadata.gz: 146ac84e6b757422be14c5e206b4f0525e271f4bd45afdd70f47dad1388799765a6e6563d4ad45e88b7fb0dee3ebe7a4ea97d85220f62b760740d915383d2fcd
-  data.tar.gz: 2e99432a58ccbfaf1838acd5b7ddaf0d8e62a3b73e44b90fddcf8f369555bab65fa352c251c747eae46cd69dd14987bdda2366ab5ffebdb8faf44c7b1756c2dc
+  metadata.gz: 04b1d2d66942c3c0e8277955be4936e268a8f7cbc0d3a818e6e7685ca7cc6b89f35944b252444ce708f6334a48e5d2a8cf62f55a3bcb707669c5fe33616db39d
+  data.tar.gz: 3d72ee616cf769d5c242de1bd5a0de440187206ecece4574fab664a5d98fc12efb0597b8dc1e2995c356602ba66676e351ffb3112b1fbe3c04f532ceec431bf6

data/_includes/doc_footer.html

@@ -56,7 +56,14 @@
 {% assign prev_doc = nil %}
 {% assign next_doc = nil %}
 {% if page.collection %}
-  {% assign docs = site[page.collection] | sort: 'nav_order' %}
+  {% assign generated_sidebar = site.data.jekyll_vitepress_sidebar %}
+  {% assign sidebar_collections = generated_sidebar.collections %}
+  {% assign sidebar_collection = sidebar_collections[page.collection] %}
+  {% if sidebar_collection and sidebar_collection.docs %}
+    {% assign docs = sidebar_collection.docs %}
+  {% else %}
+    {% assign docs = site[page.collection] | sort: 'nav_order' %}
+  {% endif %}
   {% assign found_current = false %}
   {% for doc in docs %}
     {% if found_current and next_doc == nil %}

data/_includes/sidebar.html

@@ -3,42 +3,60 @@
   <nav class="nav" id="VPSidebarNav" aria-labelledby="sidebar-aria-label" tabindex="-1">
     <span class="visually-hidden" id="sidebar-aria-label">Sidebar Navigation</span>
 
-    {% assign sidebar_groups = site.data.sidebar %}
+    {% assign generated_sidebar = site.data.jekyll_vitepress_sidebar %}
+    {% assign sidebar_groups = generated_sidebar.groups | default: site.data.sidebar %}
     {% for group in sidebar_groups %}
-      {% assign docs = site[group.collection] | sort: 'nav_order' %}
-      {% if docs.size > 0 %}
+      {% if group.items %}
+        {% assign sidebar_items = group.items %}
+      {% else %}
+        {% assign docs = site[group.collection] | sort: 'nav_order' %}
+        {% assign sidebar_items = docs %}
+      {% endif %}
+      {% if sidebar_items.size > 0 %}
         {% assign has_active = false %}
-        {% for doc in docs %}
-          {% if doc.url == page.url %}
-            {% assign has_active = true %}
-          {% endif %}
-        {% endfor %}
+        {% if group.active_urls contains page.url %}
+          {% assign has_active = true %}
+        {% else %}
+          {% for doc in docs %}
+            {% if doc.url == page.url %}
+              {% assign has_active = true %}
+            {% endif %}
+          {% endfor %}
+        {% endif %}
+        {% assign collapsed = false %}
+        {% if group.collapsed and has_active == false %}
+          {% assign collapsed = true %}
+        {% endif %}
 
         <div class="group no-transition">
-          <section class="VPSidebarItem level-0 collapsible{% if has_active %} has-active{% endif %}" data-vp-sidebar-group data-collection="{{ group.collection }}">
-            <div class="item" role="button" tabindex="0">
+          <section class="VPSidebarItem level-0 collapsible{% if has_active %} has-active{% endif %}{% if collapsed %} collapsed{% endif %}" data-vp-sidebar-group data-collection="{{ group.collection }}">
+            <div class="item" role="button" tabindex="0" aria-expanded="{% if collapsed %}false{% else %}true{% endif %}">
               <div class="indicator"></div>
               <h2 class="text">{{ group.title }}</h2>
-              <div class="caret" role="button" aria-label="toggle section" tabindex="0">
+              <div class="caret" role="button" aria-label="toggle section" tabindex="0" aria-expanded="{% if collapsed %}false{% else %}true{% endif %}">
                 <span class="vpi-chevron-right caret-icon"></span>
               </div>
             </div>
 
             <div class="items">
-              {% for doc in docs %}
-                {% assign active = false %}
-                {% if doc.url == page.url %}
-                  {% assign active = true %}
-                {% endif %}
-                <div class="VPSidebarItem level-1 is-link{% if active %} is-active{% endif %}">
-                  <div class="item">
-                    <div class="indicator"></div>
-                    <a class="VPLink link link" href="{{ doc.url | relative_url }}" data-vp-sidebar-link data-turbo="true" data-turbo-frame="vp-content-frame" data-turbo-action="advance">
-                      <p class="text">{{ doc.title }}</p>
-                    </a>
+              {% if group.items %}
+                {% include sidebar_items.html nodes=group.items level=1 %}
+              {% else %}
+                {% for doc in docs %}
+                  {% assign active = false %}
+                  {% if doc.url == page.url %}
+                    {% assign active = true %}
+                  {% endif %}
+                  <div class="VPSidebarItem level-1 is-link{% if active %} is-active{% endif %}">
+                    <div class="item">
+                      <div class="indicator"></div>
+                      <a class="VPLink link link" href="{{ doc.url | relative_url }}" data-vp-sidebar-link data-turbo="true" data-turbo-frame="vp-content-frame" data-turbo-action="advance">
+                        <p class="text">{{ doc.title }}</p>
+                      </a>
+                    </div>
                   </div>
-                </div>
-              {% endfor %}
+                {% endfor %}
+              {% endif %}
             </div>
           </section>
         </div>

data/_includes/sidebar_items.html

@@ -0,0 +1,41 @@
+{% for node in include.nodes %}
+  {% assign item_level = include.level | default: 1 %}
+  {% assign doc = node.doc %}
+  {% assign has_children = false %}
+  {% if node.children and node.children.size > 0 %}
+    {% assign has_children = true %}
+  {% endif %}
+  {% assign active = false %}
+  {% if node.url == page.url %}
+    {% assign active = true %}
+  {% endif %}
+  {% assign has_active = false %}
+  {% if node.active_urls contains page.url %}
+    {% assign has_active = true %}
+  {% endif %}
+  {% assign collapsed = false %}
+  {% if node.collapsed and has_active == false %}
+    {% assign collapsed = true %}
+  {% endif %}
+
+  <div class="VPSidebarItem level-{{ item_level }} is-link{% if has_children %} collapsible{% endif %}{% if active %} is-active{% endif %}{% if has_active %} has-active{% endif %}{% if collapsed %} collapsed{% endif %}">
+    <div class="item"{% if has_children %} aria-expanded="{% if collapsed %}false{% else %}true{% endif %}"{% endif %}>
+      <div class="indicator"></div>
+      <a class="VPLink link link" href="{{ node.url | relative_url }}" data-vp-sidebar-link data-turbo="true" data-turbo-frame="vp-content-frame" data-turbo-action="advance">
+        <p class="text">{{ node.title | default: doc.title }}</p>
+      </a>
+      {% if has_children %}
+        <div class="caret" role="button" aria-label="toggle section" tabindex="0" aria-expanded="{% if collapsed %}false{% else %}true{% endif %}">
+          <span class="vpi-chevron-right caret-icon"></span>
+        </div>
+      {% endif %}
+    </div>
+
+    {% if has_children %}
+      <div class="items">
+        {% assign child_level = item_level | plus: 1 %}
+        {% include sidebar_items.html nodes=node.children level=child_level %}
+      </div>
+    {% endif %}
+  </div>
+{% endfor %}

data/assets/js/vitepress-theme.js

@@ -684,12 +684,28 @@
   syncNavTop();
   window.addEventListener('scroll', syncNavTop, { passive: true });
 
-  document.querySelectorAll('.VPSidebarItem.level-0.collapsible').forEach(function (section) {
+  function setSidebarSectionCollapsed(section, collapsed) {
+    section.classList.toggle('collapsed', collapsed);
+
+    var item = section.querySelector(':scope > .item');
+    var caret = section.querySelector(':scope > .item .caret');
+    var expanded = String(!collapsed);
+
+    if (item) {
+      item.setAttribute('aria-expanded', expanded);
+    }
+
+    if (caret) {
+      caret.setAttribute('aria-expanded', expanded);
+    }
+  }
+
+  document.querySelectorAll('.VPSidebarItem.collapsible').forEach(function (section) {
     var item = section.querySelector(':scope > .item');
     var caret = section.querySelector(':scope > .item .caret');
 
     function toggleSection() {
-      section.classList.toggle('collapsed');
+      setSidebarSectionCollapsed(section, !section.classList.contains('collapsed'));
     }
 
     if (item) {
@@ -701,6 +717,10 @@
       });
 
       item.addEventListener('keydown', function (event) {
+        if (event.target.closest('a')) {
+          return;
+        }
+
         if (event.key === 'Enter' || event.key === ' ') {
           event.preventDefault();
           toggleSection();
@@ -2174,7 +2194,7 @@
       return null;
     }
 
-    var activeItems = Array.from(sidebar.querySelectorAll('.VPSidebarItem.level-1.is-link.is-active'));
+    var activeItems = Array.from(sidebar.querySelectorAll('.VPSidebarItem.is-link.is-active'));
 
     if (!activeItems.length) {
       return null;
@@ -2212,16 +2232,19 @@
     }
 
     document.querySelectorAll('[data-vp-sidebar-link]').forEach(function (link) {
-      var item = link.closest('.VPSidebarItem.level-1.is-link');
+      var item = link.closest('.VPSidebarItem.is-link');
       var active = normalizePathname(link.getAttribute('href')) === currentPath;
       if (item) {
         item.classList.toggle('is-active', active);
       }
     });
 
-    document.querySelectorAll('[data-vp-sidebar-group]').forEach(function (group) {
-      var hasActiveLink = !!group.querySelector('.VPSidebarItem.level-1.is-link.is-active');
+    document.querySelectorAll('.VPSidebarItem.collapsible').forEach(function (group) {
+      var hasActiveLink = group.classList.contains('is-active') || !!group.querySelector('.VPSidebarItem.is-link.is-active');
       group.classList.toggle('has-active', hasActiveLink);
+      if (hasActiveLink) {
+        setSidebarSectionCollapsed(group, false);
+      }
     });
 
     document.querySelectorAll('[data-vp-nav-link]').forEach(function (link) {

data/lib/jekyll/vitepress_theme/hooks.rb

@@ -3,6 +3,231 @@ require 'rouge'
 
 module Jekyll
   module VitePressTheme
+    # rubocop:disable Metrics/ModuleLength
+    module Sidebar
+      module_function
+
+      DATA_KEY = 'jekyll_vitepress_sidebar'.freeze
+      MAX_ITEM_LEVEL = 5
+
+      def apply(site)
+        generated_sidebar = generate(site)
+        site.data[DATA_KEY] = generated_sidebar if generated_sidebar
+      rescue StandardError => e
+        Jekyll.logger.warn('jekyll-vitepress-theme', "Sidebar hierarchy generation failed: #{e.message}")
+      end
+
+      def generate(site)
+        sidebar_groups = site.data['sidebar']
+        return nil unless sidebar_groups.respond_to?(:each)
+
+        groups = sidebar_groups.filter_map { |group| generated_group(site, group) }
+
+        {
+          'groups' => groups,
+          'collections' => groups.to_h { |group| [group['collection'], collection_data(group)] }
+        }
+      end
+
+      def generated_group(site, group)
+        collection_name = group_value(group, 'collection')
+        docs = collection_docs(site, collection_name)
+        return nil if docs.empty?
+
+        collection_data = build_collection(collection_name, docs)
+        return nil if collection_data['docs'].empty?
+
+        group_hash(group).merge(collection_data)
+      end
+
+      def collection_data(group)
+        group.slice('collection', 'items', 'docs', 'active_urls')
+      end
+
+      def build_collection(collection_name, docs)
+        ordered_docs = sort_docs(docs)
+        nodes = ordered_docs.to_h { |doc| [doc, node_for(doc)] }
+        roots = attach_nodes(collection_name, ordered_docs, nodes)
+
+        finalize_nodes(roots, 1)
+        flat_docs = flatten_docs(roots)
+        {
+          'collection' => collection_name.to_s,
+          'items' => roots,
+          'docs' => flat_docs,
+          'active_urls' => flat_docs.filter_map { |doc| doc_url(doc) }
+        }
+      end
+
+      def attach_nodes(collection_name, docs, nodes)
+        docs.each_with_object([]) do |doc, roots|
+          parent_doc = parent_doc_for(doc, docs)
+          if valid_parent?(doc, parent_doc, docs)
+            nodes[parent_doc]['children'] << nodes[doc]
+          else
+            warn_missing_parent(collection_name, doc) if parent_title(doc)
+            roots << nodes[doc]
+          end
+        end
+      end
+
+      def valid_parent?(doc, parent_doc, docs)
+        parent_doc && !attaching_creates_cycle?(doc, parent_doc, docs)
+      end
+
+      def collection_docs(site, collection_name)
+        return [] unless collection_name
+
+        collection = site.collections[collection_name.to_s]
+        return [] unless collection
+
+        collection.docs
+      end
+
+      def group_hash(group)
+        return group if group.is_a?(Hash)
+
+        group.respond_to?(:to_h) ? group.to_h : {}
+      end
+
+      def group_value(group, key)
+        group_hash(group)[key] || group_hash(group)[key.to_sym]
+      end
+
+      def sort_docs(docs)
+        docs.sort_by { |doc| sort_key(doc) }
+      end
+
+      def sort_key(doc)
+        nav_order = data_value(doc, 'nav_order')
+        order_bucket = nav_order.nil? ? 1 : 0
+        numeric_order = numeric?(nav_order)
+        order_type = numeric_order ? 0 : 1
+        order_value = numeric_order ? nav_order.to_f : nav_order.to_s
+
+        [order_bucket, order_type, order_value, title(doc).downcase, doc_url(doc).to_s]
+      end
+
+      def numeric?(value)
+        value.is_a?(Numeric) || value.to_s.match?(/\A-?\d+(?:\.\d+)?\z/)
+      end
+
+      def node_for(doc)
+        {
+          'doc' => doc,
+          'title' => title(doc),
+          'url' => doc_url(doc),
+          'collapsed' => truthy?(data_value(doc, 'collapsed')),
+          'children' => [],
+          'active_urls' => []
+        }
+      end
+
+      def parent_doc_for(doc, docs)
+        direct_parent = parent_title(doc)
+        return nil unless direct_parent
+
+        candidates = docs.select { |candidate| candidate != doc && title(candidate) == direct_parent }
+        grand_parent = normalized_string(data_value(doc, 'grand_parent'))
+        return candidates.first unless grand_parent
+
+        candidates.find { |candidate| ancestor_titles(candidate, docs).include?(grand_parent) }
+      end
+
+      def attaching_creates_cycle?(doc, parent_doc, docs)
+        current = parent_doc
+        seen = []
+
+        while current
+          return true if current == doc || seen.include?(current)
+
+          seen << current
+          current = parent_doc_for(current, docs)
+        end
+
+        false
+      end
+
+      def ancestor_titles(doc, docs)
+        titles = []
+        current = parent_doc_for(doc, docs)
+        seen = []
+
+        while current && !seen.include?(current)
+          seen << current
+          titles << title(current)
+          current = parent_doc_for(current, docs)
+        end
+
+        titles
+      end
+
+      def finalize_nodes(nodes, level)
+        nodes.sort_by! { |node| sort_key(node['doc']) }
+        nodes.each do |node|
+          finalize_children(node, level)
+
+          node['active_urls'] = [node['url'], *node['children'].flat_map { |child| child['active_urls'] }].compact
+        end
+      end
+
+      def finalize_children(node, level)
+        if level >= MAX_ITEM_LEVEL
+          warn_depth_limit(node) unless node['children'].empty?
+          node['children'] = []
+        else
+          finalize_nodes(node['children'], level + 1)
+        end
+      end
+
+      def flatten_docs(nodes)
+        nodes.flat_map do |node|
+          [node['doc'], *flatten_docs(node['children'])]
+        end
+      end
+
+      def data_value(doc, key)
+        data = doc.respond_to?(:data) ? doc.data : {}
+        data[key] || data[key.to_sym]
+      end
+
+      def title(doc)
+        normalized_string(data_value(doc, 'title')) || ''
+      end
+
+      def parent_title(doc)
+        normalized_string(data_value(doc, 'parent'))
+      end
+
+      def doc_url(doc)
+        doc.url if doc.respond_to?(:url)
+      end
+
+      def normalized_string(value)
+        string = value.to_s.strip
+        string.empty? ? nil : string
+      end
+
+      def truthy?(value)
+        value == true || value.to_s.casecmp('true').zero?
+      end
+
+      def warn_missing_parent(collection_name, doc)
+        Jekyll.logger.warn(
+          'jekyll-vitepress-theme',
+          "Missing sidebar parent '#{parent_title(doc)}' for '#{title(doc)}' in #{collection_name}; rendering it at the collection root."
+        )
+      end
+
+      def warn_depth_limit(node)
+        Jekyll.logger.warn(
+          'jekyll-vitepress-theme',
+          "Sidebar item '#{node['title']}' is deeper than #{MAX_ITEM_LEVEL} item levels; nested children were not rendered."
+        )
+      end
+    end
+    # rubocop:enable Metrics/ModuleLength
+
     module SearchIndex
       module_function
 
@@ -19,9 +244,14 @@ module Jekyll
           }
           {% assign first = false %}
         {% endif %}
-        {% assign sidebar_groups = site.data.sidebar %}
+        {% assign generated_sidebar = site.data.jekyll_vitepress_sidebar %}
+        {% assign sidebar_groups = generated_sidebar.groups | default: site.data.sidebar %}
         {% for group in sidebar_groups %}
-          {% assign docs = site[group.collection] | sort: 'nav_order' %}
+          {% if group.docs %}
+            {% assign docs = group.docs %}
+          {% else %}
+            {% assign docs = site[group.collection] | sort: 'nav_order' %}
+          {% endif %}
           {% for doc in docs %}
             {% if doc.title and doc.url %}
               {% unless first %},{% endunless %}
@@ -236,6 +466,7 @@ end
 Jekyll::Hooks.register :site, :post_read do |site|
   Jekyll::VitePressTheme::VersionLabel.apply(site)
   Jekyll::VitePressTheme::RougeStyles.apply(site)
+  Jekyll::VitePressTheme::Sidebar.apply(site)
   Jekyll::VitePressTheme::SearchIndex.apply(site)
 end
 

data/lib/jekyll/vitepress_theme/version.rb

@@ -1,5 +1,5 @@
 module Jekyll
   module VitePressTheme
-    VERSION = "1.7.0".freeze
+    VERSION = "1.8.0".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-vitepress-theme
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.8.0
 platform: ruby
 authors:
 - Carmine Paolino
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-16 00:00:00.000000000 Z
+date: 2026-06-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -79,6 +79,7 @@ files:
 - _includes/rubygems_downloads_button.html
 - _includes/search.html
 - _includes/sidebar.html
+- _includes/sidebar_items.html
 - _includes/version_link.html
 - _includes/vp_image.html
 - _layouts/default.html