jekyll_outline 1.2.0 → 1.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f19cd3e8a114d272e1a25858375c4f9cae27be24c8c7df0794340efc43311cf4
-  data.tar.gz: 2c9502f7e10ed8bcdf992b4f7761a597c16d154c4f7889b130ee72d4197ee9ab
+  metadata.gz: b279fb946cc9cd5d5fc092680a1f28c2af772dc2daa319a4d3c82f4946d5c731
+  data.tar.gz: 0e1f714175edd37e7b06f07f499891d365dbb2ed01d2fe90923a54d6cac613b2
 SHA512:
-  metadata.gz: cd40905342095e621420f8255ab6b59e935559d2b7c744ac6c474dd47c993eaf3a4cd79ac3c0a2983977690485b5feb108aff6b2f222ac6a9ad26523cde88790
-  data.tar.gz: 4dde939dffacc17793cb972adec4bf4efaf17fff24251592e517efcb6f8f68823322ade76df90dd55aa29e50d15fa673afc9e13e623a2adf088181d6d263c32b
+  metadata.gz: 4811c7012c0ab9fc504906886a29b4e27d83073f2a079d1cc7e1c9dcdec25acc14da1559e0b940556ba994e2edba45cfb510866c205829d92085a5fd936a02e2
+  data.tar.gz: b79734ebe03d8facc9034e6be26bacf038609f74b9cfca6611297f16f90891f8c12dc9a88c3b6e82d00d8656f4ba24dd33ec2d46ccefa5173fa05f750b061948

data/.rubocop.yml

@@ -1,16 +1,17 @@
 require:
- - rubocop-md
- - rubocop-performance
- - rubocop-rake
- - rubocop-rspec
+  # - rubocop-jekyll
+  - rubocop-md
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-rspec
 
 AllCops:
   Exclude:
-    - exe/**/*
+    - binstub/**/*
+    - demo/_site/*
     - vendor/**/*
     - Gemfile*
   NewCops: enable
-  TargetRubyVersion: 2.6
 
 Gemspec/DeprecatedAttributeAssignment:
   Enabled: false
@@ -18,6 +19,9 @@ Gemspec/DeprecatedAttributeAssignment:
 Gemspec/RequireMFA:
   Enabled: false
 
+Gemspec/RequiredRubyVersion:
+  Enabled: false
+
 Layout/HashAlignment:
   EnforcedColonStyle: table
   EnforcedHashRocketStyle: table
@@ -26,25 +30,45 @@ Layout/LineLength:
   Max: 150
 
 Metrics/AbcSize:
-  Max: 30
+  Max: 55
 
 Metrics/BlockLength:
   Exclude:
-    - jekyll_outline.gemspec
-  Max: 40
+    - jekyll_plugin_support.gemspec
+  Max: 30
 
 Metrics/CyclomaticComplexity:
-  Max: 20
+  Max: 25
 
 Metrics/MethodLength:
-  Max: 30
+  Max: 50
 
 Metrics/PerceivedComplexity:
-  Max: 20
+  Max: 25
 
 Naming/FileName:
   Exclude:
     - Rakefile
+    - "*.md"
+
+RSpec/ExampleLength:
+  Max: 30
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+  IgnoreMethods: true
+
+RSpec/SpecFilePathSuffix:
+  Enabled: false
+
+RSpec/IndexedLet:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Max: 15
+
+Style/ClassVars:
+  Enabled: false
 
 Style/Documentation:
   Enabled: false
@@ -52,9 +76,8 @@ Style/Documentation:
 Style/FrozenStringLiteralComment:
   Enabled: false
 
+Style/StringConcatenation:
+  Enabled: false
+
 Style/TrailingCommaInHashLiteral:
   EnforcedStyleForMultiline: comma
-
-RSpec/FilePath:
-  IgnoreMethods: true
-  SpecSuffixOnly: true

data/CHANGELOG.md

@@ -1,20 +1,49 @@
+# Change Log
+
+## 1.2.3 / 2024-07-23
+
+* Made compatible with jekyll_plugin_support v1.0.0
+
+
+## 1.2.2 / 2024-01-08
+
+* Added `sort_by_title` keyword option.
+
+
+## 1.2.1 / 2023-06-17
+
+* Updated dependencies.
+* No longer explodes when a value for `order` is not provided in front matter.
+
+
 ## 1.2.0 / 2023-04-23
-  - Added optional `field` parameter.
+
+* Added optional `field` parameter.
+
 
 ## 1.1.1 / 2023-04-02
-  * Added [`attribution` support](https://github.com/mslinn/jekyll_plugin_support#subclass-attribution).
+
+* Added [`attribution` support](https://github.com/mslinn/jekyll_plugin_support#subclass-attribution).
+
 
 ## 1.1.0 / 2023-03-14
-  * `outline_js` tag added, for including Javascript necessary to position images relating to the outline.
-  * Now generates a series of divs, instead of one big div.
-  * Now interprets numbers as decimal instead of octal.
-  * CSS documented and new `post_title` class defined.
+
+* `outline_js` tag added, for including Javascript necessary to position images relating to the outline.
+* Now generates a series of divs, instead of one big div.
+* Now interprets numbers as decimal instead of octal.
+* CSS documented and new `post_title` class defined.
+
 
 ## 1.0.2 / 2023-02-16
-  * Updated to `jekyll_plugin_support` v0.5.1
+
+* Updated to `jekyll_plugin_support` v0.5.1
+
 
 ## 1.0.1 / 2023-02-14
-  * Now dependent upon `jekyll_plugin_support`
+
+* Now dependent upon `jekyll_plugin_support`
+
 
 ## 1.0.0 / 2022-04-02
-  * Initial version, this Jekyll plugin defines a block tag called `outline`.
+
+* Initial version, this Jekyll plugin defines a block tag called `outline`.

data/README.md

@@ -1,11 +1,35 @@
-`jekyll_outline`
-[![Gem Version](https://badge.fury.io/rb/jekyll_outline.svg)](https://badge.fury.io/rb/jekyll_outline)
-===========
+# `jekyll_outline` [![Gem Version](https://badge.fury.io/rb/jekyll_outline.svg)](https://badge.fury.io/rb/jekyll_outline)
 
 `jekyll_outline` Jekyll tag plugin that creates a clickable table of contents.
 
 
+## Usage
+
+These examples are taken from [`demo/index.html`](demo/index.html).
+
+Sort by `order` field:
+
+```html
+{% outline attribution fields="<b> title </b> &ndash; <i> description </i>" stuff %}
+000: A Topic 0..19
+020: A Topic 20..39
+040: A Topic 40..
+{% endoutline %}
+```
+
+Sort by `title` field:
+
+```html
+{% outline attribution sort_by_title fields="<b> title </b> &ndash; <i> description </i>" stuff %}
+000: B Topic 0..19
+020: B Topic 20..39
+040: B Topic 40..
+{% endoutline %}
+```
+
+
 ## Installation
+
 Add the following line to your Jekyll project's Gemfile, within the `jekyll_plugins` group:
 
 ```ruby
@@ -16,20 +40,24 @@ end
 
 And then execute:
 
-    $ bundle
+```shell
+$ bundle
+```
 
 
 ## Fields
+
 By default, each displayed entry consists of a document title,
 wrapped within an &lt;a href&gt; HTML tag that links to the page for that entry,
 followed by an indication of whether the document is visible (a draft) or not.
 
 Entry can also include following fields:
-`draft`, `categories`, `description`, `date`, `last_modified` or `last_modified_at`, `layout`, `order`, `title`, `slug`, `ext`, `tags`, and `excerpt`.
+`draft`, `categories`, `description`, `date`, `last_modified` or `last_modified_at`, `layout`, `order`, `title`, `slug`,
+`ext`, `tags`, and `excerpt`.
 
 Specify the fields like this:
 
-```
+```html
 {% outline fields="title &ndash; <i> description </i>" %}
 000: Topic 0..19
 020: Topic 20..39
@@ -45,8 +73,10 @@ Tokens are separated by white space.
 
 
 ### CSS
+
 The CSS used for the demo website should be copied to your project.
-See the sections of [`demo/assets/css/styles.css`](/mslinn/jekyll_outline/blob/master/demo/assets/css/style.css#L252-L315) as shown:
+See the sections of
+[`demo/assets/css/styles.css`](/mslinn/jekyll_outline/blob/master/demo/assets/css/style.css#L252-L315) as shown:
 
 ```css
 /* Start of jekyll_plugin_support css */
@@ -59,6 +89,7 @@ See the sections of [`demo/assets/css/styles.css`](/mslinn/jekyll_outline/blob/m
 ```
 
 ### JavaScript
+
 This project's `outline_js` tag returns the Javascript necessary to position images relating to the outline.
 If used without parameters it just returns the JavaScript.
 Use the tag this way:
@@ -78,7 +109,9 @@ Use the tag this way:
 
 
 ## Explanation
+
 Given an outline that looks like this:
+
 ```html
 {% outline stuff %}
 000: Topic 0..19
@@ -89,11 +122,12 @@ Given an outline that looks like this:
 
 ...and given pages in the `stuff` collection with the following names:
 
- - `010-published.html` has title **Published Stuff Post 010**
- - `020-unpublished.html` has title **Unpublished Post 020**
- - `030-unpublished.html` has title **Unpublished Post 030**
+- `010-published.html` has title **Published Stuff Post 010**
+- `020-unpublished.html` has title **Unpublished Post 020**
+- `030-unpublished.html` has title **Unpublished Post 030**
 
 Then links to the pages in the `stuff` collection's pages are interleaved into the generated outline like this:
+
 ```html
 <div class="outer_posts">
   <h3 class='post_title clear' id="title_0">Topic 0..19</h3>
@@ -121,6 +155,7 @@ Note that leading zeros in the first column above are not present in the `id`s b
 
 If you want to provide images to embed at appropriate locations within the outline,
 wrap them within an invisible `div` so the web page does not jump around as the images are loaded.
+
 ```html
 <div style="display: none;">
 {% img align="right"
@@ -146,30 +181,34 @@ wrap them within an invisible `div` so the web page does not jump around as the
 %}
 </div>
 ```
+
 The JavaScript identifies the images and repositions them in the DOM such that they follow the appropriate heading.
 If no image corresponds to a heading, no error or warning is generated.
 The images can be located anywhere on the page; they will be relocated appropriately.
 If an image does not correspond to a heading, it is deleted.
 
 
-
-
 ## Attribution
+
 See [`jekyll_plugin_support` for `attribution`](https://github.com/mslinn/jekyll_plugin_support#subclass-attribution)
 
 
 ## Additional Information
+
 More information is available on
 [Mike Slinn&rsquo;s website](https://www.mslinn.com/jekyll/3000-jekyll-plugins.html#outline).
 
 
 ## Development
+
 After checking out the repo, run `bin/setup` to install development dependencies.
 
 Then you can run `bin/console` for an interactive prompt that will allow you to experiment using `irb`.
 
 ### Build and Install Locally
+
 To build and install this gem onto your local machine, run:
+
 ```shell
 $ bundle exec rake install
 jekyll_outline 0.1.0 built to pkg/jekyll_outline-0.1.0.gem.
@@ -191,45 +230,56 @@ jekyll_outline (0.1.0)
 
 
 ## Demo
+
 A demo / test website is provided in the `demo` directory.
 It can be used to debug the plugin or to run freely.
 
+
 ### Run Freely
- 1. Run from the command line:
-    ```shell
-    $ demo/_bin/debug -r
-    ```
 
-  2. View the generated website at [`http://localhost:4444`](http://localhost:4444)
+1. Run from the command line:
+
+   ```shell
+   $ demo/_bin/debug -r
+   ```
+
+2. View the generated website at [`http://localhost:4444`](http://localhost:4444)
+
 
 ### Plugin Debugging
- 1. Set breakpoints in Visual Studio Code.
 
- 2. Initiate a debug session from the command line:
-    ```shell
-    $ demo/_bin/debug
-    ```
+1. Set breakpoints in Visual Studio Code.
 
-  3. Once the `Fast Debugger` signon appears, launch the Visual Studio Code launch
-     configuration called `Attach rdebug-ide`.
+2. Initiate a debug session from the command line:
 
-  4. View the generated website at [`http://localhost:4444`](http://localhost:4444)
+   ```shell
+   $ demo/_bin/debug
+   ```
+
+3. Once the `Fast Debugger` signon appears, launch the Visual Studio Code launch
+   configuration called `Attach rdebug-ide`.
+4. View the generated website at [`http://localhost:4444`](http://localhost:4444)
 
 
 ## Release
+
 To release a new version,
-  1. Update the version number in `version.rb`.
-  2. Describe the changes in `CHANGELOG.md`.
-  3. Commit all changes to git; if you don't the next step might fail with an unexplainable error message.
-  4. Run the following:
-     ```shell
-     $ bundle exec rake release
-     ```
-     The above creates a git tag for the version, commits the created tag,
-     and pushes the new `.gem` file to [RubyGems.org](https://rubygems.org).
+
+1. Update the version number in `version.rb`.
+2. Describe the changes in `CHANGELOG.md`.
+3. Commit all changes to git; if you don't the next step might fail with an unexplainable error message.
+4. Run the following:
+
+    ```shell
+    $ bundle exec rake release
+    ```
+
+    The above creates a git tag for the version, commits the created tag,
+    and pushes the new `.gem` file to [RubyGems.org](https://rubygems.org).
 
 
 ## Contributing
+
 Bug reports and pull requests are welcome on GitHub at https://github.com/mslinn/jekyll_outline.
 
 1. Fork the project
@@ -239,4 +289,5 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/mslinn
 
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/jekyll_outline.gemspec

@@ -35,6 +35,6 @@ Gem::Specification.new do |spec|
   spec.version = JekyllOutlineVersion::VERSION
 
   spec.add_dependency 'jekyll', '>= 3.5.0'
-  spec.add_dependency 'jekyll_draft', '~> 1.1.0'
-  spec.add_dependency 'jekyll_plugin_support', '~> 0.6.0'
+  spec.add_dependency 'jekyll_draft', '>= 1.1.2'
+  spec.add_dependency 'jekyll_plugin_support', '>= 1.0.0'
 end

data/lib/jekyll_outline/version.rb

@@ -1,3 +1,3 @@
 module JekyllOutlineVersion
-  VERSION = '1.2.0'.freeze
+  VERSION = '1.2.3'.freeze
 end

data/lib/jekyll_outline.rb

@@ -1,5 +1,5 @@
-require_relative './outline_js'
-require_relative './outline_tag'
+require_relative 'outline_js'
+require_relative 'outline_tag'
 
 module Outline
   include OutlineTag

data/lib/outline_js.rb

@@ -35,6 +35,6 @@ module OutlineJsTag
         .join("\n")
     end
 
-    JekyllPluginHelper.register(self, PLUGIN_JS_NAME)
+    ::JekyllSupport::JekyllPluginHelper.register(self, PLUGIN_JS_NAME)
   end
 end

data/lib/outline_tag.rb

@@ -6,10 +6,38 @@ require 'jekyll_plugin_support'
 require 'yaml'
 require_relative 'jekyll_outline/version'
 
+# This class generates output of the form, where NNN is an order value:
+# <div class="outer_posts">
+#   <h3 class="post_title clear" id="title_0">Django / Oscar Evaluation</h3>
+#   <div id="posts_wrapper_0" class="clearfix">
+#     <div id="posts_0" class="posts">
+#       <span>2021-02-11</span> <span><a href="/collection/page1.html">Title 1</a></span>
+#       <span>2023-12-09</span> <span><a href="/collection/page2.html">Title 2</a></span>
+#     </div>
+#     <h3 class="post_title clear" id="title_NNN">Notes</h3>
+#     <div id="posts_wrapper_NNN" class="clearfix">
+#       <div id="posts_400" class="posts">
+#         <span>2021-04-14</span> <span><a href="/collection/page3.html">Title 3</a></span>
+#         <span>2021-03-29</span> <span><a href="/collection/page4.html">Title 4</a></span>
+#       </div>
+#     </div>
+#     <div id="jps_attribute_570007" class="jps_attribute">
+#       <div>
+#         <a href="https://www.mslinn.com/jekyll_plugins/jekyll_outline.html" target="_blank" rel="nofollow">
+#           Generated by the jekyll_outline v1.2.1 Jekyll plugin, written by Mike Slinn 2024-01-09.
+#         </a>
+#       </div>
+#     </div>
+#   </div>
+# </div>
+#
+# Subclasses, such as jekyll_toc.rb, might generate other output.
+
 module OutlineTag
   PLUGIN_NAME = 'outline'.freeze
 
   # Interleaves with docs
+  # Duck type compatible with Jekyll doc
   class Header
     attr_accessor :order, :title
 
@@ -33,14 +61,18 @@ module OutlineTag
       headers = make_headers(super) # Process the block content.
 
       @helper.gem_file __FILE__
-      @fields = @helper.parameter_specified?('fields')&.split(' ') || ['title']
-      @logger.info { "@fields are: #{@fields}" }
+      @fields  = @helper.parameter_specified?('fields')&.split || ['title']
+      @sort_by = @helper.parameter_specified?('sort_by_title') ? 'title' : 'order'
       @collection_name = @helper.remaining_markup
       abort 'OutlineTag: collection_name was not specified' unless @collection_name
 
       @docs = obtain_docs(@collection_name)
       collection = headers + @docs
+      render_outline collection
+    end
 
+    # Overload this for a subclass
+    def render_outline(collection)
       <<~HEREDOC
         <div class="outer_posts">
         #{make_entries collection}
@@ -49,6 +81,8 @@ module OutlineTag
       HEREDOC
     end
 
+    def open_head; end
+
     private
 
     def header?(variable)
@@ -64,14 +98,18 @@ module OutlineTag
     # @param collection Array of Jekyll::Document and Outline::Header
     # @return Array of String
     def make_entries(collection)
-      sorted = collection.sort_by(&obtain_order)
+      sorted = if @sort_by == 'order'
+                 collection.sort_by(&obtain_order)
+               else
+                 collection.sort_by(&obtain_field)
+               end
       pruned = remove_empty_headers sorted
       @section_state = :head
       @section_id = 0
       result = pruned.map do |entry|
         handle entry
       end
-      result << "    </div>\n  </div>" if @section_state == :in_body
+      result << "    </div>\n  </div>" if @section_state == :in_body # Modify this for TOC
       result&.join("\n")
     end
 
@@ -86,14 +124,16 @@ module OutlineTag
         entry
       else
         if @section_state == :head
-          section_start = "<div id='posts_wrapper_#{@header_order}' class='clearfix'>\n    " \
-                          "<div id='posts_#{@header_order}' class='posts'>\n"
+          section_start = <<~ENDTEXT # Modify this for TOC
+            <div id="posts_wrapper_#{@header_order}" class='clearfix'>
+              <div id="posts_#{@header_order}" class='posts'>
+          ENDTEXT
         end
         @section_state = :in_body
         date = entry.data['last_modified_at'] # "%Y-%m-%d"
         draft = Jekyll::Draft.draft_html(entry)
         visible_line = handle_entry entry
-        result = "    <span>#{date}</span> <span><a href='#{entry.url}'>#{visible_line.strip}</a>#{draft}</span>"
+        result = "    <span>#{date}</span> <span><a href='#{entry.url}'>#{visible_line.strip}</a>#{draft}</span>" # Modify this for TOC
         result = section_start + result if section_start
         result
       end
@@ -133,13 +173,25 @@ module OutlineTag
         .reject { |doc| doc.path.end_with? 'index.html' }
     end
 
-    # Sort entries without an order property at the end
+    # Sort entries within the outline tag which do not have the property specified by @sort_by at the end
+    def obtain_field
+      sort_by = @sort_by.to_s
+      proc do |entry|
+        if entry.respond_to? :data # page
+          entry.data.key?(sort_by) ? entry.data[sort_by] || 'zzz' : 'zzz'
+        else # heading
+          entry.respond_to?(sort_by) ? entry.send(sort_by) || 'zzz' : 'zzz'
+        end
+      end
+    end
+
+    # Sort entries within the outline tag which do not have an order property at the end
     def obtain_order
       proc do |entry|
-        if entry.respond_to? :data
-          entry.data.key?('order') ? entry.data['order'] : FIXNUM_MAX
-        else
-          entry.order
+        if entry.respond_to? :data # page
+          entry.data.key?('order') ? entry.data['order'] || FIXNUM_MAX : FIXNUM_MAX
+        else # heading
+          entry.order || FIXNUM_MAX
         end
       end
     end
@@ -166,6 +218,6 @@ module OutlineTag
         .join("\n")
     end
 
-    JekyllPluginHelper.register(self, PLUGIN_NAME)
+    ::JekyllSupport::JekyllPluginHelper.register(self, PLUGIN_NAME)
   end
 end

data/spec/outline_spec.rb

@@ -4,10 +4,7 @@ require_relative '../lib/jekyll_outline'
 RSpec.describe(Outline) do
   include Jekyll
 
-  it 'is created properly' do
-    pending 'This is just a placeholder'
-    run_tag = RunTag.new('run', 'echo asdf')
-    output = run_tag.render(context)
-    expect(output).to eq('asdf')
+  it 'never works first time', skip: 'Just a placeholder' do
+    expect(true).to be_truthy
   end
 end

data/spec/spec_helper.rb

@@ -2,9 +2,8 @@ require 'jekyll'
 require_relative '../lib/jekyll_outline'
 
 RSpec.configure do |config|
-  config.filter_run :focus
+  config.filter_run_when_matching focus: true
   config.order = 'random'
-  config.run_all_when_everything_filtered = true
 
   # See https://relishapp.com/rspec/rspec-core/docs/command-line/only-failures
   config.example_status_persistence_file_path = 'spec/status_persistence.txt'

data/spec/status_persistence.txt

@@ -1,3 +1,3 @@
-example_id                         | status | run_time        |
----------------------------------- | ------ | --------------- |
-./spec/jekyll_outline_spec.rb[1:1] | passed | 0.00023 seconds |
+example_id                  | status  | run_time        |
+--------------------------- | ------- | --------------- |
+./spec/outline_spec.rb[1:1] | pending | 0.00001 seconds |

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_outline
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.3
 platform: ruby
 authors:
 - Mike Slinn
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-05-24 00:00:00.000000000 Z
+date: 2024-07-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -28,30 +28,30 @@ dependencies:
   name: jekyll_draft
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: 1.1.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: 1.1.2
 - !ruby/object:Gem::Dependency
   name: jekyll_plugin_support
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 1.0.0
 description: 'Jekyll tag plugin that creates a clickable table of contents.
 
   '
@@ -102,7 +102,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: Jekyll tag plugin that creates a clickable table of contents.