jekyll-toc 0.0.4 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7a6987cd0c0489041a425e9da09b74af6847e148
-  data.tar.gz: 0eee9d6b1ed1eb887fea59a9f5f489a663d8bc8b
+  metadata.gz: d5182d04d94e419e33025caaa66a64d016d1db78
+  data.tar.gz: 131cf0a03478c80523fc94bca791dc4e1e0424a8
 SHA512:
-  metadata.gz: be71a8215c97908a15d25a167753c9e66fd0d13a9f7663acdb3b26255fc26a5d0cfdc57f33923d35150d4ba3c5eda37aeb4fcc1c374a3f7f5dd0da81e3cc97e7
-  data.tar.gz: e28a6858a6d61be4f5fddb87374173861097983826d470ffbfaad5e79b71dcb5194d9a6954231664db0ee9632931bd1b2c52edfacccb2528ebdcff088972f0fd
+  metadata.gz: 267d7551a141b3007950892e24d618a869a48af010c9d912cd62d940e21d439a0f3df2fa1f78c67c9a0a353f7a7e975da9fdcdc484058e5f4f6651e1076233d7
+  data.tar.gz: c399807b95bf22b474184677296a973c1909cc89a322e0b416b11797f4ec09a0d9321e3cec4b3e9fe3959fe297c287ff5e6be2640c86f8a514cc5d92ba1c7301

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+  - 2.0
+  - 2.1
+  - 2.2
+gemfile:
+  - gemfiles/jekyll_3.1.gemfile
+  - gemfiles/jekyll_3.gemfile
+  - gemfiles/jekyll_2.gemfile

data/Appraisals

@@ -0,0 +1,11 @@
+appraise "jekyll-3.1" do
+  gem "jekyll", "3.1.2"
+end
+
+appraise "jekyll-3" do
+  gem "jekyll", "3.0.3"
+end
+
+appraise "jekyll-2" do
+  gem "jekyll", "2.5.3"
+end

data/Gemfile

@@ -1,4 +1,3 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in ruboty.gemspec
 gemspec

data/README.md

@@ -1,5 +1,6 @@
 # jekyll-toc
 
+[![Build Status](https://travis-ci.org/toshimaru/jekyll-toc.svg?branch=master)](https://travis-ci.org/toshimaru/jekyll-toc)
 [![Gem Version](https://badge.fury.io/rb/jekyll-toc.svg)](http://badge.fury.io/rb/jekyll-toc)
 [![Dependency Status](https://gemnasium.com/toshimaru/jekyll-toc.svg)](https://gemnasium.com/toshimaru/jekyll-toc)
 [![Code Climate](https://codeclimate.com/github/toshimaru/jekyll-toc/badges/gpa.svg)](https://codeclimate.com/github/toshimaru/jekyll-toc)
@@ -19,12 +20,6 @@ gems:
   - jekyll-toc
 ```
 
-Add `toc` filter to your site's `{{ content }}` (e.g. `_layouts/post.html`).
-
-```
-{{ content | toc }}
-```
-
 Set `toc: true` in your posts.
 
 ```yml
@@ -35,17 +30,51 @@ toc: true
 ---
 ```
 
+There are three Liquid filters available now, which all should be applied
+to some HTML content, e.g. the Liquid variable `content` available in
+Jekyll's templates.
+
+1. `toc_only`  
+   Generates the TOC itself as described [below](#generated-table-of-contents-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.
+
+2. `inject_anchors`  
+   Injects HTML anchors into the content without actually outputing the
+   TOC itself.
+   They are of the form:
+   
+   ```html
+   <a id="heading11" 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.
+
+3. `toc`  
+  This is the concatenation of the two above, where the TOC is placed
+  directly above the content.
+  
+  Add `toc` filter to your site's `{{ content }}` (e.g. `_layouts/post.html`).
+
+  ```
+  {{ content | toc }}
+  ```
+
+
 ## Generated Table of Contents HTML
 
 jekyll-toc generates Unordered List. The final output is as follows.
 
 ```html
 <ul class="section-nav">
-  <li><a href="#heading1">Heading.1</a></li>
-  <li><a href="#heading2-1">Heading.2-1</a></li>
-  <li><a href="#heading2-2">Heading.2-2</a></li>
-  <li><a href="#heading3">Heading.3</a></li>
-  <li><a href="#heading2-3">Heading.2-3</a></li>
+  <li class="toc-entry toc-h1"><a href="#heading1">Heading.1</a></li>
+  <li class="toc-entry toc-h2"><a href="#heading2-1">Heading.2-1</a></li>
+  <li class="toc-entry toc-h2"><a href="#heading2-2">Heading.2-2</a></li>
+  <li class="toc-entry toc-h3"><a href="#heading3">Heading.3</a></li>
+  <li class="toc-entry toc-h2"><a href="#heading2-3">Heading.2-3</a></li>
 </ul>
 ```
 
@@ -69,8 +98,28 @@ The toc can be modified with CSS. The sample CSS is the following.
 
 ![screenshot](https://cloud.githubusercontent.com/assets/803398/5723662/f0bc84c8-9b88-11e4-986c-90608ca88184.png)
 
-## TODO
-* Test
-* Travis CI
-* Coverage & Coverall
-* Close toc with JavaScript
+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`.
+
+That way, one can tune the depth of the TOC displayed on the site.  
+The following CSS will display only the first two heading levels and hides
+all other links:
+
+```css
+.toc-entry.toc-h1,
+.toc-entry.toc-h2
+{}
+.toc-entry.toc-h3,
+.toc-entry.toc-h4,
+.toc-entry.toc-h5,
+.toc-entry.toc-h6
+{
+  display: none;
+}
+```
+

data/gemfiles/jekyll_2.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "jekyll", "2.5.3"
+
+gemspec :path => "../"

data/gemfiles/jekyll_3.1.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "jekyll", "3.1.2"
+
+gemspec :path => "../"

data/gemfiles/jekyll_3.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "jekyll", "3.0.3"
+
+gemspec :path => "../"

data/jekyll-toc.gemspec

@@ -6,8 +6,8 @@ Gem::Specification.new do |spec|
   spec.name          = 'jekyll-toc'
   spec.version       = JekyllToc::VERSION
   spec.summary       = "Jekyll Table of Contents plugin"
-  spec.description   = "Jekyll plugin which generates a table of contents at the top of the content"
-  spec.authors       = ["Toshimaru"]
+  spec.description   = "A liquid filter plugin for Jekyll which generates a table of contents."
+  spec.authors       = ["Toshimaru", 'torbjoernk']
   spec.email         = 'me@toshimaru.net'
   spec.files         = `git ls-files -z`.split("\x0")
   spec.homepage      = 'https://github.com/toshimaru/jekyll-toc'
@@ -16,6 +16,8 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_runtime_dependency "nokogiri", "~> 1.6"
+
+  spec.add_development_dependency "appraisal"
   spec.add_development_dependency 'minitest', "~> 5.0"
   spec.add_development_dependency "jekyll", "~> 2.0"
   spec.add_development_dependency "rake"

data/lib/jekyll-toc.rb

@@ -1,35 +1,90 @@
 require 'nokogiri'
 
 module Jekyll
-  # parse logic is from html-pipeline toc_filter
-  # https://github.com/jch/html-pipeline/blob/v1.1.0/lib/html/pipeline/toc_filter.rb
+  module TableOfContents
+    PUNCTUATION_REGEXP = RUBY_VERSION > '1.9' ? /[^\p{Word}\- ]/u : /[^\w\- ]/
+
+    class Parser
+      attr_reader :doc
+
+      def initialize(html)
+        @doc = Nokogiri::HTML::DocumentFragment.parse(html)
+        @entries = parse_content
+      end
+
+      def build_toc
+        toc = %Q{<ul class="section-nav">\n}
+
+        @entries.each do |entry|
+          toc << %Q{<li class="toc-entry toc-#{entry[:node_name]}"><a href="##{entry[:id]}#{entry[:uniq]}">#{entry[:text]}</a></li>\n}
+        end
+
+        toc << '</ul>'
+      end
+
+      def inject_anchors_into_html
+        @entries.each do |entry|
+          entry[:content_node].add_previous_sibling(%Q{<a id="#{entry[:id]}#{entry[:uniq]}" class="anchor" href="##{entry[:id]}#{entry[:uniq]}" aria-hidden="true"><span class="octicon octicon-link"></span></a>})
+        end
+
+        @doc.inner_html
+      end
+
+      def toc
+        build_toc + inject_anchors_into_html
+      end
+
+      # parse logic is from html-pipeline toc_filter
+      # https://github.com/jch/html-pipeline/blob/v1.1.0/lib/html/pipeline/toc_filter.rb
+      private
+      def parse_content
+        entries = []
+        headers = Hash.new(0)
+
+        @doc.css('h1, h2, h3, h4, h5, h6').each do |node|
+          text = node.text
+          id = text.downcase
+          id.gsub!(PUNCTUATION_REGEXP, '') # remove punctuation
+          id.gsub!(' ', '-') # replace spaces with dash
+
+          uniq = (headers[id] > 0) ? "-#{headers[id]}" : ''
+          headers[id] += 1
+          if header_content = node.children.first
+            entries << {
+                id: id,
+                uniq: uniq,
+                text: text,
+                node_name: node.name,
+                content_node: header_content
+            }
+          end
+        end
+
+        entries
+      end
+    end
+  end
+
   module TableOfContentsFilter
-    PUNCTUATION_REGEXP = RUBY_VERSION > "1.9" ? /[^\p{Word}\- ]/u : /[^\w\- ]/
+    def toc_only(html)
+      page = @context.registers[:page]
+      return html unless page['toc']
+
+      Jekyll::TableOfContents::Parser.new(html).build_toc
+    end
+
+    def inject_anchors(html)
+      page = @context.registers[:page]
+      return html unless page['toc']
+
+      Jekyll::TableOfContents::Parser.new(html).inject_anchors_into_html
+    end
 
     def toc(html)
       page = @context.registers[:page]
-      return html unless page["toc"]
-
-      toc = ""
-      doc = Nokogiri::HTML::DocumentFragment.parse(html)
-      headers = Hash.new(0)
-
-      doc.css('h1, h2, h3, h4, h5, h6').each do |node|
-        text = node.text
-        id = text.downcase
-        id.gsub!(PUNCTUATION_REGEXP, '') # remove punctuation
-        id.gsub!(' ', '-') # replace spaces with dash
-
-        uniq = (headers[id] > 0) ? "-#{headers[id]}" : ''
-        headers[id] += 1
-        if header_content = node.children.first
-          toc << %Q{<li><a href="##{id}#{uniq}">#{text}</a></li>\n}
-          header_content.add_previous_sibling(%Q{<a id="#{id}#{uniq}" class="anchor" href="##{id}#{uniq}" aria-hidden="true"><span class="octicon octicon-link"></span></a>})
-        end
-      end
-      toc = %Q{<ul class="section-nav">\n#{toc}</ul>} unless toc.empty?
+      return html unless page['toc']
 
-      toc + doc.inner_html
+      Jekyll::TableOfContents::Parser.new(html).toc
     end
   end
 end

data/lib/version.rb

@@ -1,3 +1,3 @@
 module JekyllToc
-  VERSION = "0.0.4"
+  VERSION = '0.1.0'
 end

data/test/test_helper.rb

@@ -1,2 +1,18 @@
 require 'jekyll'
 require 'minitest/autorun'
+
+SIMPLE_HTML = <<EOL
+<h1>Simple H1</h1>
+<h2>Simple H2</h2>
+<h3>Simple H3</h3>
+<h4>Simple H4</h4>
+<h5>Simple H5</h5>
+<h6>Simple H6</h6>
+EOL
+
+module TestHelpers
+  def read_html_and_create_parser
+    @parser = Jekyll::TableOfContents::Parser.new(SIMPLE_HTML)
+    assert_match /Simple H1/, @parser.doc.inner_html
+  end
+end

data/test/test_inject_anchors_filter.rb

@@ -0,0 +1,23 @@
+require 'test_helper'
+require_relative '../lib/jekyll-toc'
+
+
+class TestTOCOnlyFilter < Minitest::Test
+  include TestHelpers
+
+  def setup
+    read_html_and_create_parser
+  end
+
+  def test_injects_anchors_into_content
+    html = @parser.inject_anchors_into_html
+
+    assert_match /<a id="simple\-h1" class="anchor" href="#simple\-h1" aria\-hidden="true"><span.*span><\/a>Simple H1/, html
+  end
+
+  def test_does_not_inject_toc
+    html = @parser.inject_anchors_into_html
+
+    assert_nil /<ul class="section-nav">/ =~ html
+  end
+end

data/test/test_toc_filter.rb

@@ -0,0 +1,23 @@
+require 'test_helper'
+require_relative '../lib/jekyll-toc'
+
+
+class TestTOCFilter < Minitest::Test
+  include TestHelpers
+
+  def setup
+    read_html_and_create_parser
+  end
+
+  def test_injects_anchors
+    html = @parser.toc
+
+    assert_match /<a id="simple\-h1" class="anchor" href="#simple\-h1" aria\-hidden="true"><span.*span><\/a>Simple H1/, html
+  end
+
+  def test_injects_toc_container
+    html = @parser.toc
+
+    assert_match /<ul class="section-nav">/, html
+  end
+end

data/test/test_toc_only_filter.rb

@@ -0,0 +1,23 @@
+require 'test_helper'
+require_relative '../lib/jekyll-toc'
+
+
+class TestTOCOnlyFilter < Minitest::Test
+  include TestHelpers
+
+  def setup
+    read_html_and_create_parser
+  end
+
+  def test_injects_toc_container
+    html = @parser.build_toc
+
+    assert_match /<ul class="section-nav">/, html
+  end
+
+  def test_does_not_return_content
+    html = @parser.build_toc
+
+    assert_nil /<h1>Simple H1<\/h1>/ =~ html
+  end
+end

metadata

@@ -1,14 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-toc
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.1.0
 platform: ruby
 authors:
 - Toshimaru
+- torbjoernk
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-18 00:00:00.000000000 Z
+date: 2016-03-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
@@ -24,6 +25,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -66,21 +81,29 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Jekyll plugin which generates a table of contents at the top of the content
+description: A liquid filter plugin for Jekyll which generates a table of contents.
 email: me@toshimaru.net
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".travis.yml"
+- Appraisals
 - Gemfile
 - LICENSE.md
 - README.md
 - Rakefile
+- gemfiles/jekyll_2.gemfile
+- gemfiles/jekyll_3.1.gemfile
+- gemfiles/jekyll_3.gemfile
 - jekyll-toc.gemspec
 - lib/jekyll-toc.rb
 - lib/version.rb
 - test/test_helper.rb
+- test/test_inject_anchors_filter.rb
+- test/test_toc_filter.rb
+- test/test_toc_only_filter.rb
 homepage: https://github.com/toshimaru/jekyll-toc
 licenses:
 - MIT
@@ -101,9 +124,12 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.4
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: Jekyll Table of Contents plugin
 test_files:
 - test/test_helper.rb
+- test/test_inject_anchors_filter.rb
+- test/test_toc_filter.rb
+- test/test_toc_only_filter.rb