HTML
assert_equal(expected, doc.css('ul.custom-list').to_s)
end
end
jekyll-toc-0.13.1/test/test_kramdown_list.rb 0000644 0000041 0000041 00000006430 13615547335 021140 0 ustar www-data www-data # frozen_string_literal: true
require 'test_helper'
class TestKramdownList < Minitest::Test
# NOTE: kramdown automatically injects `id` attribute
def test_kramdown_heading
text = <<~MARKDOWN
# h1
## h2
MARKDOWN
expected = <<~HTML
h1
h2
HTML
actual = Kramdown::Document.new(text).to_html
assert_equal(expected, actual)
end
def test_japanese_heading
text = <<~MARKDOWN
# 日本語見出し１
## 日本語見出し２
MARKDOWN
expected = <<~HTML
日本語見出し１
日本語見出し２
HTML
actual = Kramdown::Document.new(text).to_html
assert_equal(expected, actual)
end
def test_kramdown_list_1
text = <<~MARKDOWN
* level-1
* level-2
* level-3
* level-4
* level-5
MARKDOWN
expected = <<~HTML
level-1
level-2
level-3
level-4
level-5
HTML
actual = Kramdown::Document.new(text).to_html
assert_equal(expected, actual)
end
def test_kramdown_list_2
text = <<~MARKDOWN
* level-1
* level-3
* level-2
* level-4
* level-5
MARKDOWN
expected = <<~HTML
level-1
level-3
level-2
level-4
level-5
HTML
actual = Kramdown::Document.new(text).to_html
assert_equal(expected, actual)
end
def test_kramdown_list_3
text = <<~MARKDOWN
* level-4
* level-3
* level-2
* level-1
MARKDOWN
expected = <<~HTML
* level-4
* level-3 * level-2 * level-1
HTML
actual = Kramdown::Document.new(text).to_html
assert_equal(expected, actual)
end
def test_kramdown_list_4
text = <<~MARKDOWN
* level-1
* level-4
* level-3
* level-2
* level-1
MARKDOWN
expected = <<~HTML
level-1
* level-4
level-3
level-2
level-1
HTML
actual = Kramdown::Document.new(text).to_html
assert_equal(expected, actual)
end
def test_kramdown_list_5
text = <<~MARKDOWN
* level-1
* level-3
* level-2
* level-1
MARKDOWN
expected = <<~HTML
level-1
level-3
level-2
level-1
HTML
actual = Kramdown::Document.new(text).to_html
assert_equal(expected, actual)
end
end
jekyll-toc-0.13.1/test/test_toc_tag.rb 0000644 0000041 0000041 00000001633 13615547335 017703 0 ustar www-data www-data # frozen_string_literal: true
require 'test_helper'
class TestTableOfContentsTag < Minitest::Test
include Liquid
def setup
@stubbed_context = Struct.new(:registers)
@stubbed_context1 = Struct.new(:config)
@stubbed_context2 = Struct.new(:toc, :content)
end
def test_toc_tag
context = @stubbed_context.new(
page: @stubbed_context2.new({ 'toc' => false }, '
HTML
module TestHelpers
def read_html_and_create_parser
@parser = Jekyll::TableOfContents::Parser.new(SIMPLE_HTML)
end
end
jekyll-toc-0.13.1/README.md 0000644 0000041 0000041 00000014247 13615547335 015204 0 ustar www-data www-data # jekyll-toc
[](http://badge.fury.io/rb/jekyll-toc)
[](https://codeclimate.com/github/toshimaru/jekyll-toc)
[](https://codeclimate.com/github/toshimaru/jekyll-toc/test_coverage)
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [1. Basic Usage](#1-basic-usage)
- [2. Advanced Usage](#2-advanced-usage)
- [Generated HTML](#generated-html)
- [Default Configuration](#default-configuration)
- [Customization](#customization)
- [TOC levels](#toc-levels)
- [Skip TOC](#skip-toc)
- [Skip TOC Section](#skip-toc-section)
- [CSS Styling](#css-styling)
- [Custom CSS Class](#custom-css-class)
## Installation
Add jekyll-toc plugin in your site's `Gemfile`, and run `bundle install`.
```ruby
gem 'jekyll-toc'
```
Add jekyll-toc to the `gems:` section in your site's `_config.yml`.
```yml
plugins:
- jekyll-toc
```
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.
### 1. 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.
### 2. 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
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
{% toc %}
{{ content }}
```
: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.
```html
{{ content | toc_only }}
{{ content | inject_anchors }}
```
#### `inject_anchors` filter
Injects HTML anchors into the content without actually outputting the TOC itself.
They are of the form:
```html
```
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. The HTML output is as follows.
```html
```
## Default Configuration
```yml
toc:
min_level: 1
max_level: 6
no_toc_section_class: no_toc_section
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
toc:
min_level: 2 # default: 1
max_level: 5 # default: 6
```
The default level range is `
` to `
`.
### Skip TOC
The heading is ignored in the toc when you add `no_toc` to the class.
```html
h1
This heading is ignored in the toc
h2
```
### Skip TOC Section
The headings are ignored inside the element which has `no_toc_section` class.
```html
h1
This heading is ignored in the toc
This heading is ignored in the toc
h4
```
Which would result in only the `
` & `
` within the example being included in the TOC.
The class can be configured on `_config.yml`:
```yml
toc:
no_toc_section_class: exclude # default: no_toc_section
```
Configuring multiple classes for `no_toc_section_class` is allowed:
```yml
toc:
no_toc_section_class:
- no_toc_section
- exclude
- your_custom_skip_class_name
```
### 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;
}
```
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 `
...
` (a single
`#` in Markdown) will get the CSS class `toc-h1`.
### Custom CSS Class
You can apply custom CSS classes to the generated `
` and `
` tags.
```yml
toc:
# Default is "section-nav":
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-
```
jekyll-toc-0.13.1/gemfiles/ 0000755 0000041 0000041 00000000000 13615547335 015510 5 ustar www-data www-data jekyll-toc-0.13.1/gemfiles/jekyll_3.8.gemfile 0000644 0000041 0000041 00000000333 13615547335 020723 0 ustar www-data www-data # This file was generated by Appraisal
source "https://rubygems.org"
gem "appraisal"
gem "minitest-reporters"
gem "minitest"
gem "pry"
gem "rake"
gem "rubocop"
gem "simplecov"
gem "jekyll", "3.8"
gemspec path: "../"
jekyll-toc-0.13.1/gemfiles/jekyll_4.0.gemfile 0000644 0000041 0000041 00000000333 13615547335 020714 0 ustar www-data www-data # This file was generated by Appraisal
source "https://rubygems.org"
gem "appraisal"
gem "minitest-reporters"
gem "minitest"
gem "pry"
gem "rake"
gem "rubocop"
gem "simplecov"
gem "jekyll", "4.0"
gemspec path: "../"
jekyll-toc-0.13.1/gemfiles/jekyll_3.7.gemfile 0000644 0000041 0000041 00000000333 13615547335 020722 0 ustar www-data www-data # This file was generated by Appraisal
source "https://rubygems.org"
gem "appraisal"
gem "minitest-reporters"
gem "minitest"
gem "pry"
gem "rake"
gem "rubocop"
gem "simplecov"
gem "jekyll", "3.7"
gemspec path: "../"
jekyll-toc-0.13.1/LICENSE.md 0000644 0000041 0000041 00000002064 13615547335 015323 0 ustar www-data www-data The MIT License (MIT)
Copyright (c) 2020 Toshimaru
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.
jekyll-toc-0.13.1/CHANGELOG.md 0000644 0000041 0000041 00000000143 13615547335 015524 0 ustar www-data www-data Changelog is maintained under [Github Releases](https://github.com/toshimaru/jekyll-toc/releases).
jekyll-toc-0.13.1/jekyll-toc.gemspec 0000644 0000041 0000041 00000001573 13615547335 017345 0 ustar www-data www-data # frozen_string_literal: true
lib = File.expand_path('../lib', __FILE__)
$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
require 'version'
Gem::Specification.new do |spec|
spec.name = 'jekyll-toc'
spec.version = JekyllToc::VERSION
spec.summary = 'Jekyll Table of Contents plugin'
spec.description = 'Jekyll (Ruby static website generator) plugin which generates a table of contents.'
spec.authors = %w(toshimaru torbjoernk)
spec.email = 'me@toshimaru.net'
spec.files = `git ls-files -z`.split("\x0")
spec.homepage = 'https://github.com/toshimaru/jekyll-toc'
spec.license = 'MIT'
spec.test_files = spec.files.grep(%r{^(test|spec|features)/})
spec.require_paths = ['lib']
spec.required_ruby_version = '>= 2.4'
spec.add_dependency 'jekyll', '>= 3.7'
spec.add_dependency 'nokogiri', '~> 1.9'
end
jekyll-toc-0.13.1/.rubocop.yml 0000644 0000041 0000041 00000000601 13615547335 016164 0 ustar www-data www-data AllCops:
TargetRubyVersion: 2.4
Exclude:
- '*.gemspec'
- 'gemfiles/*'
- Rakefile
- Gemfile
Metrics/MethodLength:
Enabled: false
Metrics/AbcSize:
Enabled: false
Metrics/ClassLength:
Enabled: false
Style/BracesAroundHashParameters:
Enabled: false
Style/WordArray:
Enabled: false
Naming/FileName:
Enabled: false
Layout/LineLength:
Enabled: false
jekyll-toc-0.13.1/Appraisals 0000644 0000041 0000041 00000000272 13615547335 015740 0 ustar www-data www-data # frozen_string_literal: true
appraise 'jekyll-4.0' do
gem 'jekyll', '4.0'
end
appraise 'jekyll-3.8' do
gem 'jekyll', '3.8'
end
appraise 'jekyll-3.7' do
gem 'jekyll', '3.7'
end
jekyll-toc-0.13.1/.gitignore 0000644 0000041 0000041 00000000067 13615547335 015710 0 ustar www-data www-data *.gem
/Gemfile.lock
/.bundle/
/coverage
*.gemfile.lock
jekyll-toc-0.13.1/Rakefile 0000644 0000041 0000041 00000000321 13615547335 015356 0 ustar www-data www-data 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
jekyll-toc-0.13.1/lib/ 0000755 0000041 0000041 00000000000 13615547335 014463 5 ustar www-data www-data jekyll-toc-0.13.1/lib/version.rb 0000644 0000041 0000041 00000000111 13615547335 016466 0 ustar www-data www-data # frozen_string_literal: true
module JekyllToc
VERSION = '0.13.1'
end
jekyll-toc-0.13.1/lib/jekyll-toc.rb 0000644 0000041 0000041 00000002456 13615547335 017074 0 ustar www-data www-data # 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 = context.registers[:site].config['toc'] || {}
TableOfContents::Parser.new(content_html, toc_config).build_toc
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
@context.registers[:site].config['toc'] || {}
end
end
end
Liquid::Template.register_filter(Jekyll::TableOfContentsFilter)
Liquid::Template.register_tag('toc', Jekyll::TocTag) # will be enabled at v1.0
jekyll-toc-0.13.1/lib/table_of_contents/ 0000755 0000041 0000041 00000000000 13615547335 020153 5 ustar www-data www-data jekyll-toc-0.13.1/lib/table_of_contents/configuration.rb 0000644 0000041 0000041 00000002215 13615547335 023347 0 ustar www-data www-data # frozen_string_literal: true
module Jekyll
module TableOfContents
# jekyll-toc configuration class
class Configuration
attr_accessor :toc_levels, :no_toc_class, :no_toc_section_class,
:list_class, :sublist_class, :item_class, :item_prefix
DEFAULT_CONFIG = {
'min_level' => 1,
'max_level' => 6,
'no_toc_section_class' => 'no_toc_section',
'list_class' => 'section-nav',
'sublist_class' => '',
'item_class' => 'toc-entry',
'item_prefix' => 'toc-'
}.freeze
def initialize(options)
options = generate_option_hash(options)
@toc_levels = options['min_level']..options['max_level']
@no_toc_class = 'no_toc'
@no_toc_section_class = options['no_toc_section_class']
@list_class = options['list_class']
@sublist_class = options['sublist_class']
@item_class = options['item_class']
@item_prefix = options['item_prefix']
end
private
def generate_option_hash(options)
DEFAULT_CONFIG.merge(options)
rescue TypeError
DEFAULT_CONFIG
end
end
end
end
jekyll-toc-0.13.1/lib/table_of_contents/parser.rb 0000644 0000041 0000041 00000010524 13615547335 021776 0 ustar www-data www-data # frozen_string_literal: true
module Jekyll
module TableOfContents
# Parse html contents and generate table of contents
class Parser
PUNCTUATION_REGEXP = /[^\p{Word}\- ]/u.freeze
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
%(
\n#{build_toc_list(@entries)}
)
end
def inject_anchors_into_html
@entries.each do |entry|
entry[:header_content].add_previous_sibling(
%()
)
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 = node.text
id = node.attribute('id') || text
.downcase
.gsub(PUNCTUATION_REGEXP, '') # remove punctuation
.tr(' ', '-') # replace spaces with dash
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)
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
toc_list << %(
#{entry[:text]})
# If the next entry should be indented in the list, generate a sublist
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\n#{build_toc_list(nest_entries)}
\n)
i += nest_entries.count
end
# Add the closing tag for the current entry in the list
toc_list << %(\n)
elsif entry[:h_num] > min_h_num
# If the current entry should be indented in the list, generate a sublist
nest_entries = get_nest_entries(entries[i, entries.count], min_h_num)
toc_list << build_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
end
end
end
jekyll-toc-0.13.1/Gemfile 0000644 0000041 0000041 00000000223 13615547335 015205 0 ustar www-data www-data source 'https://rubygems.org'
gemspec
gem 'appraisal'
gem 'minitest-reporters'
gem 'minitest'
gem 'pry'
gem 'rake'
gem 'rubocop'
gem 'simplecov'
jekyll-toc-0.13.1/.github/ 0000755 0000041 0000041 00000000000 13615547335 015255 5 ustar www-data www-data jekyll-toc-0.13.1/.github/workflows/ 0000755 0000041 0000041 00000000000 13615547335 017312 5 ustar www-data www-data jekyll-toc-0.13.1/.github/workflows/coverage.yml 0000644 0000041 0000041 00000001100 13615547335 021620 0 ustar www-data www-data name: Coverage
on: [push]
jobs:
build:
strategy:
matrix:
ruby: [2.6]
runs-on: ubuntu-latest
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
jekyll-toc-0.13.1/.github/workflows/ci.yml 0000644 0000041 0000041 00000001335 13615547335 020432 0 ustar www-data www-data name: CI
on: [push]
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
exclude:
- ruby: 2.4
gemfile: gemfiles/jekyll_4.0.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
with:
ruby-version: ${{ matrix.ruby }}
- name: bundle install
run: |
gem install bundler
bundle install --jobs 4 --retry 3
- name: Run Test
run: bundle exec rake
jekyll-toc-0.13.1/.github/workflows/rubocop.yml 0000644 0000041 0000041 00000000647 13615547335 021515 0 ustar www-data www-data name: RuboCop
on: [push]
jobs:
build:
strategy:
matrix:
ruby: [2.6]
runs-on: ubuntu-latest
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