jekyll-toc 0.12.2 → 0.15.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 +32 -0
- data/.github/workflows/coverage.yml +22 -0
- data/.github/workflows/rubocop.yml +19 -0
- data/.rubocop.yml +24 -9
- data/Appraisals +5 -9
- data/Gemfile +10 -0
- data/LICENSE.md +1 -1
- data/README.md +106 -29
- data/gemfiles/jekyll_3.8.gemfile +7 -0
- data/gemfiles/jekyll_3.9.gemfile +14 -0
- data/gemfiles/jekyll_4.0.gemfile +14 -0
- data/gemfiles/jekyll_4.1.gemfile +14 -0
- data/jekyll-toc.gemspec +9 -15
- data/lib/table_of_contents/configuration.rb +4 -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_option_error.rb → test_invalid_options.rb} +6 -14
- data/test/parser/test_ordered_list.rb +76 -0
- data/test/parser/test_toc_only_filter.rb +2 -2
- data/test/parser/test_various_toc_html.rb +147 -214
- data/test/test_configuration.rb +15 -13
- data/test/test_helper.rb +2 -2
- data/test/test_toc_tag.rb +1 -1
- metadata +29 -119
- data/.travis.yml +0 -22
- data/gemfiles/jekyll_3.6.gemfile +0 -7
- data/gemfiles/jekyll_3.7.gemfile +0 -7
- data/lib/version.rb +0 -5
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: e250bc0a38525c4496ba464685b2ca3bc9c462953ce7c299a52cf52611940099
|
4
|
+
data.tar.gz: 628f832e2adaae7b8b225423149b6dd950d04c884698f1b8e42c6e3990f33359
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 258fde765cb95ce75abd2b87a4336a3a58630188e872c337014b8b780ac06843521b49070a201a3c9cdc7530409f61caeb159b770801b580eed8fb4921a5f74c
|
7
|
+
data.tar.gz: d9d8e1dc2b78c353333db1af1ad03eb86b387e35e89fea8fd554c834e3b8d93b200539f48f9bc070d95bb24f18addb8127329b966a6512ef6bac02909ce37ef1
|
@@ -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
|
@@ -0,0 +1,32 @@
|
|
1
|
+
name: CI
|
2
|
+
on: [push, pull_request]
|
3
|
+
jobs:
|
4
|
+
build:
|
5
|
+
strategy:
|
6
|
+
matrix:
|
7
|
+
ruby: [2.4, 2.5, 2.6, 2.7]
|
8
|
+
gemfile:
|
9
|
+
- gemfiles/jekyll_3.8.gemfile
|
10
|
+
- gemfiles/jekyll_3.9.gemfile
|
11
|
+
- gemfiles/jekyll_4.0.gemfile
|
12
|
+
- gemfiles/jekyll_4.1.gemfile
|
13
|
+
exclude:
|
14
|
+
- ruby: 2.4
|
15
|
+
gemfile: gemfiles/jekyll_4.0.gemfile
|
16
|
+
- ruby: 2.4
|
17
|
+
gemfile: gemfiles/jekyll_4.1.gemfile
|
18
|
+
env:
|
19
|
+
BUNDLE_GEMFILE: ${{ matrix.gemfile }}
|
20
|
+
runs-on: ubuntu-latest
|
21
|
+
steps:
|
22
|
+
- uses: actions/checkout@v2
|
23
|
+
- name: Set up Ruby ${{ matrix.ruby }}
|
24
|
+
uses: actions/setup-ruby@v1
|
25
|
+
with:
|
26
|
+
ruby-version: ${{ matrix.ruby }}
|
27
|
+
- name: bundle install
|
28
|
+
run: |
|
29
|
+
gem install bundler
|
30
|
+
bundle install --jobs 4 --retry 3
|
31
|
+
- name: Run Test
|
32
|
+
run: bundle exec rake
|
@@ -0,0 +1,22 @@
|
|
1
|
+
name: Coverage
|
2
|
+
on: [push, pull_request]
|
3
|
+
jobs:
|
4
|
+
build:
|
5
|
+
strategy:
|
6
|
+
matrix:
|
7
|
+
ruby: [2.6]
|
8
|
+
runs-on: ubuntu-latest
|
9
|
+
name: coverage
|
10
|
+
steps:
|
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.4
|
19
|
+
env:
|
20
|
+
CC_TEST_REPORTER_ID: 6b81e393ea6ad38560386f650ea2fb0e57a7beb5e20f8c8364fabee30d5bff07
|
21
|
+
with:
|
22
|
+
coverageCommand: bundle exec rake
|
@@ -0,0 +1,19 @@
|
|
1
|
+
name: RuboCop
|
2
|
+
on: [push, pull_request]
|
3
|
+
jobs:
|
4
|
+
build:
|
5
|
+
strategy:
|
6
|
+
matrix:
|
7
|
+
ruby: [2.6]
|
8
|
+
runs-on: ubuntu-latest
|
9
|
+
name: rubocop
|
10
|
+
steps:
|
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
|
8
|
-
|
9
|
-
|
10
|
-
|
10
|
+
require:
|
11
|
+
- rubocop-performance
|
12
|
+
- rubocop-minitest
|
11
13
|
|
12
14
|
Metrics/MethodLength:
|
13
15
|
Enabled: false
|
14
|
-
|
15
16
|
Metrics/AbcSize:
|
16
17
|
Enabled: false
|
17
|
-
|
18
18
|
Metrics/ClassLength:
|
19
19
|
Enabled: false
|
20
20
|
|
21
|
-
|
21
|
+
Naming/FileName:
|
22
22
|
Enabled: false
|
23
23
|
|
24
|
-
|
24
|
+
Layout/LineLength:
|
25
25
|
Enabled: false
|
26
|
+
Layout/SpaceAroundMethodCallOperator:
|
27
|
+
Enabled: true
|
28
|
+
|
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', '3.8'
|
5
|
-
end
|
6
|
-
|
7
|
-
appraise 'jekyll-3.7' do
|
8
|
-
gem 'jekyll', '3.7'
|
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
data/LICENSE.md
CHANGED
data/README.md
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
# jekyll-toc
|
2
2
|
|
3
|
-
|
4
|
-
[![Gem Version](https://badge.fury.io/rb/jekyll-toc.svg)](
|
3
|
+
![CI](https://github.com/toshimaru/jekyll-toc/workflows/CI/badge.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
22
|
- [Custom CSS Class](#custom-css-class)
|
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,13 +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
|
-
If you'd like separated TOC and content, you can use `toc_only` and `inject_anchors`
|
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_only` filter
|
70
|
-
|
71
|
-
⚠️ ~~Please use `{% toc %}` instead of `{{ content | toc_only }}`.~~
|
72
|
+
#### `{% toc %}` tag / `toc_only` filter
|
72
73
|
|
73
74
|
Generates the TOC itself as described [below](#generated-html).
|
74
75
|
Mostly useful in cases where the TOC should _not_ be placed immediately
|
@@ -85,9 +86,21 @@ above the content but at some other place of the page, i.e. an aside.
|
|
85
86
|
</div>
|
86
87
|
```
|
87
88
|
|
88
|
-
|
89
|
+
:warning: **`{% toc %}` Tag Limitation**
|
90
|
+
|
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
|
95
|
+
<div>
|
96
|
+
<div id="table-of-contents">
|
97
|
+
{{ content | toc_only }}
|
98
|
+
</div>
|
99
|
+
<div id="markdown-content">
|
100
|
+
{{ content | inject_anchors }}
|
101
|
+
</div>
|
102
|
+
</div>
|
103
|
+
```
|
91
104
|
|
92
105
|
#### `inject_anchors` filter
|
93
106
|
|
@@ -105,7 +118,7 @@ location with the `toc_only` filter.
|
|
105
118
|
|
106
119
|
## Generated HTML
|
107
120
|
|
108
|
-
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.
|
109
122
|
|
110
123
|
```html
|
111
124
|
<ul class="section-nav">
|
@@ -131,12 +144,18 @@ jekyll-toc generates an unordered list. The HTML output is as follows.
|
|
131
144
|
|
132
145
|
![screenshot](https://user-images.githubusercontent.com/803398/28401295-0dcfb7ca-6d54-11e7-892b-2f2e6ca755a7.png)
|
133
146
|
|
134
|
-
##
|
147
|
+
## Customization
|
148
|
+
|
149
|
+
jekyll-toc is customizable on `_config.yml`.
|
150
|
+
|
151
|
+
### Default Configuration
|
135
152
|
|
136
153
|
```yml
|
154
|
+
# _config.yml
|
137
155
|
toc:
|
138
156
|
min_level: 1
|
139
157
|
max_level: 6
|
158
|
+
ordered_list: false
|
140
159
|
no_toc_section_class: no_toc_section
|
141
160
|
list_class: section-nav
|
142
161
|
sublist_class: ''
|
@@ -144,39 +163,49 @@ toc:
|
|
144
163
|
item_prefix: toc-
|
145
164
|
```
|
146
165
|
|
147
|
-
## Customization
|
148
|
-
|
149
166
|
### TOC levels
|
150
167
|
|
151
|
-
The toc levels can be configured on `_config.yml`:
|
152
|
-
|
153
168
|
```yml
|
169
|
+
# _config.yml
|
154
170
|
toc:
|
155
171
|
min_level: 2 # default: 1
|
156
172
|
max_level: 5 # default: 6
|
157
173
|
```
|
158
174
|
|
159
|
-
The default
|
175
|
+
The default heading range is from `<h1>` to `<h6>`.
|
176
|
+
|
177
|
+
### Enable TOC by default
|
178
|
+
|
179
|
+
You can enable TOC by default with [Front Matter Defaults](https://jekyllrb.com/docs/configuration/front-matter-defaults/):
|
180
|
+
|
181
|
+
```yml
|
182
|
+
# _config.yml
|
183
|
+
defaults:
|
184
|
+
- scope:
|
185
|
+
path: ""
|
186
|
+
values:
|
187
|
+
toc: true
|
188
|
+
```
|
160
189
|
|
161
190
|
### Skip TOC
|
162
191
|
|
163
|
-
The heading is ignored in the toc
|
192
|
+
The heading is ignored in the toc by adding `no_toc` class.
|
164
193
|
|
165
194
|
```html
|
166
195
|
<h1>h1</h1>
|
167
|
-
<h1 class="no_toc">This heading is ignored in the
|
196
|
+
<h1 class="no_toc">This heading is ignored in the TOC</h1>
|
168
197
|
<h2>h2</h2>
|
169
198
|
```
|
170
199
|
|
171
|
-
### Skip TOC
|
200
|
+
### Skip TOC Sectionally
|
172
201
|
|
173
202
|
The headings are ignored inside the element which has `no_toc_section` class.
|
174
203
|
|
175
204
|
```html
|
176
205
|
<h1>h1</h1>
|
177
206
|
<div class="no_toc_section">
|
178
|
-
<h2>This heading is ignored in the
|
179
|
-
<h3>This heading is ignored in the
|
207
|
+
<h2>This heading is ignored in the TOC</h2>
|
208
|
+
<h3>This heading is ignored in the TOC</h3>
|
180
209
|
</div>
|
181
210
|
<h4>h4</h4>
|
182
211
|
```
|
@@ -186,13 +215,15 @@ Which would result in only the `<h1>` & `<h4>` within the example being included
|
|
186
215
|
The class can be configured on `_config.yml`:
|
187
216
|
|
188
217
|
```yml
|
218
|
+
# _config.yml
|
189
219
|
toc:
|
190
220
|
no_toc_section_class: exclude # default: no_toc_section
|
191
221
|
```
|
192
222
|
|
193
|
-
Configuring multiple classes
|
223
|
+
Configuring multiple classes are allowed:
|
194
224
|
|
195
225
|
```yml
|
226
|
+
# _config.yml
|
196
227
|
toc:
|
197
228
|
no_toc_section_class:
|
198
229
|
- no_toc_section
|
@@ -218,14 +249,15 @@ The toc can be modified with CSS. The sample CSS is the following.
|
|
218
249
|
|
219
250
|
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`.
|
220
251
|
|
221
|
-
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.
|
222
|
-
`#` in Markdown) will get the CSS class `toc-h1`.
|
252
|
+
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.
|
253
|
+
For example, the TOC entry linking to a heading `<h1>...</h1>` (a single `#` in Markdown) will get the CSS class `toc-h1`.
|
223
254
|
|
224
255
|
### Custom CSS Class
|
225
256
|
|
226
257
|
You can apply custom CSS classes to the generated `<ul>` and `<li>` tags.
|
227
258
|
|
228
259
|
```yml
|
260
|
+
# _config.yml
|
229
261
|
toc:
|
230
262
|
# Default is "section-nav":
|
231
263
|
list_class: my-list-class
|
@@ -236,3 +268,48 @@ toc:
|
|
236
268
|
# Default is "toc-":
|
237
269
|
item_prefix: item-
|
238
270
|
```
|
271
|
+
|
272
|
+
### Using Unordered/Ordered lists
|
273
|
+
|
274
|
+
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>`.
|
275
|
+
This can be configured in `_config.yml`:
|
276
|
+
|
277
|
+
```yml
|
278
|
+
# _config.yml
|
279
|
+
toc:
|
280
|
+
ordered_list: true # default is false
|
281
|
+
```
|
282
|
+
|
283
|
+
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.
|
284
|
+
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.
|
285
|
+
|
286
|
+
Example
|
287
|
+
|
288
|
+
```yml
|
289
|
+
# _config.yml
|
290
|
+
toc:
|
291
|
+
ordered_list: true
|
292
|
+
list_class: my-list-class
|
293
|
+
sublist_class: my-sublist-class
|
294
|
+
```
|
295
|
+
|
296
|
+
```css
|
297
|
+
.my-list-class {
|
298
|
+
list-style-type: upper-alpha;
|
299
|
+
}
|
300
|
+
|
301
|
+
.my-sublist-class: {
|
302
|
+
list-style-type: lower-alpha;
|
303
|
+
}
|
304
|
+
```
|
305
|
+
|
306
|
+
This will produce:
|
307
|
+
|
308
|
+
![screenshot](https://user-images.githubusercontent.com/7675276/85813980-a0ea5a80-b719-11ea-9458-ccf9b86a778b.png)
|
309
|
+
|
310
|
+
## Alternative Tools
|
311
|
+
|
312
|
+
- Adding anchor to headings
|
313
|
+
- [AnchorJS](https://www.bryanbraun.com/anchorjs/)
|
314
|
+
- Generating TOC for kramdown content
|
315
|
+
- [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))
|