jekyll-toc-plus 0.20.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7673dcb756b228f2940af9eb43c7e2e18bb42afd1aae9a508da44991d67c3428
+  data.tar.gz: f44af3e46bad9e0339246603ae38409ce2ef7301c1d5003bf5f86a5267fa2d0c
+SHA512:
+  metadata.gz: 4e1552ac001c4036bf30b849a41eb0f64cb75c5de1202518cffaab3d6ce87e145ec90929047cbded341008572823128365e35c44d8a7c61a53650e30486f9f0a
+  data.tar.gz: ba0c7b2eb8ba036284909822ad1dada88227c0adc4c318d5ec8b782ed12bd5359759d03ea4b2be8bf16fa2aa502e1c4904b031993783ac5b263bbae7d54e92e6

data/.rubocop.yml

@@ -0,0 +1,44 @@
+AllCops:
+  TargetRubyVersion: 2.7
+  NewCops: enable
+  Exclude:
+    - "*.gemspec"
+    - "gemfiles/*"
+    - "vendor/**/*"
+    - Rakefile
+    - Gemfile
+require:
+  - rubocop-minitest
+  - rubocop-rake
+  - rubocop-performance
+
+Metrics/MethodLength:
+  Enabled: false
+Metrics/AbcSize:
+  Enabled: false
+Metrics/ClassLength:
+  Enabled: false
+
+Naming/FileName:
+  Enabled: false
+
+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/Appraisals

@@ -0,0 +1,9 @@
+# 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/CHANGELOG.md

@@ -0,0 +1 @@
+Changelog is maintained under [Github Releases](https://github.com/jannewaren/jekyll-toc-plus/releases).

data/Gemfile

@@ -0,0 +1,14 @@
+source 'https://rubygems.org'
+
+gemspec
+
+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'

data/LICENSE.md

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2020-2021 Toshimaru
+Copyright (c) 2025 Janne Warén
+
+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,486 @@
+# jekyll-toc-plus
+
+![CI](https://github.com/jannewaren/jekyll-toc-plus/workflows/CI/badge.svg)
+[![Gem Version](https://badge.fury.io/rb/jekyll-toc-plus.svg)](https://badge.fury.io/rb/jekyll-toc-plus)
+
+## About this fork
+
+`jekyll-toc-plus` is a fork of [`toshimaru/jekyll-toc`](https://github.com/toshimaru/jekyll-toc).
+All credit for the original plugin goes to its upstream authors — this fork simply adds a
+few extra options (`div_list`, `flat_list`, `toc_only_direct_text`, and per-page
+`toc_config` overrides) on top of their work, and is published to RubyGems so others can
+`gem install` it directly.
+
+It is otherwise a drop-in replacement. The maintainer makes **no promise to maintain this
+as a full author**, but contributions and pull requests are welcome.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basic Usage](#basic-usage)
+  - [Advanced Usage](#advanced-usage)
+- [Generated HTML](#generated-html)
+- [Customization](#customization)
+  - [Default Configuration](#default-configuration)
+  - [TOC levels](#toc-levels)
+  - [Enable TOC by default](#enable-toc-by-default)
+  - [Skip TOC](#skip-toc)
+  - [Skip TOC Sectionally](#skip-toc-sectionally)
+  - [TOC Only Direct Text](#toc-only-direct-text)
+  - [CSS Styling](#css-styling)
+  - [Custom CSS Class and ID](#custom-css-class-and-id)
+  - [Using Unordered/Ordered lists](#using-unorderedordered-lists)
+  - [Using divs as list elements](#using-divs-as-list-elements)
+  - [Using a flat list](#using-a-flat-list)
+- [Alternative Tools](#alternative-tools)
+
+## Installation
+
+Add jekyll-toc-plus plugin in your site's `Gemfile`, and run `bundle install`.
+
+```ruby
+gem 'jekyll-toc-plus'
+```
+
+Add jekyll-toc-plus to the `plugins:` section in your site's `_config.yml`.
+
+```yml
+plugins:
+  - jekyll-toc-plus
+```
+
+Set `toc: true` in posts for which you want the TOC to appear.
+
+```yml
+---
+layout: post
+title: "Welcome to Jekyll!"
+toc: true
+---
+```
+
+## Usage
+
+There are three Liquid filters, which can be applied to HTML content,
+e.g. the Liquid variable `content` available in Jekyll's templates.
+
+### Basic Usage
+
+#### `toc` filter
+
+Add the `toc` filter to your site's `{{ content }}` (e.g. `_layouts/post.html`).
+
+```liquid
+{{ content | toc }}
+```
+
+This filter places the TOC directly above the content.
+
+### Advanced Usage
+
+If you'd like separated TOC and content, you can use `{% toc %}` tag (or `toc_only` filter) and `inject_anchors` filter.
+
+#### `{% toc %}` tag / `toc_only` filter
+
+Generates the TOC itself as described [below](#generated-html).
+Mostly useful in cases where the TOC should _not_ be placed immediately
+above the content but at some other place of the page, i.e. an aside.
+
+```html
+<div>
+  <div id="table-of-contents">
+    {% toc %}
+  </div>
+  <div id="markdown-content">
+    {{ content }}
+  </div>
+</div>
+```
+
+:warning: **`{% toc %}` Tag Limitation**
+
+`{% toc %}` works only for [Jekyll Posts](https://jekyllrb.com/docs/step-by-step/08-blogging/) and [Jekyll Collections](https://jekyllrb.com/docs/collections/).
+If you'd like to use `{% toc %}` except posts or collections, please use `toc_only` filter as described below.
+
+```html
+<div>
+  <div id="table-of-contents">
+    {{ content | toc_only }}
+  </div>
+  <div id="markdown-content">
+    {{ content | inject_anchors }}
+  </div>
+</div>
+```
+
+#### `inject_anchors` filter
+
+Injects HTML anchors into the content without actually outputting the TOC itself.
+They are of the form:
+
+```html
+<a class="anchor" href="#heading1-1" aria-hidden="true">
+  <span class="octicon octicon-link"></span>
+</a>
+```
+
+This is only useful when the TOC itself should be placed at some other
+location with the `toc_only` filter.
+
+## Generated HTML
+
+jekyll-toc generates an unordered list by default. The HTML output is as follows.
+
+```html
+<ul id="toc" class="section-nav">
+  <li class="toc-entry toc-h1"><a href="#heading1">Heading.1</a>
+    <ul>
+      <li class="toc-entry toc-h2"><a href="#heading1-1">Heading.1-1</a></li>
+      <li class="toc-entry toc-h2"><a href="#heading1-2">Heading.1-2</a></li>
+    </ul>
+  </li>
+  <li class="toc-entry toc-h1"><a href="#heading2">Heading.2</a>
+    <ul>
+      <li class="toc-entry toc-h2"><a href="#heading2-1">Heading.2-1</a>
+        <ul>
+          <li class="toc-entry toc-h3"><a href="#heading2-1-1">Heading.2-1-1</a></li>
+          <li class="toc-entry toc-h3"><a href="#heading2-1-2">Heading.2-1-2</a></li>
+        </ul>
+      </li>
+      <li class="toc-entry toc-h2"><a href="#heading2-2">Heading.2-2</a></li>
+    </ul>
+  </li>
+</ul>
+```
+
+![screenshot](https://user-images.githubusercontent.com/803398/28401295-0dcfb7ca-6d54-11e7-892b-2f2e6ca755a7.png)
+
+## Customization
+
+jekyll-toc is customizable on `_config.yml`.
+
+### Default Configuration
+
+```yml
+# _config.yml
+toc:
+  min_level: 1
+  max_level: 6
+  ordered_list: false
+  no_toc_section_class: no_toc_section
+  list_id: toc
+  list_class: section-nav
+  sublist_class: ''
+  item_class: toc-entry
+  item_prefix: toc-
+  div_list: false
+  flat_list: false
+  toc_only_direct_text: false
+```
+
+### TOC levels
+
+```yml
+# _config.yml
+toc:
+  min_level: 2 # default: 1
+  max_level: 5 # default: 6
+```
+
+The default heading range is from `<h1>` to `<h6>`.
+
+#### Per-Page TOC Level Override
+
+You can override the `min_level` and `max_level` settings for individual pages or posts by adding a `toc_config` key to the YAML front matter:
+
+```yml
+---
+layout: post
+title: "My Post"
+toc: true
+toc_config:
+  min_level: 2  # Override: Start from H2 for this page only
+  max_level: 4  # Override: Stop at H4 for this page only
+---
+```
+
+This is useful when you want different TOC depths for different types of content.
+
+### Enable TOC by default
+
+You can enable TOC by default with [Front Matter Defaults](https://jekyllrb.com/docs/configuration/front-matter-defaults/):
+
+```yml
+# _config.yml
+defaults:
+  - scope:
+      path: ""
+    values:
+      toc: true
+```
+
+### Skip TOC
+
+The heading is ignored in the toc by adding `no_toc` class.
+
+```html
+<h1>h1</h1>
+<h1 class="no_toc">This heading is ignored in the TOC</h1>
+<h2>h2</h2>
+```
+
+### Skip TOC Sectionally
+
+The headings are ignored inside the element which has `no_toc_section` class.
+
+```html
+<h1>h1</h1>
+<div class="no_toc_section">
+  <h2>This heading is ignored in the TOC</h2>
+  <h3>This heading is ignored in the TOC</h3>
+</div>
+<h4>h4</h4>
+```
+
+Which would result in only the `<h1>` & `<h4>` within the example being included in the TOC.
+
+The class can be configured on `_config.yml`:
+
+```yml
+# _config.yml
+toc:
+  no_toc_section_class: exclude # default: no_toc_section
+```
+
+Configuring multiple classes are allowed:
+
+```yml
+# _config.yml
+toc:
+  no_toc_section_class:
+    - no_toc_section
+    - exclude
+    - your_custom_skip_class_name
+```
+
+### toc_only_direct_text
+
+By default, the TOC includes all text content from headings, including text within nested HTML elements. The `toc_only_direct_text` option allows you to extract only the direct text nodes from headings, excluding all child elements.
+
+This is particularly useful when using custom HTML components or tags within headings (like badges, icons, or status indicators) that you don't want to appear in the table of contents.
+
+```yml
+# _config.yml
+toc:
+  toc_only_direct_text: true # default: false
+```
+
+**Example:**
+
+Given this heading:
+
+```html
+<h2>formatName <tag>Required</tag></h2>
+```
+
+- With `toc_only_direct_text: false` (default): TOC shows "formatName Required"
+- With `toc_only_direct_text: true`: TOC shows "formatName"
+
+**Per-page override:**
+
+You can override this setting for specific pages using front matter:
+
+```yml
+---
+layout: post
+title: "My Post"
+toc: true
+toc_config:
+  toc_only_direct_text: true
+---
+```
+
+### CSS Styling
+
+The toc can be modified with CSS. The sample CSS is the following.
+
+```css
+.section-nav {
+  background-color: #fff;
+  margin: 5px 0;
+  padding: 10px 30px;
+  border: 1px solid #e8e8e8;
+  border-radius: 3px;
+}
+```
+
+![screenshot](https://user-images.githubusercontent.com/803398/28401455-0ba60868-6d55-11e7-8159-0ae7591aee66.png)
+
+Each TOC `li` entry has two CSS classes for further styling. The general `toc-entry` is applied to all `li` elements in the `ul.section-nav`.
+
+Depending on the heading level each specific entry refers to, it has a second CSS class `toc-XX`, where `XX` is the HTML heading tag name.
+For example, the TOC entry linking to a heading `<h1>...</h1>` (a single `#` in Markdown) will get the CSS class `toc-h1`.
+
+### Custom CSS Class and ID
+
+You can apply custom CSS classes to the generated `<ul>` and `<li>` tags.
+
+```yml
+# _config.yml
+toc:
+  list_id: my-toc-id # Default: "toc"
+  list_class: my-list-class # Default: "section-nav"
+  sublist_class: my-sublist-class # Default: no class for sublists
+  item_class: my-item-class # Default: "toc-entry"
+  item_prefix: item- # Default: "toc-":
+```
+
+### Using Unordered/Ordered lists
+
+By default the table of contents will be generated as an unordered list via `<ul></ul>` tags. This can be configured to use ordered lists instead `<ol></ol>`.
+This can be configured in `_config.yml`:
+
+```yml
+# _config.yml
+toc:
+  ordered_list: true # default is false
+```
+
+In order to change the list type, use the [list-style-type](https://developer.mozilla.org/en-US/docs/Web/CSS/list-style-type) css property.
+Add a class to the `sublist_class` configuration to append it to the `ol` tags so that you can add the `list-style-type` property.
+
+Example
+
+```yml
+# _config.yml
+toc:
+  ordered_list: true
+  list_class: my-list-class
+  sublist_class: my-sublist-class
+```
+
+```css
+.my-list-class {
+  list-style-type: upper-alpha;
+}
+
+.my-sublist-class {
+  list-style-type: lower-alpha;
+}
+```
+
+This will produce:
+
+![screenshot](https://user-images.githubusercontent.com/7675276/85813980-a0ea5a80-b719-11ea-9458-ccf9b86a778b.png)
+
+### Using divs as list elements
+
+By default, the table of contents is generated using `<ul>`, `<ol>`, and `<li>` tags. If you prefer to use `<div>` elements instead (for custom styling or accessibility reasons), you can enable this by setting the `div_list` option in your `_config.yml`:
+
+```yml
+# _config.yml
+toc:
+  div_list: true # default is false
+```
+
+When `div_list` is set to `true`, the TOC will be rendered using `<div>` elements for both the list container and each entry, instead of `<ul>`, `<ol>`, and `<li>`. You can still use the `list_class`, `sublist_class`, and `item_class` options to add custom CSS classes for styling:
+
+```yml
+# _config.yml
+toc:
+  div_list: true
+  list_class: my-list-class
+  sublist_class: my-sublist-class
+  item_class: my-item-class
+```
+
+Example CSS for styling the TOC with `<div>` elements:
+
+```css
+.my-list-class {
+  /* Styles for the TOC container */
+  margin: 10px 0;
+}
+
+.my-item-class {
+  /* Styles for each TOC entry */
+  padding: 4px 0;
+}
+
+.my-sublist-class {
+  /* Styles for nested TOC containers */
+  margin-left: 20px;
+}
+```
+
+This will produce a TOC structure like:
+
+```html
+<div id="toc" class="my-list-class">
+  <div class="my-item-class toc-h1"><a href="#heading1">Heading.1</a>
+    <div class="my-sublist-class">
+      <div class="my-item-class toc-h2"><a href="#heading1-1">Heading.1-1</a></div>
+      <div class="my-item-class toc-h2"><a href="#heading1-2">Heading.1-2</a></div>
+    </div>
+  </div>
+  <div class="my-item-class toc-h1"><a href="#heading2">Heading.2</a></div>
+</div>
+```
+
+Use this option if you want more flexibility in styling or need to avoid list semantics for accessibility or design reasons.
+
+### Using a flat list
+
+By default, the table of contents is generated as a nested structure that reflects the hierarchy of headings in your content. If you prefer a flat list with no nesting (where all TOC entries appear at the same level regardless of their heading level), you can enable this by setting the `flat_list` option in your `_config.yml`:
+
+```yml
+# _config.yml
+toc:
+  flat_list: true # default is false
+```
+
+When `flat_list` is set to `true`, all TOC entries will be rendered at the same level without any nesting, while still retaining the CSS classes that indicate their heading level. This is useful when you want to style headings differently based on their level but prefer a simplified, non-nested list structure.
+
+The flat list option works with both standard lists (`<ul>`, `<ol>`) and div-based lists (when `div_list` is set to `true`).
+
+Example with standard lists:
+
+```html
+<ul id="toc" class="section-nav">
+  <li class="toc-entry toc-h1"><a href="#heading1">Heading.1</a></li>
+  <li class="toc-entry toc-h2"><a href="#heading1-1">Heading.1-1</a></li>
+  <li class="toc-entry toc-h2"><a href="#heading1-2">Heading.1-2</a></li>
+  <li class="toc-entry toc-h1"><a href="#heading2">Heading.2</a></li>
+  <li class="toc-entry toc-h2"><a href="#heading2-1">Heading.2-1</a></li>
+  <li class="toc-entry toc-h3"><a href="#heading2-1-1">Heading.2-1-1</a></li>
+</ul>
+```
+
+Example with div-based lists:
+
+```html
+<div id="toc" class="section-nav">
+  <div class="toc-entry toc-h1"><a href="#heading1">Heading.1</a></div>
+  <div class="toc-entry toc-h2"><a href="#heading1-1">Heading.1-1</a></div>
+  <div class="toc-entry toc-h2"><a href="#heading1-2">Heading.1-2</a></div>
+  <div class="toc-entry toc-h1"><a href="#heading2">Heading.2</a></div>
+  <div class="toc-entry toc-h2"><a href="#heading2-1">Heading.2-1</a></div>
+  <div class="toc-entry toc-h3"><a href="#heading2-1-1">Heading.2-1-1</a></div>
+</div>
+```
+
+Use this option when you want a simplified TOC structure but still want to style entries differently based on their heading level using CSS. For example:
+
+```css
+.toc-h1 { font-weight: bold; font-size: 1.2em; }
+.toc-h2 { font-weight: normal; font-size: 1.1em; }
+.toc-h3 { font-style: italic; font-size: 1em; }
+```
+
+## Alternative Tools
+
+- Adding anchor to headings
+  - [AnchorJS](https://www.bryanbraun.com/anchorjs/)
+- Generating TOC for kramdown content
+  - [Automatic “Table of Contents” Generation](https://kramdown.gettalong.org/converter/html.html#toc) (See also. [Create Table of Contents in kramdown](https://blog.toshima.ru/2020/05/22/kramdown-toc))

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+
+task default: :test
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end

data/gemfiles/jekyll_3.9.gemfile

@@ -0,0 +1,17 @@
+# 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

@@ -0,0 +1,17 @@
+# 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

@@ -0,0 +1,17 @@
+# 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

@@ -0,0 +1,17 @@
+# 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

@@ -0,0 +1,17 @@
+# 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: "../"

data/lib/jekyll-toc-plus.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require 'nokogiri'
+require 'table_of_contents/configuration'
+require 'table_of_contents/parser'
+
+module Jekyll
+  # toc tag for Jekyll
+  class TocTag < Liquid::Tag
+    def render(context)
+      return '' unless context.registers[:page]['toc']
+
+      content_html = context.registers[:page]['content']
+      toc_config = merge_toc_config(context)
+      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.
+    def toc_only(html)
+      return '' unless toc_enabled?
+
+      TableOfContents::Parser.new(html, toc_config).build_toc
+    end
+
+    def inject_anchors(html)
+      return html unless toc_enabled?
+
+      TableOfContents::Parser.new(html, toc_config).inject_anchors_into_html
+    end
+
+    def toc(html)
+      return html unless toc_enabled?
+
+      TableOfContents::Parser.new(html, toc_config).toc
+    end
+
+    private
+
+    def toc_enabled?
+      @context.registers[:page]['toc'] == true
+    end
+
+    def toc_config
+      site_config = @context.registers[:site].config['toc'] || {}
+      page_config = @context.registers[:page]['toc_config'] || {}
+      site_config.merge(page_config)
+    end
+  end
+end
+
+Liquid::Template.register_filter(Jekyll::TableOfContentsFilter)
+Liquid::Template.register_tag('toc', Jekyll::TocTag) # will be enabled at v1.0

data/lib/table_of_contents/configuration.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module TableOfContents
+    # jekyll-toc configuration class
+    class Configuration
+      attr_reader :toc_levels, :no_toc_class, :ordered_list, :no_toc_section_class,
+                  :list_id, :list_class, :sublist_class, :item_class, :item_prefix, :div_list, :flat_list,
+                  :toc_only_direct_text
+
+      DEFAULT_CONFIG = {
+        'min_level' => 1,
+        'max_level' => 6,
+        'ordered_list' => false,
+        'no_toc_section_class' => 'no_toc_section',
+        'list_id' => 'toc',
+        'list_class' => 'section-nav',
+        'sublist_class' => '',
+        'item_class' => 'toc-entry',
+        'item_prefix' => 'toc-',
+        'div_list' => false,
+        'flat_list' => false,
+        'toc_only_direct_text' => false
+      }.freeze
+
+      def initialize(options)
+        options = generate_option_hash(options)
+
+        @toc_levels = options['min_level']..options['max_level']
+        @ordered_list = options['ordered_list']
+        @no_toc_class = 'no_toc'
+        @no_toc_section_class = options['no_toc_section_class']
+        @list_id = options['list_id']
+        @list_class = options['list_class']
+        @sublist_class = options['sublist_class']
+        @item_class = options['item_class']
+        @item_prefix = options['item_prefix']
+        @div_list = options['div_list']
+        @flat_list = options['flat_list']
+        @toc_only_direct_text = options['toc_only_direct_text']
+      end
+
+      private
+
+      def generate_option_hash(options)
+        DEFAULT_CONFIG.merge(options)
+      rescue TypeError
+        DEFAULT_CONFIG
+      end
+    end
+  end
+end

data/lib/table_of_contents/helper.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module TableOfContents
+    # helper methods for Parser
+    module Helper
+      PUNCTUATION_REGEXP = /[^\p{Word}\- ]/u.freeze
+
+      def generate_toc_id(text)
+        text = text.downcase
+                   .gsub(PUNCTUATION_REGEXP, '') # remove punctuation
+                   .tr(' ', '-') # replace spaces with dash
+        CGI.escape(text)
+      end
+
+      def extract_text(node, only_direct_text: false)
+        if only_direct_text
+          node.children.select(&:text?).map { |child| child.text.strip }.reject(&:empty?).join(' ')
+        else
+          node.text.strip
+        end
+      end
+    end
+  end
+end

data/lib/table_of_contents/parser.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require 'table_of_contents/helper'
+
+module Jekyll
+  module TableOfContents
+    # Parse html contents and generate table of contents
+    class Parser
+      include ::Jekyll::TableOfContents::Helper
+
+      def initialize(html, options = {})
+        @doc = Nokogiri::HTML::DocumentFragment.parse(html)
+        @configuration = Configuration.new(options)
+        @entries = parse_content
+      end
+
+      def toc
+        build_toc + inject_anchors_into_html
+      end
+
+      def build_toc
+        %(<#{list_tag} id="#{@configuration.list_id}" class="#{@configuration.list_class}">\n#{build_toc_list(@entries)}</#{list_tag}>)
+      end
+
+      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>)
+          )
+        end
+
+        @doc.inner_html
+      end
+
+      private
+
+      # parse logic is from html-pipeline toc_filter
+      # https://github.com/jch/html-pipeline/blob/v1.1.0/lib/html/pipeline/toc_filter.rb
+      def parse_content
+        headers = Hash.new(0)
+
+        (@doc.css(toc_headings) - @doc.css(toc_headings_in_no_toc_section))
+          .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)
+
+          suffix_num = headers[id]
+          headers[id] += 1
+
+          entries << {
+            id: suffix_num.zero? ? id : "#{id}-#{suffix_num}",
+            text: CGI.escapeHTML(text),
+            node_name: node.name,
+            header_content: node.children.first,
+            h_num: node.name.delete('h').to_i
+          }
+        end
+      end
+
+      # Returns the list items for entries
+      def build_toc_list(entries)
+        if @configuration.flat_list
+          build_flat_toc_list(entries)
+        else
+          build_nested_toc_list(entries)
+        end
+      end
+
+      # Returns the list items for entries in a flat structure
+      def build_flat_toc_list(entries)
+        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)
+        end
+
+        toc_list
+      end
+
+      # Returns the list items for entries in a nested structure
+      def build_nested_toc_list(entries)
+        i = 0
+        toc_list = +''
+        min_h_num = entries.map { |e| e[:h_num] }.min
+
+        while i < entries.count
+          entry = entries[i]
+          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>)
+            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)
+              toc_list << %(\n<#{list_tag}#{ul_attributes}>\n#{build_nested_toc_list(nest_entries)}</#{list_tag}>\n)
+              i += nest_entries.count
+            end
+            toc_list << %(</#{list_parent_tag}>\n)
+          elsif entry[:h_num] > min_h_num
+            nest_entries = get_nest_entries(entries[i, entries.count], min_h_num)
+            toc_list << build_nested_toc_list(nest_entries)
+            i += nest_entries.count - 1
+          end
+          i += 1
+        end
+
+        toc_list
+      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)
+      def get_nest_entries(entries, min_h_num)
+        entries.inject([]) do |nest_entries, entry|
+          break nest_entries if entry[:h_num] == min_h_num
+
+          nest_entries << entry
+        end
+      end
+
+      def toc_headings
+        @configuration.toc_levels.map { |level| "h#{level}" }.join(',')
+      end
+
+      def toc_headings_in_no_toc_section
+        if @configuration.no_toc_section_class.is_a?(Array)
+          @configuration.no_toc_section_class.map { |cls| toc_headings_within(cls) }.join(',')
+        else
+          toc_headings_within(@configuration.no_toc_section_class)
+        end
+      end
+
+      def toc_headings_within(class_name)
+        @configuration.toc_levels.map { |level| ".#{class_name} h#{level}" }.join(',')
+      end
+
+      def ul_attributes
+        @ul_attributes ||= @configuration.sublist_class.empty? ? '' : %( class="#{@configuration.sublist_class}")
+      end
+
+      def list_parent_tag
+        @list_parent_tag ||= @configuration.div_list ? 'div' : 'li'
+      end
+
+      def list_tag
+        @list_tag ||= if @configuration.div_list
+                        'div'
+                      else
+                        (@configuration.ordered_list ? 'ol' : 'ul')
+                      end
+      end
+    end
+  end
+end

data/lib/table_of_contents/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Jekyll
+  module TableOfContents
+    VERSION = '0.20.0'
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: jekyll-toc-plus
+version: !ruby/object:Gem::Version
+  version: 0.20.0
+platform: ruby
+authors:
+- toshimaru
+- torbjoernk
+- Janne Warén
+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.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.9'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+description: Jekyll (Ruby static website generator) plugin which generates a Table
+  of Contents for the page.
+email: janne.waren@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- Appraisals
+- CHANGELOG.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
+- lib/jekyll-toc-plus.rb
+- lib/table_of_contents/configuration.rb
+- lib/table_of_contents/helper.rb
+- lib/table_of_contents/parser.rb
+- lib/table_of_contents/version.rb
+homepage: https://github.com/jannewaren/jekyll-toc-plus
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jannewaren/jekyll-toc-plus
+  source_code_uri: https://github.com/jannewaren/jekyll-toc-plus
+  changelog_uri: https://github.com/jannewaren/jekyll-toc-plus/releases
+  rubygems_mfa_required: 'true'
+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: 4.0.10
+specification_version: 4
+summary: Jekyll Table of Contents plugin
+test_files: []