jekyll-toc 0.13.1 → 0.16.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6123e008a00020b06966fcfa4e66fab35284e48f5bc4a5fcb3d26ea0ca2d403
-  data.tar.gz: ad37834ad4d61ba77873ac067f86104e9bee7c5a82a6b1d5bdcd912076b4291f
+  metadata.gz: 620c7b76a5dcffc7d12cacccadc5371700e05aa9cc0b63342d7e9b8be82251c4
+  data.tar.gz: 9408a17eb39c5731c93d230fcae0d88cbd1d0feabb24d77a99d72a5daac6bc39
 SHA512:
-  metadata.gz: e9c6b782daf540efffda92f9b1016cb0dc2006f7ae2792cea07742c359f2eb73c08d0e78d97e2a5a4f0ed6e57dca0ec72a1d4473df2fbd519db2c7a888e6c345
-  data.tar.gz: fe877c2210252015b8166d6276be755040e6e344aea232dfb61a334fb600889f76669c1ab38f305362e4655897a2bf6b451a42e7e9fd9f627ba4cebf10c65e68
+  metadata.gz: 6a90ffe23c78afe62746863488f9bc73855c6f707eee0676d2652fa8b9f325663e3605593e3c59b1eee9c81df37bd4ff21fb46268b70f0b6ff7ef3f4ec112d6d
+  data.tar.gz: a1d757462fe314e449ecc4259eeb8257d6f81d8898667060bf08a325e77db27db751a90de6f76f53b9c50aaf2d50896e622640f72e1e0d9bc160fed0668deedc

data/.github/dependabot.yml

@@ -0,0 +1,19 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "bundler"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    reviewers:
+      - toshimaru
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    reviewers:
+      - toshimaru

data/.github/workflows/ci.yml

@@ -1,24 +1,30 @@
 name: CI
-on: [push]
+on: [push, pull_request]
 jobs:
   build:
     strategy:
       matrix:
         ruby: [2.4, 2.5, 2.6, 2.7]
         gemfile:
-        - gemfiles/jekyll_4.0.gemfile
-        - gemfiles/jekyll_3.8.gemfile
-        - gemfiles/jekyll_3.7.gemfile
+          - gemfiles/jekyll_3.8.gemfile
+          - gemfiles/jekyll_3.9.gemfile
+          - gemfiles/jekyll_4.0.gemfile
+          - gemfiles/jekyll_4.1.gemfile
+          - gemfiles/jekyll_4.2.gemfile
         exclude:
         - ruby: 2.4
           gemfile: gemfiles/jekyll_4.0.gemfile
+        - ruby: 2.4
+          gemfile: gemfiles/jekyll_4.1.gemfile
+        - ruby: 2.4
+          gemfile: gemfiles/jekyll_4.2.gemfile
     env:
       BUNDLE_GEMFILE: ${{ matrix.gemfile }}
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2
     - name: Set up Ruby ${{ matrix.ruby }}
-      uses: eregon/use-ruby-action@master
+      uses: actions/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby }}
     - name: bundle install

data/.github/workflows/coverage.yml

@@ -1,21 +1,22 @@
 name: Coverage
-on: [push]
+on: [push, pull_request]
 jobs:
   build:
     strategy:
       matrix:
-        ruby: [2.6]
+        ruby: [2.7]
     runs-on: ubuntu-latest
+    name: coverage
     steps:
-    - uses: actions/checkout@v2
-    - name: Set up Ruby ${{ matrix.ruby }}
-      uses: eregon/use-ruby-action@master
-      with:
-        ruby-version: ${{ matrix.ruby }}
-    - name: bundle install
-      run: bundle install --jobs 4 --retry 3
-    - uses: paambaati/codeclimate-action@v2.4.0
-      env:
-        CC_TEST_REPORTER_ID: 6b81e393ea6ad38560386f650ea2fb0e57a7beb5e20f8c8364fabee30d5bff07
-      with:
-        coverageCommand: bundle exec rake
+      - uses: actions/checkout@v2
+      - name: Set up Ruby ${{ matrix.ruby }}
+        uses: actions/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: bundle install
+        run: bundle install --jobs 4 --retry 3
+      - uses: paambaati/codeclimate-action@v2.7.5
+        env:
+          CC_TEST_REPORTER_ID: 6b81e393ea6ad38560386f650ea2fb0e57a7beb5e20f8c8364fabee30d5bff07
+        with:
+          coverageCommand: bundle exec rake

data/.github/workflows/rubocop.yml

@@ -1,18 +1,19 @@
 name: RuboCop
-on: [push]
+on: [push, pull_request]
 jobs:
   build:
     strategy:
       matrix:
-        ruby: [2.6]
+        ruby: [2.7]
     runs-on: ubuntu-latest
+    name: rubocop
     steps:
-    - uses: actions/checkout@v2
-    - name: Set up Ruby ${{ matrix.ruby }}
-      uses: eregon/use-ruby-action@master
-      with:
-        ruby-version: ${{ matrix.ruby }}
-    - name: bundle install
-      run: bundle install --jobs 4 --retry 3
-    - name: Run RuboCop
-      run: bundle exec rubocop
+      - uses: actions/checkout@v2
+      - name: Set up Ruby ${{ matrix.ruby }}
+        uses: actions/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - name: bundle install
+        run: bundle install --jobs 4 --retry 3
+      - name: Run RuboCop
+        run: bundle exec rubocop

data/.rubocop.yml

@@ -1,28 +1,43 @@
 AllCops:
   TargetRubyVersion: 2.4
+  NewCops: enable
   Exclude:
-    - '*.gemspec'
-    - 'gemfiles/*'
+    - "*.gemspec"
+    - "gemfiles/*"
+    - "vendor/**/*"
     - Rakefile
     - Gemfile
+require:
+  - rubocop-performance
+  - rubocop-minitest
 
 Metrics/MethodLength:
   Enabled: false
-
 Metrics/AbcSize:
   Enabled: false
-
 Metrics/ClassLength:
   Enabled: false
 
-Style/BracesAroundHashParameters:
+Naming/FileName:
   Enabled: false
 
-Style/WordArray:
+Layout/LineLength:
   Enabled: false
+Layout/SpaceAroundMethodCallOperator:
+  Enabled: true
 
-Naming/FileName:
-  Enabled: false
+Lint/RaiseException:
+  Enabled: true
+Lint/StructNewOverride:
+  Enabled: true
 
-Layout/LineLength: 
+Style/WordArray:
   Enabled: false
+Style/HashEachMethods:
+  Enabled: true
+Style/HashTransformKeys:
+  Enabled: true
+Style/HashTransformValues:
+  Enabled: true
+Style/ExponentialNotation:
+  Enabled: true

data/Appraisals

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

data/Gemfile

@@ -7,5 +7,8 @@ gem 'minitest-reporters'
 gem 'minitest'
 gem 'pry'
 gem 'rake'
+gem 'rubocop-minitest'
+gem 'rubocop-performance'
+gem 'rubocop-rake'
 gem 'rubocop'
-gem 'simplecov'
+gem 'simplecov', '~> 0.17.1'

data/README.md

@@ -1,7 +1,7 @@
 # jekyll-toc
 
 ![CI](https://github.com/toshimaru/jekyll-toc/workflows/CI/badge.svg)
-[![Gem Version](https://badge.fury.io/rb/jekyll-toc.svg)](http://badge.fury.io/rb/jekyll-toc)
+[![Gem Version](https://badge.fury.io/rb/jekyll-toc.svg)](https://badge.fury.io/rb/jekyll-toc)
 [![Code Climate](https://codeclimate.com/github/toshimaru/jekyll-toc/badges/gpa.svg)](https://codeclimate.com/github/toshimaru/jekyll-toc)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/cd56b207f327603662a1/test_coverage)](https://codeclimate.com/github/toshimaru/jekyll-toc/test_coverage)
 
@@ -9,16 +9,19 @@
 
 - [Installation](#installation)
 - [Usage](#usage)
-  - [1. Basic Usage](#1-basic-usage)
-  - [2. Advanced Usage](#2-advanced-usage)
+  - [Basic Usage](#basic-usage)
+  - [Advanced Usage](#advanced-usage)
 - [Generated HTML](#generated-html)
-- [Default Configuration](#default-configuration)
 - [Customization](#customization)
+  - [Default Configuration](#default-configuration)
   - [TOC levels](#toc-levels)
+  - [Enable TOC by default](#enable-toc-by-default)
   - [Skip TOC](#skip-toc)
-  - [Skip TOC Section](#skip-toc-section)
+  - [Skip TOC Sectionally](#skip-toc-sectionally)
   - [CSS Styling](#css-styling)
-  - [Custom CSS Class](#custom-css-class)
+  - [Custom CSS Class and ID](#custom-css-class-and-id)
+  - [Using Unordered/Ordered lists](#using-unorderedordered-lists)
+- [Alternative Tools](#alternative-tools)
 
 ## Installation
 
@@ -50,7 +53,7 @@ toc: true
 There are three Liquid filters, which can be applied to HTML content,
 e.g. the Liquid variable `content` available in Jekyll's templates.
 
-### 1. Basic Usage
+### Basic Usage
 
 #### `toc` filter
 
@@ -62,11 +65,11 @@ Add the `toc` filter to your site's `{{ content }}` (e.g. `_layouts/post.html`).
 
 This filter places the TOC directly above the content.
 
-### 2. Advanced Usage
+### 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 %}` 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
@@ -85,7 +88,8 @@ above the content but at some other place of the page, i.e. an aside.
 
 :warning: **`{% toc %}` Tag Limitation**
 
-`{% toc %}` can be available only in [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.
+`{% 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>
@@ -114,10 +118,10 @@ location with the `toc_only` filter.
 
 ## Generated HTML
 
-jekyll-toc generates an unordered list. The HTML output is as follows.
+jekyll-toc generates an unordered list by default. The HTML output is as follows.
 
 ```html
-<ul class="section-nav">
+<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>
@@ -140,52 +144,69 @@ jekyll-toc generates an unordered list. The HTML output is as follows.
 
 ![screenshot](https://user-images.githubusercontent.com/803398/28401295-0dcfb7ca-6d54-11e7-892b-2f2e6ca755a7.png)
 
-## Default Configuration 
+## 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-
 ```
 
-## Customization
-
 ### TOC levels
 
-The toc levels can be configured on `_config.yml`:
-
 ```yml
+# _config.yml
 toc:
   min_level: 2 # default: 1
   max_level: 5 # default: 6
 ```
 
-The default level range is `<h1>` to `<h6>`.
+The default heading range is from `<h1>` to `<h6>`.
+
+### 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 when you add `no_toc` to the class.
+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>
+<h1 class="no_toc">This heading is ignored in the TOC</h1>
 <h2>h2</h2>
 ```
 
-### Skip TOC Section
+### 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>
+  <h2>This heading is ignored in the TOC</h2>
+  <h3>This heading is ignored in the TOC</h3>
 </div>
 <h4>h4</h4>
 ```
@@ -195,13 +216,15 @@ Which would result in only the `<h1>` & `<h4>` within the example being included
 The class can be configured on `_config.yml`:
 
 ```yml
+# _config.yml
 toc:
   no_toc_section_class: exclude # default: no_toc_section
 ```
 
-Configuring multiple classes for `no_toc_section_class` is allowed:
+Configuring multiple classes are allowed:
 
 ```yml
+# _config.yml
 toc:
   no_toc_section_class:
     - no_toc_section
@@ -227,21 +250,64 @@ The toc can be modified with CSS. The sample CSS is the following.
 
 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`.
+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
+### 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:
-  # Default is "section-nav":
+  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
-  # Default is no class for sublists:
   sublist_class: my-sublist-class
-  # Default is "toc-entry":
-  item_class: my-item-class
-  # Default is "toc-":
-  item_prefix: item-
 ```
+
+```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)
+
+## 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))