jekyll-toc-generator 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c6d4565912821695402aa8731d39c5fa37db228a1d913a43b1b1c081541dbca8
+  data.tar.gz: d1eb16a8e95e4cd052d9974b03175a41bef067a2fa5959221930138375c8a24f
+SHA512:
+  metadata.gz: 4d1d48cfe71db0b1a126ed5ea41c4c61b3aba641d9d9c2b536cd7aa46ff02d6fe75c124810970bcef33dde90553a4681f36417aae6ee877a2c7a65bc4783f67b
+  data.tar.gz: 585b4df874534717b07f4b948569cf3aa951bb2d5e691b501d2cf05a4913eab3b794611167831b356b11f21023ed1c643c677ee253de61d177e757b6f2eb1378

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jason Chance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,135 @@
+# jekyll-toc-generator
+
+Hook-based table of contents injection for Jekyll. Posts and pages with `toc: true` in frontmatter automatically get a TOC injected — no Liquid tag required in the content.
+
+## Installation
+
+Add to your Jekyll site's `Gemfile`:
+
+```ruby
+gem "jekyll-toc-generator"
+```
+
+Then add to `_config.yml`:
+
+```yaml
+plugins:
+  - jekyll-toc-generator
+```
+
+Run `bundle install`.
+
+## Usage
+
+Add `toc: true` to any post or page frontmatter:
+
+```yaml
+---
+title: My Long Post
+toc: true
+---
+```
+
+The plugin automatically injects a `<nav class="toc">` element immediately before the first `<h2>` in the rendered HTML. No Liquid tag needed.
+
+## Configuration
+
+All options are optional. Add to `_config.yml`:
+
+```yaml
+toc:
+  min_headings: 2      # don't inject TOC if fewer than N h2s (default: 2)
+  title: "Contents"   # TOC nav title (default: "Table of Contents")
+  levels: [2, 3]       # heading levels to include (default: [2, 3])
+```
+
+### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `min_headings` | `2` | Minimum number of `<h2>` elements required to inject a TOC |
+| `title` | `"Table of Contents"` | Text shown in the TOC `<h2>` title |
+| `levels` | `[2, 3]` | Heading levels to include in the TOC |
+
+## TOC HTML Structure
+
+```html
+<nav class="toc" aria-label="Table of contents">
+  <h2 class="toc__title">Table of Contents</h2>
+  <ul class="toc__list">
+    <li class="toc__item"><a href="#heading-slug">Heading Text</a>
+      <ul class="toc__sublist">
+        <li class="toc__item--sub"><a href="#sub-heading-slug">Sub Heading</a></li>
+      </ul>
+    </li>
+  </ul>
+</nav>
+```
+
+### CSS Classes
+
+| Class | Element | Description |
+|---|---|---|
+| `.toc` | `<nav>` | Outer TOC container |
+| `.toc__title` | `<h2>` | TOC section title |
+| `.toc__list` | `<ul>` | Top-level heading list |
+| `.toc__item` | `<li>` | Top-level heading item |
+| `.toc__sublist` | `<ul>` | Nested subheading list |
+| `.toc__item--sub` | `<li>` | Subheading item |
+
+### Example CSS
+
+```css
+.toc {
+  background: #f8f8f8;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  padding: 1rem 1.5rem;
+  margin-bottom: 2rem;
+  display: inline-block;
+  min-width: 200px;
+}
+
+.toc__title {
+  font-size: 1rem;
+  margin: 0 0 0.5rem;
+  font-weight: 600;
+}
+
+.toc__list,
+.toc__sublist {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.toc__sublist {
+  padding-left: 1rem;
+}
+
+.toc__item,
+.toc__item--sub {
+  margin: 0.25rem 0;
+}
+```
+
+## Slug Generation
+
+Heading IDs are slugified to match Jekyll's default anchor generation:
+
+- Lowercase
+- Non-alphanumeric characters removed
+- Spaces and underscores replaced with `-`
+- Leading/trailing hyphens stripped
+
+Example: `"What's New?"` → `#whats-new`
+
+## Requirements
+
+- Jekyll >= 4.0
+- Ruby >= 2.7
+- No additional gem dependencies (pure Ruby, no Nokogiri)
+
+## License
+
+MIT © Jason Chance 2025

data/lib/jekyll/toc_generator.rb

@@ -0,0 +1,10 @@
+require "jekyll-toc-generator/version"
+require "jekyll-toc-generator/toc_builder"
+
+Jekyll::Hooks.register [:posts, :pages, :documents], :post_render do |doc|
+  next unless doc.data["toc"] == true
+
+  config = doc.site.config["toc"] || {}
+  builder = Jekyll::TocGenerator::TocBuilder.new(doc.output, config)
+  doc.output = builder.build
+end

data/lib/jekyll-toc-generator/toc_builder.rb

@@ -0,0 +1,101 @@
+module Jekyll
+  module TocGenerator
+    class TocBuilder
+      def initialize(html, config = {})
+        @html = html
+        @min_headings = config["min_headings"] || 2
+        @title = config["title"] || "Table of Contents"
+        @levels = config["levels"] || [2, 3]
+      end
+
+      def build
+        return @html if @html.nil? || @html.empty?
+
+        headings = extract_headings
+        h2s = headings.select { |h| h[:level] == 2 }
+        return @html if h2s.size < @min_headings
+
+        toc_html = build_toc(headings)
+        inject_toc(toc_html)
+      end
+
+      private
+
+      def extract_headings
+        levels_pattern = @levels.map(&:to_s).join
+        headings = []
+        @html.scan(/<h([#{levels_pattern}])[^>]*>(.*?)<\/h\1>/im) do |level, content|
+          text = strip_tags(content)
+          headings << { level: level.to_i, text: text, slug: slugify(text) }
+        end
+        headings
+      end
+
+      def strip_tags(html)
+        html.gsub(/<[^>]+>/, "").strip
+      end
+
+      def slugify(text)
+        text.downcase.gsub(/[^\w\s-]/, "").gsub(/[\s_]+/, "-").gsub(/^-+|-+$/, "")
+      end
+
+      def build_toc(headings)
+        items_html = build_items(headings)
+        <<~HTML
+          <nav class="toc" aria-label="Table of contents">
+            <h2 class="toc__title">#{@title}</h2>
+            <ul class="toc__list">
+          #{items_html.chomp}
+            </ul>
+          </nav>
+        HTML
+      end
+
+      def build_items(headings)
+        html = ""
+        current_h2 = nil
+        pending_subs = []
+
+        flush = lambda do
+          if current_h2
+            html += "    <li class=\"toc__item\"><a href=\"##{current_h2[:slug]}\">#{current_h2[:text]}</a>"
+            unless pending_subs.empty?
+              html += "\n      <ul class=\"toc__sublist\">\n"
+              pending_subs.each do |sub|
+                html += "        <li class=\"toc__item--sub\"><a href=\"##{sub[:slug]}\">#{sub[:text]}</a></li>\n"
+              end
+              html += "      </ul>\n    "
+            end
+            html += "</li>\n"
+            pending_subs = []
+            current_h2 = nil
+          end
+        end
+
+        headings.each do |h|
+          if h[:level] == 2
+            flush.call
+            current_h2 = h
+          else
+            if current_h2
+              pending_subs << h
+            else
+              # h3 with no preceding h2 — treat as top-level
+              html += "    <li class=\"toc__item\"><a href=\"##{h[:slug]}\">#{h[:text]}</a></li>\n"
+            end
+          end
+        end
+
+        flush.call
+        html
+      end
+
+      def inject_toc(toc_html)
+        first_h2 = @html.match(/<h2[^>]*>/i)
+        return @html unless first_h2
+
+        @html.sub(first_h2[0], toc_html.chomp + first_h2[0])
+      end
+    end
+  end
+end

data/lib/jekyll-toc-generator/version.rb

@@ -0,0 +1,5 @@
+module Jekyll
+  module TocGenerator
+    VERSION = "0.1.0"
+  end
+end

data/lib/jekyll-toc-generator.rb

@@ -0,0 +1,3 @@
+require "jekyll-toc-generator/version"
+require "jekyll-toc-generator/toc_builder"
+require "jekyll/toc_generator"

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-toc-generator
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jason Chance
+bindir: bin
+cert_chain: []
+date: 2026-08-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+email:
+- jason@jasonchance.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/jekyll-toc-generator.rb
+- lib/jekyll-toc-generator/toc_builder.rb
+- lib/jekyll-toc-generator/version.rb
+- lib/jekyll/toc_generator.rb
+homepage: https://github.com/jchance/jekyll-toc-generator
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Hook-based table of contents injection for Jekyll — no Liquid tag needed.
+test_files: []