jekyll-toc-plus 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7673dcb756b228f2940af9eb43c7e2e18bb42afd1aae9a508da44991d67c3428
-  data.tar.gz: f44af3e46bad9e0339246603ae38409ce2ef7301c1d5003bf5f86a5267fa2d0c
+  metadata.gz: 9d7d885bed409b2179feb9778b06baf21181d9beaa1afbcb8579e8b642bf2fb6
+  data.tar.gz: ae7409264bb42c87b72de4a527a6e0e8a77c5f8cc638a5bdf17093d4a39fb2c3
 SHA512:
-  metadata.gz: 4e1552ac001c4036bf30b849a41eb0f64cb75c5de1202518cffaab3d6ce87e145ec90929047cbded341008572823128365e35c44d8a7c61a53650e30486f9f0a
-  data.tar.gz: ba0c7b2eb8ba036284909822ad1dada88227c0adc4c318d5ec8b782ed12bd5359759d03ea4b2be8bf16fa2aa502e1c4904b031993783ac5b263bbae7d54e92e6
+  metadata.gz: 506c7cd216eeb6af1aec9b17193dbb5d300853f64ce539e816e84fc81e4b97423807a8a231ff154d94f08f8b6025d8b23f2df73684dd7ccbeebc252604c8da93
+  data.tar.gz: 398a1dbdd54565f0b5f8152cbaaa4247bee486404ee1cb85606a222c36fb01ff1375dd81aa45c61b59889ac033cfd3a9e0744b1f5d73c1bcca77e4f65e57107b

data/.rubocop.yml

@@ -1,13 +1,12 @@
 AllCops:
-  TargetRubyVersion: 2.7
+  TargetRubyVersion: 3.2
   NewCops: enable
   Exclude:
     - "*.gemspec"
-    - "gemfiles/*"
     - "vendor/**/*"
     - Rakefile
     - Gemfile
-require:
+plugins:
   - rubocop-minitest
   - rubocop-rake
   - rubocop-performance
@@ -24,21 +23,6 @@ Naming/FileName:
 
 Layout/LineLength:
   Enabled: false
-Layout/SpaceAroundMethodCallOperator:
-  Enabled: true
-
-Lint/RaiseException:
-  Enabled: true
-Lint/StructNewOverride:
-  Enabled: true
 
 Style/WordArray:
   Enabled: false
-Style/HashEachMethods:
-  Enabled: true
-Style/HashTransformKeys:
-  Enabled: true
-Style/HashTransformValues:
-  Enabled: true
-Style/ExponentialNotation:
-  Enabled: true

data/CHANGELOG.md

@@ -1 +1,29 @@
-Changelog is maintained under [Github Releases](https://github.com/jannewaren/jekyll-toc-plus/releases).
+# Changelog
+
+Versions through 0.20.0 are documented under
+[GitHub Releases](https://github.com/jannewaren/jekyll-toc-plus/releases).
+
+## [Unreleased]
+
+## [0.21.0] - 2026-06-20
+
+### Added
+
+- `no_toc_class` config option to customize the class that excludes a heading
+  from the TOC (default: `no_toc`), mirroring the configurable `no_toc_section_class`.
+
+### Changed
+
+- The `{% toc %}` tag now requires `toc: true` strictly, matching the `toc` /
+  `toc_only` / `inject_anchors` filters. Previously the tag accepted any truthy
+  front-matter value. If you relied on a non-`true` truthy value (e.g. `toc: "yes"`)
+  to render the tag, set it to `toc: true`.
+
+### Fixed
+
+- Escape heading ids when interpolating them into `href` attributes, preventing
+  HTML/attribute injection from an author-supplied `id` containing characters
+  such as `"`.
+- De-duplicate headings that share an explicit `id`: a second `id="foo"` now
+  links to `#foo-1` instead of emitting a duplicate `#foo` fragment. Previously
+  only generated ids were de-duplicated.

data/CLAUDE.md

@@ -0,0 +1,51 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`jekyll-toc-plus` is a Ruby gem / Jekyll plugin that generates a Table of Contents from rendered HTML content. It is a fork of [`toshimaru/jekyll-toc`](https://github.com/toshimaru/jekyll-toc), adding the options `div_list`, `flat_list`, `toc_only_direct_text`, and per-page `toc_config` front-matter overrides. It aims to stay a drop-in replacement for upstream.
+
+## Commands
+
+```sh
+bundle install                 # install dev dependencies
+bundle exec rake               # run the full test suite (default task)
+bundle exec rake test          # same, explicit
+bundle exec rubocop            # lint
+bundle exec rubocop -A         # lint with autocorrect
+
+# Run a single test file (note: tests `require 'test_helper'`, so -Itest is required)
+bundle exec ruby -Ilib -Itest test/parser/test_toc_filter.rb
+
+# Run a single test by name
+bundle exec ruby -Ilib -Itest test/parser/test_toc_filter.rb -n test_nested_toc
+
+bundle exec rake build         # build the .gem
+```
+
+CI (`.github/workflows`) runs the test suite across Ruby `3.2`, `3.3`, `3.4`, and `4.0` (on Jekyll 4.4), plus a separate RuboCop job. RuboCop targets Ruby 3.2 syntax; keep new code compatible.
+
+## Architecture
+
+The plugin is two thin Liquid integrations over one parser.
+
+**Entry point — `lib/jekyll-toc-plus.rb`** (the file `require`d by Jekyll). Registers:
+- `Jekyll::TableOfContentsFilter`, a Liquid filter module exposing three filters: `toc` (TOC + anchored content), `toc_only` (just the TOC list; a supported filter, kept because — unlike the `{% toc %}` tag — it works on any page), and `inject_anchors` (just the anchored content). Each is gated by `toc_enabled?`, which requires the page's front matter to have `toc: true`.
+- `Jekyll::TocTag`, the `{% toc %}` Liquid tag. Equivalent to `toc_only` but reads `content` directly from the page register, so it only works for Posts/Collections (documented limitation).
+
+**Config resolution** is shared via `TableOfContents::ConfigResolver#merge_toc_config`, mixed into both the filter (called through `toc_config`) and the tag: site-wide `_config.yml` `toc:` settings are merged with per-page `toc_config:` front matter, where **page values override site values**. This is the mechanism behind per-page `min_level`/`max_level`/`toc_only_direct_text` overrides.
+
+**`TableOfContents::Parser`** (`lib/table_of_contents/parser.rb`) does all real work:
+- Parses the HTML once with Nokogiri (`DocumentFragment`) in `initialize`, then `parse_content` walks the configured heading levels, skipping headings with the `no_toc` class or inside any `no_toc_section_class` container. Each entry records its id (existing `id` attribute, else a slug from the heading text), escaped text, node name, and heading number.
+- `build_toc` emits the list; it dispatches to `build_flat_toc_list` (when `flat_list`) or the recursive `build_nested_toc_list`, which builds nested sublists by comparing each entry's heading number to the minimum level in the slice.
+- `inject_anchors_into_html` mutates the parsed doc, inserting `<a class="anchor">` before each heading, and returns the modified HTML.
+- `list_tag` / `list_parent_tag` select the output element: `div` when `div_list`, otherwise `ul`/`ol` (per `ordered_list`) + `li`.
+
+**`Configuration`** (`configuration.rb`) merges user options over the single source of truth `DEFAULT_CONFIG` and exposes them as readers. When adding a new option, add it to `DEFAULT_CONFIG`, expose an `attr_reader`, assign it in `initialize`, and document it in `README.md`'s Default Configuration block.
+
+**`Helper`** (`helper.rb`) is mixed into `Parser`: `generate_toc_id` slugifies heading text (downcase, strip punctuation via a Unicode-aware regexp, dasherize, URL-encode) and `extract_text` implements `toc_only_direct_text` by pulling only direct text-node children of a heading.
+
+## Tests
+
+Minitest, run via Rake. `test/test_helper.rb` boots SimpleCov + Minitest reporters and defines `SIMPLE_HTML` (h1–h6) plus the `TestHelpers#read_html_and_create_parser` helper. Parser-level behavior lives in `test/parser/`; the Liquid tag/front-matter override behavior is in `test/test_page_config_override.rb` and `test/test_toc_tag.rb` (which stub the Liquid context with `Struct`). New options should get a focused file under `test/parser/`.

data/Gemfile

@@ -2,10 +2,8 @@ source 'https://rubygems.org'
 
 gemspec
 
-gem 'appraisal'
 gem 'minitest-reporters'
 gem 'minitest'
-gem 'pry'
 gem 'rake'
 gem 'rubocop-minitest'
 gem 'rubocop-performance'

data/README.md

@@ -130,7 +130,7 @@ location with the `toc_only` filter.
 
 ## Generated HTML
 
-jekyll-toc generates an unordered list by default. The HTML output is as follows.
+jekyll-toc-plus generates an unordered list by default. The HTML output is as follows.
 
 ```html
 <ul id="toc" class="section-nav">
@@ -158,7 +158,7 @@ jekyll-toc generates an unordered list by default. The HTML output is as follows
 
 ## Customization
 
-jekyll-toc is customizable on `_config.yml`.
+jekyll-toc-plus is customizable on `_config.yml`.
 
 ### Default Configuration
 
@@ -168,6 +168,7 @@ toc:
   min_level: 1
   max_level: 6
   ordered_list: false
+  no_toc_class: no_toc
   no_toc_section_class: no_toc_section
   list_id: toc
   list_class: section-nav
@@ -230,6 +231,14 @@ The heading is ignored in the toc by adding `no_toc` class.
 <h2>h2</h2>
 ```
 
+The class can be configured on `_config.yml`:
+
+```yml
+# _config.yml
+toc:
+  no_toc_class: skip-toc # default: no_toc
+```
+
 ### Skip TOC Sectionally
 
 The headings are ignored inside the element which has `no_toc_section` class.

data/jekyll-toc-plus.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative 'lib/table_of_contents/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'jekyll-toc-plus'
+  spec.version       = Jekyll::TableOfContents::VERSION
+  spec.summary       = 'Jekyll Table of Contents plugin'
+  spec.description   = 'Jekyll (Ruby static website generator) plugin which generates a Table of Contents for the page.'
+  spec.authors       = ['toshimaru', 'torbjoernk', 'Janne Warén']
+  spec.email         = 'janne.waren@gmail.com'
+  spec.homepage      = 'https://github.com/jannewaren/jekyll-toc-plus'
+  spec.license       = 'MIT'
+  spec.require_paths = ['lib']
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/jannewaren/jekyll-toc-plus'
+  spec.metadata['changelog_uri'] = 'https://github.com/jannewaren/jekyll-toc-plus/releases'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|circleci)|appveyor)})
+    end
+  end
+
+  spec.required_ruby_version = '>= 3.2'
+
+  spec.add_dependency 'jekyll', '>= 4.4'
+  spec.add_dependency 'nokogiri', '~> 1.12'
+end

data/lib/jekyll-toc-plus.rb

@@ -5,28 +5,42 @@ require 'table_of_contents/configuration'
 require 'table_of_contents/parser'
 
 module Jekyll
+  module TableOfContents
+    # Resolves the effective TOC config by merging site-wide `_config.yml`
+    # `toc:` settings with per-page `toc_config:` front matter, where page
+    # values override site values. Shared by the filter and the tag.
+    module ConfigResolver
+      private
+
+      def merge_toc_config(registers)
+        site_config = registers[:site].config['toc'] || {}
+        page_config = registers[:page]['toc_config'] || {}
+        site_config.merge(page_config)
+      end
+    end
+  end
+
   # toc tag for Jekyll
   class TocTag < Liquid::Tag
+    include TableOfContents::ConfigResolver
+
     def render(context)
-      return '' unless context.registers[:page]['toc']
+      return '' unless context.registers[:page]['toc'] == true
 
       content_html = context.registers[:page]['content']
-      toc_config = merge_toc_config(context)
+      toc_config = merge_toc_config(context.registers)
       TableOfContents::Parser.new(content_html, toc_config).build_toc
     end
-
-    private
-
-    def merge_toc_config(context)
-      site_config = context.registers[:site].config['toc'] || {}
-      page_config = context.registers[:page]['toc_config'] || {}
-      site_config.merge(page_config)
-    end
   end
 
   # Jekyll Table of Contents filter plugin
   module TableOfContentsFilter
-    # Deprecated method. Removed in v1.0.
+    include TableOfContents::ConfigResolver
+
+    # Renders the TOC only (no anchors injected into the content).
+    # Kept as a supported filter: unlike the {% toc %} tag, it works on any
+    # page because it receives the content as input, whereas the tag reads
+    # page['content'] and therefore only works for Posts and Collections.
     def toc_only(html)
       return '' unless toc_enabled?
 
@@ -52,12 +66,10 @@ module Jekyll
     end
 
     def toc_config
-      site_config = @context.registers[:site].config['toc'] || {}
-      page_config = @context.registers[:page]['toc_config'] || {}
-      site_config.merge(page_config)
+      merge_toc_config(@context.registers)
     end
   end
 end
 
 Liquid::Template.register_filter(Jekyll::TableOfContentsFilter)
-Liquid::Template.register_tag('toc', Jekyll::TocTag) # will be enabled at v1.0
+Liquid::Template.register_tag('toc', Jekyll::TocTag)

data/lib/table_of_contents/configuration.rb

@@ -12,6 +12,7 @@ module Jekyll
         'min_level' => 1,
         'max_level' => 6,
         'ordered_list' => false,
+        'no_toc_class' => 'no_toc',
         'no_toc_section_class' => 'no_toc_section',
         'list_id' => 'toc',
         'list_class' => 'section-nav',
@@ -28,7 +29,7 @@ module Jekyll
 
         @toc_levels = options['min_level']..options['max_level']
         @ordered_list = options['ordered_list']
-        @no_toc_class = 'no_toc'
+        @no_toc_class = options['no_toc_class']
         @no_toc_section_class = options['no_toc_section_class']
         @list_id = options['list_id']
         @list_class = options['list_class']
@@ -43,9 +44,9 @@ module Jekyll
       private
 
       def generate_option_hash(options)
+        return DEFAULT_CONFIG.dup unless options.is_a?(Hash)
+
         DEFAULT_CONFIG.merge(options)
-      rescue TypeError
-        DEFAULT_CONFIG
       end
     end
   end

data/lib/table_of_contents/helper.rb

@@ -4,7 +4,7 @@ module Jekyll
   module TableOfContents
     # helper methods for Parser
     module Helper
-      PUNCTUATION_REGEXP = /[^\p{Word}\- ]/u.freeze
+      PUNCTUATION_REGEXP = /[^\p{Word}\- ]/u
 
       def generate_toc_id(text)
         text = text.downcase

data/lib/table_of_contents/parser.rb

@@ -24,9 +24,8 @@ module Jekyll
 
       def inject_anchors_into_html
         @entries.each do |entry|
-          # NOTE: `entry[:id]` is automatically URL encoded by Nokogiri
           entry[:header_content].add_previous_sibling(
-            %(<a class="anchor" href="##{entry[:id]}" aria-hidden="true"><span class="octicon octicon-link"></span></a>)
+            %(<a class="anchor" href="##{escaped_id(entry)}" aria-hidden="true"><span class="octicon octicon-link"></span></a>)
           )
         end
 
@@ -44,7 +43,9 @@ module Jekyll
           .reject { |n| n.classes.include?(@configuration.no_toc_class) }
           .inject([]) do |entries, node|
           text = extract_text(node, only_direct_text: @configuration.toc_only_direct_text)
-          id = node.attribute('id') || generate_toc_id(text)
+          # Use the attribute's string value (not the Nokogiri::XML::Attr object)
+          # so duplicate explicit ids dedupe correctly via the `headers` hash.
+          id = node.attribute('id')&.value || generate_toc_id(text)
 
           suffix_num = headers[id]
           headers[id] += 1
@@ -73,7 +74,7 @@ module Jekyll
         toc_list = +''
 
         entries.each do |entry|
-          toc_list << %(<#{list_parent_tag} class="#{@configuration.item_class} #{@configuration.item_prefix}#{entry[:node_name]}"><a href="##{entry[:id]}">#{entry[:text]}</a></#{list_parent_tag}>\n)
+          toc_list << %(<#{list_parent_tag} class="#{@configuration.item_class} #{@configuration.item_prefix}#{entry[:node_name]}"><a href="##{escaped_id(entry)}">#{entry[:text]}</a></#{list_parent_tag}>\n)
         end
 
         toc_list
@@ -90,7 +91,7 @@ module Jekyll
           if entry[:h_num] == min_h_num
             # If the current entry should not be indented in the list, add the entry to the list
             # If the next entry should be indented in the list, generate a sublist
-            toc_list << %(<#{list_parent_tag} class="#{@configuration.item_class} #{@configuration.item_prefix}#{entry[:node_name]}"><a href="##{entry[:id]}">#{entry[:text]}</a>)
+            toc_list << %(<#{list_parent_tag} class="#{@configuration.item_class} #{@configuration.item_prefix}#{entry[:node_name]}"><a href="##{escaped_id(entry)}">#{entry[:text]}</a>)
             next_i = i + 1
             if next_i < entries.count && entries[next_i][:h_num] > min_h_num
               nest_entries = get_nest_entries(entries[next_i, entries.count], min_h_num)
@@ -109,6 +110,13 @@ module Jekyll
         toc_list
       end
 
+      # Escapes an entry's id for safe interpolation into an HTML attribute
+      # value (the `href="#..."` fragment). Author-supplied ids may contain
+      # characters such as `"` that would otherwise break out of the attribute.
+      def escaped_id(entry)
+        CGI.escapeHTML(entry[:id])
+      end
+
       # Returns the entries in a nested list
       # The nested list starts at the first entry in entries (inclusive)
       # The nested list ends at the first entry in entries with depth min_h_num or greater (exclusive)

data/lib/table_of_contents/version.rb

@@ -2,6 +2,6 @@
 
 module Jekyll
   module TableOfContents
-    VERSION = '0.20.0'
+    VERSION = '0.21.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-toc-plus
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.21.0
 platform: ruby
 authors:
 - toshimaru
@@ -17,14 +17,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.9'
+        version: '4.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.9'
+        version: '4.4'
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
@@ -47,17 +47,13 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rubocop.yml"
-- Appraisals
 - CHANGELOG.md
+- CLAUDE.md
 - Gemfile
 - LICENSE.md
 - README.md
 - Rakefile
-- gemfiles/jekyll_3.9.gemfile
-- gemfiles/jekyll_4.0.gemfile
-- gemfiles/jekyll_4.1.gemfile
-- gemfiles/jekyll_4.2.gemfile
-- gemfiles/jekyll_4.3.gemfile
+- jekyll-toc-plus.gemspec
 - lib/jekyll-toc-plus.rb
 - lib/table_of_contents/configuration.rb
 - lib/table_of_contents/helper.rb
@@ -78,7 +74,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/Appraisals

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-SUPPORTED_VERSIONS = %w[3.9 4.0 4.1 4.2 4.3].freeze
-
-SUPPORTED_VERSIONS.each do |version|
-  appraise "jekyll-#{version}" do
-    gem 'jekyll', version
-  end
-end

data/gemfiles/jekyll_3.9.gemfile

@@ -1,17 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "appraisal"
-gem "minitest-reporters"
-gem "minitest"
-gem "pry"
-gem "rake"
-gem "rubocop-minitest"
-gem "rubocop-performance"
-gem "rubocop-rake"
-gem "rubocop"
-gem "simplecov", "~> 0.22.0"
-gem "jekyll", "3.9"
-
-gemspec path: "../"

data/gemfiles/jekyll_4.0.gemfile

@@ -1,17 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "appraisal"
-gem "minitest-reporters"
-gem "minitest"
-gem "pry"
-gem "rake"
-gem "rubocop-minitest"
-gem "rubocop-performance"
-gem "rubocop-rake"
-gem "rubocop"
-gem "simplecov", "~> 0.22.0"
-gem "jekyll", "4.0"
-
-gemspec path: "../"

data/gemfiles/jekyll_4.1.gemfile

@@ -1,17 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "appraisal"
-gem "minitest-reporters"
-gem "minitest"
-gem "pry"
-gem "rake"
-gem "rubocop-minitest"
-gem "rubocop-performance"
-gem "rubocop-rake"
-gem "rubocop"
-gem "simplecov", "~> 0.22.0"
-gem "jekyll", "4.1"
-
-gemspec path: "../"

data/gemfiles/jekyll_4.2.gemfile

@@ -1,17 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "appraisal"
-gem "minitest-reporters"
-gem "minitest"
-gem "pry"
-gem "rake"
-gem "rubocop-minitest"
-gem "rubocop-performance"
-gem "rubocop-rake"
-gem "rubocop"
-gem "simplecov", "~> 0.22.0"
-gem "jekyll", "4.2"
-
-gemspec path: "../"

data/gemfiles/jekyll_4.3.gemfile

@@ -1,17 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "appraisal"
-gem "minitest-reporters"
-gem "minitest"
-gem "pry"
-gem "rake"
-gem "rubocop-minitest"
-gem "rubocop-performance"
-gem "rubocop-rake"
-gem "rubocop"
-gem "simplecov", "~> 0.22.0"
-gem "jekyll", "4.3"
-
-gemspec path: "../"