jekyll-jtd-toc-nav 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 127c3ffb6cd3c92d01d52561f1c63542b3bd4b34a90c5d8c917c1eb267f0fbe4
+  data.tar.gz: d5ec6bff6a17bd9e09670665210377b938395fcae2869d807e9fdbf88284d780
+SHA512:
+  metadata.gz: 4a182031953e79e0174e8ccb203d99e6b112084deda67e18c37475302ff7c789f44b8ff0c6db9b6a2369d72212afbb6490a52e95c185bcfd01386be72ba24784
+  data.tar.gz: 2cae035deb850bccf172eae0af34225983ac545494e994da7b0db98e4fe4c9f9a9caeafcd3a8199a5a1e5674e3f314082f216881c1e4f2268cdf91220ffeac6e

data/lib/jekyll/jtd_toc_nav/injector.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module JtdTocNav
+    class Injector
+      DEFAULT_LEVELS = (2..4).to_a
+
+      def initialize(site:)
+        @site = site
+      end
+
+      def levels
+        raw = @site.config["sidebar_toc_levels"]
+        return DEFAULT_LEVELS if raw.nil?
+
+        if raw.is_a?(String) && raw.include?("..")
+          a, b = raw.split("..", 2).map { |x| Integer(x) rescue nil }
+          return DEFAULT_LEVELS if a.nil? || b.nil?
+          return (a..b).to_a
+        end
+
+        if raw.is_a?(Array)
+          ints = raw.map { |x| Integer(x) rescue nil }.compact
+          return DEFAULT_LEVELS if ints.empty?
+          return ints
+        end
+
+        DEFAULT_LEVELS
+      end
+
+      def expand_all?
+        @site.config.fetch("sidebar_toc_expand", true) != false
+      end
+
+      def process!(page_like)
+        return if page_like.output.nil? || page_like.output.empty?
+
+        html = page_like.output
+        doc = Nokogiri::HTML(html)
+
+        headings = extract_headings(doc)
+        return if headings.empty?
+
+        nav = doc.at_css("#site-nav")
+        return unless nav
+
+        page_url = page_like.url
+        link = find_nav_link(nav, page_url)
+        return unless link
+
+        nav_item = link.ancestors("li.nav-list-item").first
+        return unless nav_item
+
+        # Remove any prior injection
+        nav_item.css("> ul.nav-list[data-jtd-toc-nav='true']").remove
+
+        outline_ul = build_outline_ul(doc, headings)
+        outline_ul["data-jtd-toc-nav"] = "true"
+
+        # Ensure current page can expand/collapse like other nav items.
+        ensure_expander!(doc, nav_item, label: "Toggle page sections")
+
+        nav_item.add_class("active")
+        nav_item.add_child(outline_ul)
+
+        page_like.output = doc.to_html
+      rescue StandardError => e
+        Jekyll.logger.warn("jtd-toc-nav:", "failed to inject sidebar toc for #{page_like.url}: #{e.class}: #{e.message}")
+      end
+
+      private
+
+      def extract_headings(doc)
+        selector = levels.map { |lvl| "main h#{lvl}" }.join(", ")
+        doc.css(selector).filter_map do |h|
+          next if h["id"].to_s.empty?
+          classes = h["class"].to_s.split(/\s+/)
+          next if classes.include?("no_toc")
+          # Dont pull headings from the TOC itself if it exists in content.
+          next if h.ancestors.any? { |a| a["id"] == "markdown-toc" || a["class"].to_s.split(/\s+/).include?("js-page-toc") }
+
+          {
+            id: h["id"],
+            text: h.text.strip,
+            level: h.name.delete_prefix("h").to_i
+          }
+        end
+      end
+
+      def find_nav_link(nav, page_url)
+        baseurl = @site.config["baseurl"].to_s
+        baseurl = "" if baseurl == "/"
+
+        # Match just-the-docs trailing slash / .html.
+        candidates = []
+        candidates << page_url
+        candidates << "#{page_url}/" unless page_url.end_with?("/")
+        candidates << "#{page_url}.html" unless page_url.end_with?(".html")
+        candidates = candidates.uniq
+
+        candidates = candidates.flat_map do |u|
+          if baseurl.empty?
+            [u]
+          else
+            [u, File.join(baseurl, u)]
+          end
+        end.uniq
+
+        candidates.each do |href|
+          link = nav.at_css(%(a.nav-list-link[href="#{css_escape(href)}"]))
+          return link if link
+        end
+
+        nil
+      end
+
+      def css_escape(s)
+        # Minimal escape for quotes/backslashes in attribute selectors.
+        s.to_s.gsub("\\", "\\\\").gsub('"', '\"')
+      end
+
+      def build_outline_ul(doc, headings)
+        min_level = headings.map { |h| h[:level] }.min
+        stack = []
+
+        root_ul = Nokogiri::XML::Node.new("ul", doc)
+        root_ul["class"] = "nav-list"
+        stack << { level: min_level - 1, ul: root_ul }
+
+        headings.each_with_index do |h, idx|
+          while stack.size > 1 && h[:level] <= stack.last[:level]
+            stack.pop
+          end
+
+          while h[:level] > stack.last[:level] + 1
+            # Skip missing intermediate levels by treating as direct child.
+            stack.last[:level] += 1
+          end
+
+          li = Nokogiri::XML::Node.new("li", doc)
+          li["class"] = "nav-list-item"
+
+          a = Nokogiri::XML::Node.new("a", doc)
+          a["class"] = "nav-list-link"
+          a["href"] = "##{h[:id]}"
+          a.content = h[:text]
+          li.add_child(a)
+
+          parent_ul = stack.last[:ul]
+          parent_ul.add_child(li)
+
+          next_h = headings[idx + 1]
+          has_children = next_h && next_h[:level] > h[:level]
+          next unless has_children
+
+          # This heading has subheadings. Nest them
+          child_ul = Nokogiri::XML::Node.new("ul", doc)
+          child_ul["class"] = "nav-list"
+          li.add_child(child_ul)
+
+          # jtd hides nested `.nav-list` by default.
+          ensure_expander!(doc, li, label: "Toggle section")
+          li.add_class("active") if expand_all?
+
+          stack << { level: h[:level], ul: child_ul }
+        end
+
+        root_ul
+      end
+
+      def ensure_expander!(doc, li, label:)
+        existing = li.at_css("> button.nav-list-expander")
+        return existing if existing
+
+        button = Nokogiri::XML::Node.new("button", doc)
+        button["class"] = "nav-list-expander btn-reset"
+        button["aria-label"] = label
+        button["aria-expanded"] = li["class"].to_s.split(/\s+/).include?("active") ? "true" : "false"
+        button.inner_html = '<svg viewBox="0 0 24 24" aria-hidden="true"><use xlink:href="#svg-arrow-right"></use></svg>'
+
+        li.children.first.add_previous_sibling(button)
+        button
+      end
+    end
+  end
+end
+
+Jekyll::Hooks.register([:pages, :documents], :post_render) do |page, payload|
+  # Jekyll 3.x hook signature may pass `payload` as nil.
+  site = page.respond_to?(:site) ? page.site : nil
+  site ||= payload.is_a?(Hash) ? payload["site"] : nil
+  next unless site
+
+  injector = site.config["__jtd_toc_nav_injector"] ||= Jekyll::JtdTocNav::Injector.new(site: site)
+  injector.process!(page)
+end
+

data/lib/jekyll-jtd-toc-nav.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "jekyll"
+require "nokogiri"
+
+require_relative "jekyll/jtd_toc_nav/injector"
+
+module Jekyll
+  module JtdTocNav
+  end
+end
+

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-jtd-toc-nav
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- directsun
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+email: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/jekyll-jtd-toc-nav.rb
+- lib/jekyll/jtd_toc_nav/injector.rb
+homepage: https://github.com/sunflowermans/toc-navigation
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.8'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Inject page heading outline into Just the Docs sidebar nav
+test_files: []