jekyll-toc 0.13.0 → 0.16.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.github/dependabot.yml +19 -0
- data/.github/workflows/ci.yml +8 -5
- data/.github/workflows/coverage.yml +15 -14
- data/.github/workflows/rubocop.yml +12 -11
- data/.rubocop.yml +24 -9
- data/Appraisals +5 -9
- data/Gemfile +11 -0
- data/LICENSE.md +1 -1
- data/README.md +99 -33
- data/gemfiles/jekyll_3.8.gemfile +7 -0
- data/gemfiles/jekyll_3.9.gemfile +14 -0
- data/gemfiles/jekyll_4.0.gemfile +7 -0
- data/gemfiles/jekyll_4.1.gemfile +14 -0
- data/jekyll-toc.gemspec +8 -14
- data/lib/table_of_contents/configuration.rb +6 -2
- data/lib/table_of_contents/helper.rb +17 -0
- data/lib/table_of_contents/parser.rb +12 -8
- data/lib/table_of_contents/version.rb +7 -0
- data/test/parser/test_inject_anchors_filter.rb +1 -1
- data/test/parser/test_invalid_options.rb +32 -0
- data/test/parser/test_ordered_list.rb +76 -0
- data/test/parser/test_toc_filter.rb +1 -1
- data/test/parser/test_toc_only_filter.rb +2 -2
- data/test/parser/test_various_toc_html.rb +163 -230
- data/test/test_configuration.rb +17 -13
- data/test/test_helper.rb +2 -2
- data/test/test_jekyll-toc.rb +2 -2
- data/test/test_kramdown_list.rb +5 -5
- data/test/test_toc_tag.rb +1 -1
- metadata +24 -116
- data/gemfiles/jekyll_3.7.gemfile +0 -7
- data/lib/version.rb +0 -5
- data/test/parser/test_option_error.rb +0 -40
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: bd7b0687350d7dfb3589aa9f476f4b2e937aa03dfa7469443ccf7c81eb66557b
|
4
|
+
data.tar.gz: 7318efc6eb7aaf665f74bbae9ae48c26d46f684b54ac36381bd19905e3413f00
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 0c7862b108fcd48e8483945ed8fd0354d9e3f255a6f1c564607da167b1dfde6c59996c3934987c1a2542e36112bb1ad34fcc83b0de6bed65d524b9b7afd05dc5
|
7
|
+
data.tar.gz: e892d4e54cd93a74ae82838cfe451c4b6a9936362ed02cef7552eae7012395091cf3164370dc7c7b9e5a37921ad990b69b128d8640aa5a35795ffb7a714a8301
|
@@ -0,0 +1,19 @@
|
|
1
|
+
# To get started with Dependabot version updates, you'll need to specify which
|
2
|
+
# package ecosystems to update and where the package manifests are located.
|
3
|
+
# Please see the documentation for all configuration options:
|
4
|
+
# https://help.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
|
5
|
+
|
6
|
+
version: 2
|
7
|
+
updates:
|
8
|
+
- package-ecosystem: "bundler"
|
9
|
+
directory: "/"
|
10
|
+
schedule:
|
11
|
+
interval: "weekly"
|
12
|
+
reviewers:
|
13
|
+
- toshimaru
|
14
|
+
- package-ecosystem: "github-actions"
|
15
|
+
directory: "/"
|
16
|
+
schedule:
|
17
|
+
interval: "weekly"
|
18
|
+
reviewers:
|
19
|
+
- toshimaru
|
data/.github/workflows/ci.yml
CHANGED
@@ -1,24 +1,27 @@
|
|
1
1
|
name: CI
|
2
|
-
on: [push]
|
2
|
+
on: [push, pull_request]
|
3
3
|
jobs:
|
4
4
|
build:
|
5
5
|
strategy:
|
6
6
|
matrix:
|
7
7
|
ruby: [2.4, 2.5, 2.6, 2.7]
|
8
8
|
gemfile:
|
9
|
-
|
10
|
-
|
11
|
-
|
9
|
+
- gemfiles/jekyll_3.8.gemfile
|
10
|
+
- gemfiles/jekyll_3.9.gemfile
|
11
|
+
- gemfiles/jekyll_4.0.gemfile
|
12
|
+
- gemfiles/jekyll_4.1.gemfile
|
12
13
|
exclude:
|
13
14
|
- ruby: 2.4
|
14
15
|
gemfile: gemfiles/jekyll_4.0.gemfile
|
16
|
+
- ruby: 2.4
|
17
|
+
gemfile: gemfiles/jekyll_4.1.gemfile
|
15
18
|
env:
|
16
19
|
BUNDLE_GEMFILE: ${{ matrix.gemfile }}
|
17
20
|
runs-on: ubuntu-latest
|
18
21
|
steps:
|
19
22
|
- uses: actions/checkout@v2
|
20
23
|
- name: Set up Ruby ${{ matrix.ruby }}
|
21
|
-
uses:
|
24
|
+
uses: actions/setup-ruby@v1
|
22
25
|
with:
|
23
26
|
ruby-version: ${{ matrix.ruby }}
|
24
27
|
- name: bundle install
|
@@ -1,21 +1,22 @@
|
|
1
1
|
name: Coverage
|
2
|
-
on: [push]
|
2
|
+
on: [push, pull_request]
|
3
3
|
jobs:
|
4
4
|
build:
|
5
5
|
strategy:
|
6
6
|
matrix:
|
7
|
-
ruby: [2.
|
7
|
+
ruby: [2.7]
|
8
8
|
runs-on: ubuntu-latest
|
9
|
+
name: coverage
|
9
10
|
steps:
|
10
|
-
|
11
|
-
|
12
|
-
|
13
|
-
|
14
|
-
|
15
|
-
|
16
|
-
|
17
|
-
|
18
|
-
|
19
|
-
|
20
|
-
|
21
|
-
|
11
|
+
- uses: actions/checkout@v2
|
12
|
+
- name: Set up Ruby ${{ matrix.ruby }}
|
13
|
+
uses: actions/setup-ruby@v1
|
14
|
+
with:
|
15
|
+
ruby-version: ${{ matrix.ruby }}
|
16
|
+
- name: bundle install
|
17
|
+
run: bundle install --jobs 4 --retry 3
|
18
|
+
- uses: paambaati/codeclimate-action@v2.7.5
|
19
|
+
env:
|
20
|
+
CC_TEST_REPORTER_ID: 6b81e393ea6ad38560386f650ea2fb0e57a7beb5e20f8c8364fabee30d5bff07
|
21
|
+
with:
|
22
|
+
coverageCommand: bundle exec rake
|
@@ -1,18 +1,19 @@
|
|
1
1
|
name: RuboCop
|
2
|
-
on: [push]
|
2
|
+
on: [push, pull_request]
|
3
3
|
jobs:
|
4
4
|
build:
|
5
5
|
strategy:
|
6
6
|
matrix:
|
7
|
-
ruby: [2.
|
7
|
+
ruby: [2.7]
|
8
8
|
runs-on: ubuntu-latest
|
9
|
+
name: rubocop
|
9
10
|
steps:
|
10
|
-
|
11
|
-
|
12
|
-
|
13
|
-
|
14
|
-
|
15
|
-
|
16
|
-
|
17
|
-
|
18
|
-
|
11
|
+
- uses: actions/checkout@v2
|
12
|
+
- name: Set up Ruby ${{ matrix.ruby }}
|
13
|
+
uses: actions/setup-ruby@v1
|
14
|
+
with:
|
15
|
+
ruby-version: ${{ matrix.ruby }}
|
16
|
+
- name: bundle install
|
17
|
+
run: bundle install --jobs 4 --retry 3
|
18
|
+
- name: Run RuboCop
|
19
|
+
run: bundle exec rubocop
|
data/.rubocop.yml
CHANGED
@@ -1,28 +1,43 @@
|
|
1
1
|
AllCops:
|
2
2
|
TargetRubyVersion: 2.4
|
3
|
+
NewCops: enable
|
3
4
|
Exclude:
|
4
|
-
-
|
5
|
-
-
|
5
|
+
- "*.gemspec"
|
6
|
+
- "gemfiles/*"
|
7
|
+
- "vendor/**/*"
|
6
8
|
- Rakefile
|
7
9
|
- Gemfile
|
10
|
+
require:
|
11
|
+
- rubocop-performance
|
12
|
+
- rubocop-minitest
|
8
13
|
|
9
14
|
Metrics/MethodLength:
|
10
15
|
Enabled: false
|
11
|
-
|
12
16
|
Metrics/AbcSize:
|
13
17
|
Enabled: false
|
14
|
-
|
15
18
|
Metrics/ClassLength:
|
16
19
|
Enabled: false
|
17
20
|
|
18
|
-
|
21
|
+
Naming/FileName:
|
19
22
|
Enabled: false
|
20
23
|
|
21
|
-
|
24
|
+
Layout/LineLength:
|
22
25
|
Enabled: false
|
26
|
+
Layout/SpaceAroundMethodCallOperator:
|
27
|
+
Enabled: true
|
23
28
|
|
24
|
-
|
25
|
-
Enabled:
|
29
|
+
Lint/RaiseException:
|
30
|
+
Enabled: true
|
31
|
+
Lint/StructNewOverride:
|
32
|
+
Enabled: true
|
26
33
|
|
27
|
-
|
34
|
+
Style/WordArray:
|
28
35
|
Enabled: false
|
36
|
+
Style/HashEachMethods:
|
37
|
+
Enabled: true
|
38
|
+
Style/HashTransformKeys:
|
39
|
+
Enabled: true
|
40
|
+
Style/HashTransformValues:
|
41
|
+
Enabled: true
|
42
|
+
Style/ExponentialNotation:
|
43
|
+
Enabled: true
|
data/Appraisals
CHANGED
@@ -1,13 +1,9 @@
|
|
1
1
|
# frozen_string_literal: true
|
2
2
|
|
3
|
-
|
4
|
-
gem 'jekyll', '4.0'
|
5
|
-
end
|
6
|
-
|
7
|
-
appraise 'jekyll-3.8' do
|
8
|
-
gem 'jekyll', '3.8'
|
9
|
-
end
|
3
|
+
SUPPORTED_VERSIONS = %w[3.8 3.9 4.0 4.1].freeze
|
10
4
|
|
11
|
-
|
12
|
-
|
5
|
+
SUPPORTED_VERSIONS.each do |version|
|
6
|
+
appraise "jekyll-#{version}" do
|
7
|
+
gem 'jekyll', version
|
8
|
+
end
|
13
9
|
end
|
data/Gemfile
CHANGED
@@ -1,3 +1,14 @@
|
|
1
1
|
source 'https://rubygems.org'
|
2
2
|
|
3
3
|
gemspec
|
4
|
+
|
5
|
+
gem 'appraisal'
|
6
|
+
gem 'minitest-reporters'
|
7
|
+
gem 'minitest'
|
8
|
+
gem 'pry'
|
9
|
+
gem 'rake'
|
10
|
+
gem 'rubocop-minitest'
|
11
|
+
gem 'rubocop-performance'
|
12
|
+
gem 'rubocop-rake'
|
13
|
+
gem 'rubocop'
|
14
|
+
gem 'simplecov', '~> 0.17.1'
|
data/LICENSE.md
CHANGED
data/README.md
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
# jekyll-toc
|
2
2
|
|
3
3
|
![CI](https://github.com/toshimaru/jekyll-toc/workflows/CI/badge.svg)
|
4
|
-
[![Gem Version](https://badge.fury.io/rb/jekyll-toc.svg)](
|
4
|
+
[![Gem Version](https://badge.fury.io/rb/jekyll-toc.svg)](https://badge.fury.io/rb/jekyll-toc)
|
5
5
|
[![Code Climate](https://codeclimate.com/github/toshimaru/jekyll-toc/badges/gpa.svg)](https://codeclimate.com/github/toshimaru/jekyll-toc)
|
6
6
|
[![Test Coverage](https://api.codeclimate.com/v1/badges/cd56b207f327603662a1/test_coverage)](https://codeclimate.com/github/toshimaru/jekyll-toc/test_coverage)
|
7
7
|
|
@@ -9,16 +9,19 @@
|
|
9
9
|
|
10
10
|
- [Installation](#installation)
|
11
11
|
- [Usage](#usage)
|
12
|
-
- [
|
13
|
-
- [
|
12
|
+
- [Basic Usage](#basic-usage)
|
13
|
+
- [Advanced Usage](#advanced-usage)
|
14
14
|
- [Generated HTML](#generated-html)
|
15
|
-
- [Default Configuration](#default-configuration)
|
16
15
|
- [Customization](#customization)
|
16
|
+
- [Default Configuration](#default-configuration)
|
17
17
|
- [TOC levels](#toc-levels)
|
18
|
+
- [Enable TOC by default](#enable-toc-by-default)
|
18
19
|
- [Skip TOC](#skip-toc)
|
19
|
-
- [Skip TOC
|
20
|
+
- [Skip TOC Sectionally](#skip-toc-sectionally)
|
20
21
|
- [CSS Styling](#css-styling)
|
21
|
-
- [Custom CSS Class](#custom-css-class)
|
22
|
+
- [Custom CSS Class and ID](#custom-css-class-and-id)
|
23
|
+
- [Using Unordered/Ordered lists](#using-unorderedordered-lists)
|
24
|
+
- [Alternative Tools](#alternative-tools)
|
22
25
|
|
23
26
|
## Installation
|
24
27
|
|
@@ -50,7 +53,7 @@ toc: true
|
|
50
53
|
There are three Liquid filters, which can be applied to HTML content,
|
51
54
|
e.g. the Liquid variable `content` available in Jekyll's templates.
|
52
55
|
|
53
|
-
###
|
56
|
+
### Basic Usage
|
54
57
|
|
55
58
|
#### `toc` filter
|
56
59
|
|
@@ -62,11 +65,11 @@ Add the `toc` filter to your site's `{{ content }}` (e.g. `_layouts/post.html`).
|
|
62
65
|
|
63
66
|
This filter places the TOC directly above the content.
|
64
67
|
|
65
|
-
###
|
68
|
+
### Advanced Usage
|
66
69
|
|
67
70
|
If you'd like separated TOC and content, you can use `{% toc %}` tag (or `toc_only` filter) and `inject_anchors` filter.
|
68
71
|
|
69
|
-
#### `{% toc %}` tag
|
72
|
+
#### `{% toc %}` tag / `toc_only` filter
|
70
73
|
|
71
74
|
Generates the TOC itself as described [below](#generated-html).
|
72
75
|
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.
|
|
85
88
|
|
86
89
|
:warning: **`{% toc %}` Tag Limitation**
|
87
90
|
|
88
|
-
`{% toc %}`
|
91
|
+
`{% toc %}` works only for [Jekyll Posts](https://jekyllrb.com/docs/step-by-step/08-blogging/) and [Jekyll Collections](https://jekyllrb.com/docs/collections/).
|
92
|
+
If you'd like to use `{% toc %}` except posts or collections, please use `toc_only` filter as described below.
|
89
93
|
|
90
94
|
```html
|
91
95
|
<div>
|
@@ -114,10 +118,10 @@ location with the `toc_only` filter.
|
|
114
118
|
|
115
119
|
## Generated HTML
|
116
120
|
|
117
|
-
jekyll-toc generates an unordered list. The HTML output is as follows.
|
121
|
+
jekyll-toc generates an unordered list by default. The HTML output is as follows.
|
118
122
|
|
119
123
|
```html
|
120
|
-
<ul class="section-nav">
|
124
|
+
<ul id="toc" class="section-nav">
|
121
125
|
<li class="toc-entry toc-h1"><a href="#heading1">Heading.1</a>
|
122
126
|
<ul>
|
123
127
|
<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.
|
|
140
144
|
|
141
145
|
![screenshot](https://user-images.githubusercontent.com/803398/28401295-0dcfb7ca-6d54-11e7-892b-2f2e6ca755a7.png)
|
142
146
|
|
143
|
-
##
|
147
|
+
## Customization
|
148
|
+
|
149
|
+
jekyll-toc is customizable on `_config.yml`.
|
150
|
+
|
151
|
+
### Default Configuration
|
144
152
|
|
145
153
|
```yml
|
154
|
+
# _config.yml
|
146
155
|
toc:
|
147
156
|
min_level: 1
|
148
157
|
max_level: 6
|
158
|
+
ordered_list: false
|
149
159
|
no_toc_section_class: no_toc_section
|
160
|
+
list_id: toc
|
150
161
|
list_class: section-nav
|
151
162
|
sublist_class: ''
|
152
163
|
item_class: toc-entry
|
153
164
|
item_prefix: toc-
|
154
165
|
```
|
155
166
|
|
156
|
-
## Customization
|
157
|
-
|
158
167
|
### TOC levels
|
159
168
|
|
160
|
-
The toc levels can be configured on `_config.yml`:
|
161
|
-
|
162
169
|
```yml
|
170
|
+
# _config.yml
|
163
171
|
toc:
|
164
172
|
min_level: 2 # default: 1
|
165
173
|
max_level: 5 # default: 6
|
166
174
|
```
|
167
175
|
|
168
|
-
The default
|
176
|
+
The default heading range is from `<h1>` to `<h6>`.
|
177
|
+
|
178
|
+
### Enable TOC by default
|
179
|
+
|
180
|
+
You can enable TOC by default with [Front Matter Defaults](https://jekyllrb.com/docs/configuration/front-matter-defaults/):
|
181
|
+
|
182
|
+
```yml
|
183
|
+
# _config.yml
|
184
|
+
defaults:
|
185
|
+
- scope:
|
186
|
+
path: ""
|
187
|
+
values:
|
188
|
+
toc: true
|
189
|
+
```
|
169
190
|
|
170
191
|
### Skip TOC
|
171
192
|
|
172
|
-
The heading is ignored in the toc
|
193
|
+
The heading is ignored in the toc by adding `no_toc` class.
|
173
194
|
|
174
195
|
```html
|
175
196
|
<h1>h1</h1>
|
176
|
-
<h1 class="no_toc">This heading is ignored in the
|
197
|
+
<h1 class="no_toc">This heading is ignored in the TOC</h1>
|
177
198
|
<h2>h2</h2>
|
178
199
|
```
|
179
200
|
|
180
|
-
### Skip TOC
|
201
|
+
### Skip TOC Sectionally
|
181
202
|
|
182
203
|
The headings are ignored inside the element which has `no_toc_section` class.
|
183
204
|
|
184
205
|
```html
|
185
206
|
<h1>h1</h1>
|
186
207
|
<div class="no_toc_section">
|
187
|
-
<h2>This heading is ignored in the
|
188
|
-
<h3>This heading is ignored in the
|
208
|
+
<h2>This heading is ignored in the TOC</h2>
|
209
|
+
<h3>This heading is ignored in the TOC</h3>
|
189
210
|
</div>
|
190
211
|
<h4>h4</h4>
|
191
212
|
```
|
@@ -195,13 +216,15 @@ Which would result in only the `<h1>` & `<h4>` within the example being included
|
|
195
216
|
The class can be configured on `_config.yml`:
|
196
217
|
|
197
218
|
```yml
|
219
|
+
# _config.yml
|
198
220
|
toc:
|
199
221
|
no_toc_section_class: exclude # default: no_toc_section
|
200
222
|
```
|
201
223
|
|
202
|
-
Configuring multiple classes
|
224
|
+
Configuring multiple classes are allowed:
|
203
225
|
|
204
226
|
```yml
|
227
|
+
# _config.yml
|
205
228
|
toc:
|
206
229
|
no_toc_section_class:
|
207
230
|
- no_toc_section
|
@@ -227,21 +250,64 @@ The toc can be modified with CSS. The sample CSS is the following.
|
|
227
250
|
|
228
251
|
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`.
|
229
252
|
|
230
|
-
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.
|
231
|
-
`#` in Markdown) will get the CSS class `toc-h1`.
|
253
|
+
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.
|
254
|
+
For example, the TOC entry linking to a heading `<h1>...</h1>` (a single `#` in Markdown) will get the CSS class `toc-h1`.
|
232
255
|
|
233
|
-
### Custom CSS Class
|
256
|
+
### Custom CSS Class and ID
|
234
257
|
|
235
258
|
You can apply custom CSS classes to the generated `<ul>` and `<li>` tags.
|
236
259
|
|
237
260
|
```yml
|
261
|
+
# _config.yml
|
262
|
+
toc:
|
263
|
+
list_id: my-toc-id # Default: "toc"
|
264
|
+
list_class: my-list-class # Default: "section-nav"
|
265
|
+
sublist_class: my-sublist-class # Default: no class for sublists
|
266
|
+
item_class: my-item-class # Default: "toc-entry"
|
267
|
+
item_prefix: item- # Default: "toc-":
|
268
|
+
```
|
269
|
+
|
270
|
+
### Using Unordered/Ordered lists
|
271
|
+
|
272
|
+
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>`.
|
273
|
+
This can be configured in `_config.yml`:
|
274
|
+
|
275
|
+
```yml
|
276
|
+
# _config.yml
|
238
277
|
toc:
|
239
|
-
#
|
278
|
+
ordered_list: true # default is false
|
279
|
+
```
|
280
|
+
|
281
|
+
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.
|
282
|
+
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.
|
283
|
+
|
284
|
+
Example
|
285
|
+
|
286
|
+
```yml
|
287
|
+
# _config.yml
|
288
|
+
toc:
|
289
|
+
ordered_list: true
|
240
290
|
list_class: my-list-class
|
241
|
-
# Default is no class for sublists:
|
242
291
|
sublist_class: my-sublist-class
|
243
|
-
# Default is "toc-entry":
|
244
|
-
item_class: my-item-class
|
245
|
-
# Default is "toc-":
|
246
|
-
item_prefix: item-
|
247
292
|
```
|
293
|
+
|
294
|
+
```css
|
295
|
+
.my-list-class {
|
296
|
+
list-style-type: upper-alpha;
|
297
|
+
}
|
298
|
+
|
299
|
+
.my-sublist-class: {
|
300
|
+
list-style-type: lower-alpha;
|
301
|
+
}
|
302
|
+
```
|
303
|
+
|
304
|
+
This will produce:
|
305
|
+
|
306
|
+
![screenshot](https://user-images.githubusercontent.com/7675276/85813980-a0ea5a80-b719-11ea-9458-ccf9b86a778b.png)
|
307
|
+
|
308
|
+
## Alternative Tools
|
309
|
+
|
310
|
+
- Adding anchor to headings
|
311
|
+
- [AnchorJS](https://www.bryanbraun.com/anchorjs/)
|
312
|
+
- Generating TOC for kramdown content
|
313
|
+
- [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))
|