jekyll_outline 1.2.5 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a31ba9e3b1f1b0962f5ac28695f41b2594acde555195fdcbbf0460fa220be66e
-  data.tar.gz: bdd1e6536607a24271019aa3cc24e5de35e71b1ac4c61b925f286bb41dd5521c
+  metadata.gz: 88b2d41ecbd19787d53682b396bd2bbf9eabccf2ffa366026f4792079c3f827e
+  data.tar.gz: 44b1fbda200ea5c9a836538fc2f8e3565bef880b1dec9a77bedec513ef15f028
 SHA512:
-  metadata.gz: e815455631865429afb66cfffce54187e4696e0ecb7e3571050ab98fa6991bd679791a212cdc9915b4e9a9d0c199bf6af0ca9d77a09babe89d7d5fa83a88fa4d
-  data.tar.gz: bcc3910b01ca8d3c99ed101764350f17c95826f3b375733215f35659a6027605452881b528197709d1143b576c7c52cf2b51aad3971c1781b03b97c414f8d1dc
+  metadata.gz: 5d432be906fbe832e4db55e2333c969b7b9beda06b7c391a5f43b6cd13771646cd285847d13510678adc548db642fa3f3eb3d7521737d9e0b1f48f28eaffd991
+  data.tar.gz: 056b5a89bdbb45d9f56016f1fd17be96c7d7a6e000c5cefbfecad28c496e540c60bcf712a024107aa34e789f59dbefdcd09d9a096077e7955ea852ae3176c41d

data/.rubocop.yml

@@ -1,4 +1,4 @@
-require:
+plugins:
   # - rubocop-jekyll
   - rubocop-md
   - rubocop-performance
@@ -37,12 +37,18 @@ Metrics/BlockLength:
     - jekyll_plugin_support.gemspec
   Max: 30
 
+Metrics/ClassLength:
+  Max: 150
+
 Metrics/CyclomaticComplexity:
   Max: 25
 
 Metrics/MethodLength:
   Max: 50
 
+Metrics/ParameterLists:
+  Enabled: false
+
 Metrics/PerceivedComplexity:
   Max: 25
 

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Change Log
 
+## 1.3.0 / 2025-06-04
+
+* Now relies on `jekyll_plugin_support` v3.1.0.
+* Fixed missing </div>s.
+* Reimplemented using nested classes, concluding with a call `to_s`
+  instead of implementing crazy nesting tracking.
+* The `fields` parameter was renamed to `pattern`, however for compatibility, both parameter names are accepted.
+  If both are provided, `pattern` has priority.
+
+
+## 1.2.6 / 2025-01-03
+
+* Added `exclude_from_outline` optional front matter YAML element.
+* Ignores all files named `index`, regardless of file type.
+
+
 ## 1.2.5 / 2024-08-20
 
 * Added configurable error handling

data/README.md

@@ -3,14 +3,194 @@
 `jekyll_outline` Jekyll tag plugin that creates a clickable table of contents.
 
 
+## Order
+
+This plugin requires every page in a collection to have an entry for
+<code>order</code> in its front matter.
+The value of <code>order</code> must be an integer.
+This entry is normally used for sorting the pages.
+
+The front matter for [this page](https://mslinn.com/jekyll_plugins/jekyll_outline.html) is:
+
+```yaml
+---
+categories: [Jekyll]
+date: 2020-10-03
+description: "Organizes the index of a collection into chapters."
+last_modified_at: 2025-01-09
+layout: jekyll
+order: 100
+title: <span class="code">jekyll_outline</span>
+---
+```
+
+
+## Examples
+
+You can see this plugin in action in most of the index pages of [`mslinn.com`](https://mslinn.com).
+Following is the source for two of them:
+
+### [Django / Oscar](https://mslinn.com/django/index.html)
+
+This is the simplest possible outline, without images.
+
+```text
+{% outline attribution django %}
+0: Django / Oscar Evaluation
+400: Notes
+800: Digging Deeper
+1900: Debugging
+2700: Production
+{% endoutline %}
+```
+
+### [A/V Studio Technology](https://mslinn.com/av_studio/index.html)
+
+This outline features images associated with specific entries.
+
+```html
+{% outline attribution av_studio %}
+0: Production Infrastructure
+150: Audio
+200: Video
+300: RME TotalMix
+400: OBS Studio
+500: Pro Tools
+550: Ableton Live &amp; Push
+600: Other Music Software
+700: MIDI Hardware &amp; Software
+800: Davinci Resolve
+1000: Computer Analysis
+2000: Music Theory
+3000: Business
+4000: General
+{% endoutline %}
+
+<div style="display: none">
+  {% img
+    align="right"
+    class=""
+    id="outline_150"
+    src="/av_studio/images/everse8/everse8d.webp"
+    size="eighthsize"
+    style="margin-top: 0"
+    wrapper_class="clear"
+  %}
+  {% img
+    align="right"
+    class=""
+    id="outline_200"
+    src="./images/equipment/sony_a7iii/sony_a7iii.webp"
+    size="eighthsize"
+    style="margin-top: 0"
+    wrapper_class="clear"
+  %}
+  {% img
+    align="right"
+    class=""
+    id="outline_300"
+    src="./images/rme/rme_logo.webp"
+    size="eighthsize"
+    style="margin-top: 0"
+    wrapper_class="clear"
+  %}
+  {% img
+    align="right"
+    class=""
+    id="outline_400"
+    src="./images/obsStudio/obs_logo.webp"
+    size="eighthsize"
+    style="margin-top: 0"
+    wrapper_class="clear"
+  %}
+  {% img
+    align="right"
+    class=""
+    id="outline_500"
+    src="./images/proTools/proToolsLogo.webp"
+    size="eighthsize"
+    style="margin-top: 0"
+    wrapper_class="clear"
+  %}
+  {% img
+    align="right"
+    class=""
+    id="outline_550"
+    src="./images/ableton/ableton_live_logo.webp"
+    size="eighthsize"
+    style="margin-top: 0"
+    wrapper_class="clear"
+  %}
+  {% img
+    align="right"
+    class="rounded"
+    id="outline_600"
+    src="./images/music21.webp"
+    size="eighthsize"
+    style="margin-top: 0"
+    wrapper_class="clear"
+  %}
+  {% img
+    align="right"
+    class=""
+    id="outline_700"
+    src="./images/midi/MIDI_logo.webp"
+    size="eighthsize"
+    style="margin-top: 0"
+    wrapper_class="clear"
+  %}
+  {% img
+    align="right"
+    class=""
+    id="outline_800"
+    src="./images/davinci_resolve/daVinci_resolve_logo.webp"
+    size="eighthsize"
+    style="margin-top: 0"
+    wrapper_class="clear"
+  %}
+  {% img
+    align="right"
+    class="rounded"
+    id="outline_2000"
+    src="./images/music_theory.webp"
+    size="eighthsize"
+    style="margin-top: 0"
+    wrapper_class="clear"
+  %}
+  {% img
+    align="right"
+    class=""
+    id="outline_4000"
+    src="./images/handsfree/pageflip_firefly.webp"
+    size="eighthsize"
+    style="margin-top: 0"
+    wrapper_class="clear"
+  %}
+</div>
+
+{% outline_js wrap_in_script_tag %}
+```
+
+
 ## Usage
 
-These examples are taken from [`demo/index.html`](demo/index.html).
+All files in a collection are included in the outline,
+except for those whose name starts with `index`,
+and those with the following in their front matter:
+
+```yaml
+exclude_from_outline: true
+```
+
+Note that Jekyll requires all documents in a collection to have a value for `order` in their front matter.
+This value is ignored by `outline_tag` if `exclude_from_outline` has a truthy value.
 
-Sort by `order` field:
+The following examples are taken from [`demo/index.html`](demo/index.html).
+
+Sort by the `order` field:
 
 ```html
-{% outline attribution fields="<b> title </b> &ndash; <i> description </i>" stuff %}
+{% outline attribution pattern="<b> title </b> &ndash; <i> description </i>" stuff %}
 000: A Topic 0..19
 020: A Topic 20..39
 040: A Topic 40..
@@ -20,7 +200,7 @@ Sort by `order` field:
 Sort by `title` field:
 
 ```html
-{% outline attribution sort_by_title fields="<b> title </b> &ndash; <i> description </i>" stuff %}
+{% outline attribution sort_by_title pattern="<b> title </b> &ndash; <i> description </i>" stuff %}
 000: B Topic 0..19
 020: B Topic 20..39
 040: B Topic 40..
@@ -51,21 +231,21 @@ 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:
+Entry can also include following pattern:
 `draft`, `categories`, `description`, `date`, `last_modified` or `last_modified_at`, `layout`, `order`, `title`, `slug`,
-`ext`, `tags`, and `excerpt`.
+`ext`, and `tags`.
 
-Specify the fields like this:
+Specify the pattern like this:
 
 ```html
-{% outline fields="title &ndash; <i> description </i>" %}
+{% outline pattern="title &ndash; <i> description </i>" %}
 000: Topic 0..19
 020: Topic 20..39
 040: Topic 40..
 {% endoutline %}
 ```
 
-Words that are not a known field are transcribed into the output.
+Words in the `pattern` argument that are not recognized as a field are transcribed into the output.
 
 In the above example, notice that the HTML is space delimited from the field names.
 The parser is simple and stupid: each token is matched against the known keywords.
@@ -75,21 +255,14 @@ 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 [`demo/assets/css/jekyll_outline.css`](https://github.com/mslinn/jekyll_outline/blob/master/demo/assets/css/jekyll_outline.css).
 
-```css
-/* Start of jekyll_plugin_support css */
-... copy this portion ...
-/* End of jekyll_plugin_support css */
-
-/* Start of jekyll_outline css */
-  ... copy this portion ...
-/* End of jekyll_outline css */
-```
 
 ### JavaScript
 
+Copy [`jekyll_outline.js`](https://github.com/mslinn/jekyll_outline/blob/master/demo/assets/js/jekyll_outline.js)
+to your Jekyll website's JavaScript directory.
+
 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:
@@ -153,6 +326,8 @@ and have `id`s that correspond to outline sections.
 Each of following image's `id`s have an `outline_` prefix, followed by a number, which corresponds to one of the sections.
 Note that leading zeros in the first column above are not present in the `id`s below.
 
+Headings that do not have corresponding pages are not displayed.
+
 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.
 

data/jekyll_outline.gemspec

@@ -3,8 +3,8 @@ require_relative 'lib/jekyll_outline/version'
 Gem::Specification.new do |spec|
   github = 'https://github.com/mslinn/jekyll_outline'
 
-  spec.authors = ['Mike Slinn']
-  spec.bindir = 'exe'
+  spec.authors     = ['Mike Slinn']
+  spec.bindir      = 'exe'
   spec.description = <<~END_OF_DESC
     Jekyll tag plugin that creates a clickable table of contents.
   END_OF_DESC
@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
     'demo/assets/js/jekyll_outline.js'
   ]
   spec.homepage = 'https://www.mslinn.com/jekyll_plugins/jekyll_outline.html'
-  spec.license = 'MIT'
+  spec.license  = 'MIT'
   spec.metadata = {
     'allowed_push_host' => 'https://rubygems.org',
     'bug_tracker_uri'   => "#{github}/issues",
@@ -22,19 +22,20 @@ Gem::Specification.new do |spec|
     'homepage_uri'      => spec.homepage,
     'source_code_uri'   => github,
   }
-  spec.name = 'jekyll_outline'
+  spec.name                 = 'jekyll_outline'
+  spec.platform             = Gem::Platform::RUBY
   spec.post_install_message = <<~END_MESSAGE
 
     Thanks for installing #{spec.name}!
 
   END_MESSAGE
-  spec.require_paths = ['lib']
+  spec.require_paths         = ['lib']
   spec.required_ruby_version = '>= 2.6.0'
-  spec.summary = 'Jekyll tag plugin that creates a clickable table of contents.'
-  spec.test_files = spec.files.grep(%r{^(test|spec|features)/})
-  spec.version = JekyllOutlineVersion::VERSION
+  spec.summary               = 'Jekyll tag plugin that creates a clickable table of contents.'
+  spec.test_files            = spec.files.grep(%r{^(test|spec|features)/})
+  spec.version               = JekyllOutlineVersion::VERSION
 
-  spec.add_dependency 'jekyll', '>= 3.5.0'
-  spec.add_dependency 'jekyll_draft', '>= 2.0.2'
-  spec.add_dependency 'jekyll_plugin_support', '>= 1.0.2'
+  spec.add_dependency 'jekyll', '>= 4.4.0'
+  spec.add_dependency 'jekyll_draft', '>= 3.0.0'
+  spec.add_dependency 'jekyll_plugin_support', '>= 3.1.0'
 end

data/lib/jekyll_outline/version.rb

@@ -1,3 +1,3 @@
 module JekyllOutlineVersion
-  VERSION = '1.2.5'.freeze
+  VERSION = '1.3.0'.freeze
 end

data/lib/outline_tag.rb

@@ -1,79 +1,51 @@
-# @author Copyright 2022 {https://www.mslinn.com Michael Slinn}
-
 require 'jekyll_draft'
 require 'jekyll_plugin_logger'
 require 'jekyll_plugin_support'
-require 'yaml'
 require_relative 'jekyll_outline/version'
+require_relative 'structure/outline'
+require_relative 'structure/yaml_parser'
 
-# 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.
-
+# See spec/outline_spec for an example of HTML output.
 module JekyllSupport
   PLUGIN_NAME = 'outline'.freeze
-  OutlineError = JekyllSupport.define_error
-
-  # Interleaves with docs
-  # Duck type compatible with Jekyll doc
-  class Header
-    attr_accessor :order, :title
-
-    def initialize(yaml)
-      @order = yaml[0]
-      @published = true
-      @title = yaml[1]
-    end
 
-    def to_s
-      "  <h3 class='post_title clear' id=\"title_#{@order}\">#{@title}</h3>"
-    end
-  end
+  OutlineError = JekyllSupport.define_error
 
-  class OutlineTag < JekyllBlock # rubocop:disable Metrics/ClassLength
+  class OutlineTag < JekyllBlock
     include JekyllOutlineVersion
 
-    FIXNUM_MAX = (2**((0.size * 8) - 2)) - 1
-
     def render_impl(text)
-      headers = make_headers(super) # Process the block content.
+      block_content = super # Process the block content.
 
-      @helper.gem_file __FILE__
+      @helper.gem_file __FILE__ # For attribution
 
       @die_on_outline_error = @tag_config['die_on_outline_error'] == true if @tag_config
       @pry_on_outline_error = @tag_config['pry_on_outline_error'] == true if @tag_config
 
-      @fields  = @helper.parameter_specified?('fields')&.split || ['title']
-      @sort_by = @helper.parameter_specified?('sort_by_title') ? 'title' : 'order'
-      @collection_name = @helper.remaining_markup
-      raise OutlineError, 'collection_name was not specified' unless @collection_name
-
-      @docs = obtain_docs(@collection_name)
-      collection = headers + @docs
-      render_outline collection
+      pattern = @helper.parameter_specified?('pattern')&.split ||
+                @helper.parameter_specified?('fields')&.split ||
+                ['title']
+      sort_by = @helper.parameter_specified?('sort_by_title') ? :title : :order
+      collection_name = @helper.remaining_markup
+      raise OutlineError, 'collection_name was not specified' unless collection_name
+
+      outline_options = OutlineOptions.new(
+        attribution:        @attribution,
+        collection_name:    collection_name,
+        enable_attribution: @attribution,
+        pattern:            pattern,
+        sort_by:            sort_by
+      )
+      yaml_parser = YamlParser.new outline_options, block_content
+      outline = Outline.new(outline_options: outline_options)
+      outline.add_sections yaml_parser.sections
+
+      abort "#{collection_name} is not a valid collection." unless @site.collections&.key?(collection_name)
+      docs = @site
+             .collections[collection_name]
+             .docs
+      outline.add_entries(collection_apages(docs))
+      outline.to_s
     rescue OutlineError => e # jekyll_plugin_support handles StandardError
       @logger.error { JekyllPluginHelper.remove_html_tags e.logger_message }
       binding.pry if @pry_on_outline_error # rubocop:disable Lint/Debugger
@@ -82,173 +54,16 @@ module JekyllSupport
       e.html_message
     end
 
-    # Overload this for a subclass
-    def render_outline(collection)
-      <<~HEREDOC
-        <div class="outer_posts">
-        #{make_entries collection}
-        </div>
-        #{@helper.attribute if @helper.attribution}
-      HEREDOC
-    end
-
-    def open_head; end
-
     private
 
-    def header?(variable)
-      variable.instance_of?(Header)
-    end
-
-    def make_headers(content)
-      content = remove_leading_zeros remove_leading_spaces content
-      yaml = YAML.safe_load content
-      yaml.map { |entry| Header.new entry }
-    rescue NoMethodError => e
-      raise OutlineError, <<~END_MSG
-        Invalid YAML within {% outline %} tag. The offending content was:
-
-        <pre>#{content}</pre>
-      END_MSG
-    rescue Psych::SyntaxError => e
-      msg = <<~END_MSG
-        Invalid YAML found within {% outline %} tag:<br>
-        <pre>#{e.message}</pre>
-      END_MSG
-      @logger.error { e.message }
-      raise OutlineError, msg
-    end
-
-    # @section_state can have values: :head, :in_body
-    # @param collection Array of Jekyll::Document and JekyllSupport::Header
-    # @return Array of String
-    def make_entries(collection)
-      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 # Modify this for TOC
-      result&.join("\n")
-    end
-
-    KNOWN_FIELDS = %w[draft categories description date last_modified_at layout order title slug ext tags excerpt].freeze
-
-    def handle(entry)
-      if entry.instance_of? Header
-        @header_order = entry.order
-        section_end = "  </div>\n" if @section_state == :in_body
-        @section_state = :head
-        entry = section_end + entry.to_s if section_end
-        entry
-      else
-        if @section_state == :head
-          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>" # Modify this for TOC
-        result = section_start + result if section_start
-        result
-      end
-    end
-
-    def handle_entry(entry)
-      result = ''
-      @fields.each do |field|
-        if KNOWN_FIELDS.include? field
-          if entry.data.key? field
-            result += "#{entry.data[field]} "
-          else
-            @logger.warn { "#{field} is a known field, but it was not present in entry #{entry}" }
-          end
-        else
-          result += "#{field} "
-        end
-      end
-      result
-    end
-
-    # Find the given document
-    def obtain_doc(doc_name)
-      abort "#{@collection_name} is not a valid collection." unless @site.collections.key? @collection_name
-      @site
-        .collections[@collection_name]
-        .docs
-        .find { |doc| doc.path.end_with? "#{doc_name}.html" }
-    end
-
-    # Ignores files called index.html
-    def obtain_docs(collection_name)
-      abort "#{@collection_name} is not a valid collection." unless @site.collections.key? @collection_name
-      @site
-        .collections[collection_name]
-        .docs
-        .reject { |doc| doc.path.end_with? 'index.html' }
-    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 # page
-          entry.data.key?('order') ? entry.data['order'] || FIXNUM_MAX : FIXNUM_MAX
-        else # heading
-          entry.order || FIXNUM_MAX
-        end
-      end
-    end
-
-    def remove_empty_headers(array)
-      i = 0
-      while i < array.length - 1
-        if header?(array[i]) && header?(array[i + 1])
-          array.delete_at(i)
-        else
-          i += 1
-        end
-      end
-
-      array.delete_at(array.length - 1) if header?(array.last)
-      array
-    end
-
-    def remove_leading_spaces(multiline)
-      multiline
-        .strip
-        .split("\n")
-        .map { |x| x.gsub(/\A\s+/, '') }
-        .join("\n")
-    end
-
-    def remove_leading_zeros(multiline)
-      multiline
-        .strip
-        .split("\n")
-        .map { |x| x.gsub(/(?<= |\A)0+(?=\d)/, '') }
-        .join("\n")
+    # Returns an APage for each document in the collection with the given named.
+    # Ignores files whose name starts with `index`,
+    # and those with the following in their front matter:
+    #   exclude_from_outline: true
+    def collection_apages(pages)
+      pages
+        .reject { |doc| doc.url.match(/index(.\w*)?$/) || doc.data['exclude_from_outline'] }
+        .map { |x| ::JekyllSupport::APage.new(x, 'collection') if x }
     end
 
     JekyllPluginHelper.register(self, PLUGIN_NAME)

data/lib/structure/a_page_enrichment.rb

@@ -0,0 +1,46 @@
+# Enriches JekyllSupport.APage
+module JekyllSupport
+  KNOWN_FIELDS = %w[draft categories description date last_modified_at layout order title slug ext tags excerpt].freeze
+
+  # Overrides definition from `jekyll_plugin_support`
+  class APage
+    def render_outline_apage(pattern)
+      <<~END_ENTRY
+        <span>#{@last_modified.strftime('%Y-%m-%d')}</span>
+              <span><a href='#{@url}'>#{render_entry_details pattern}</a>#{@draft}</span>
+      END_ENTRY
+    end
+
+    # @param pattern can either be a String or [String]
+    # Renders a section entry as a string
+    # Recognized tokens are looked up, otherwise they are incorporated into the output
+    # Currently spaces are the only valid delimiters; HTML tags should be tokenized even when not delimited by spaces
+    def render_entry_details(pattern)
+      result = ''
+      fields = case pattern
+               when String
+                 pattern.split
+               when Array
+                 pattern
+               else
+                 @logger.error { "Pattern is neither a String nor an Array (#{pattern})" }
+               end
+      fields.each do |field|
+        if KNOWN_FIELDS.include? field
+          if respond_to? field
+            value = send field
+            result += "#{value} "
+          elsif data.key?(field.to_sym) || data.key?(field.to_s)
+            value = data[field.to_sym] || data[field.to_s]
+            result += "#{value} "
+          else
+            @logger.warn { "'#{field}' is a known field, but it was not present in apage with url '#{@url}'." }
+          end
+        else
+          result += "#{field} "
+        end
+      end
+      result
+    end
+  end
+end

data/lib/structure/outline.rb

@@ -0,0 +1,156 @@
+require 'jekyll_plugin_support'
+require_relative 'section'
+
+module JekyllSupport
+  # @param attribution sets the attribution message
+  # @param enable_attribution causes the attribution message to be displayed if truthy
+  # @param collection_name Name of the Jekyll collection the outline is organizing
+  # @param pattern String containing keyswords and literals; interpreted and displayed when an APage is rendered as a topic entry
+  # @param sort_by Either has value :order or :title
+  class OutlineOptions
+    attr_accessor :attribution, :enable_attribution, :collection_name, :logger, :pattern, :sort_by
+
+    def initialize(
+      collection_name: '_posts',
+      attribution: '',
+      enable_attribution: false,
+      logger: PluginMetaLogger.instance.new_logger(self, PluginMetaLogger.instance.config),
+      pattern: '<b> title </b> &ndash; <i> description </i>',
+      sort_by: :order
+    )
+      @attribution = attribution
+      @enable_attribution = enable_attribution
+      @collection_name = collection_name
+      @logger = logger
+      @pattern = pattern
+      @sort_by = sort_by
+    end
+  end
+
+  class Outline
+    attr_reader :logger, :options, :sections
+
+    # Sort all entries first so they are iteratable according to the desired order.
+    # This presorts the entries for each section.
+    #
+    # If options[:sort_by] == :order then place each APage into it's appropriate section.
+    # Otherwise place all entries into one section.
+    #
+    # options[:pattern] defaults to ['title'], but might be something like
+    # ["<b>", "title", "</b>", "&ndash;", "<i>", "description", "</i>"]
+    def initialize(outline_options: OutlineOptions.new)
+      @add_sections_called = false
+      @options = outline_options
+
+      @logger = @options.logger
+      @sections = @options.sort_by == :order ? [] : [Section.new(@options, [0, ''])]
+    rescue StandardError => e
+      error_short_trace @logger, e
+    end
+
+    def add_entries(apages)
+      sorted_apages = make_entries sort apages
+      sorted_apages.each { |apage| add_apage apage }
+      self
+    end
+
+    def add_section(section)
+      return unless @options.sort_by == :order
+
+      @sections << section
+      self
+    end
+
+    def add_sections(sections)
+      sections.each { |x| add_section x }
+      @add_sections_called = true
+      self
+    end
+
+    def make_entries(docs)
+      docs.map do |doc|
+        draft = Jekyll::Draft.draft_html doc
+        JekyllSupport.apage_from(
+          date:          doc.date,
+          description:   doc.description,
+          draft:         draft,
+          last_modified: doc.last_modified,
+          order:         doc.order,
+          title:         doc.title,
+          url:           doc.url
+        )
+      end
+    end
+
+    # @param apages [APage]
+    # @return muliline String
+    def sort(apages)
+      if @options.sort_by == :order
+        apages.sort_by(&:order)
+      else
+        apages.sort_by { |apage| sort_property_value apage }
+      end
+    end
+
+    def to_s
+      return '' unless @sections&.count&.positive?
+
+      result = []
+      result << "<div class='outer_posts'>"
+      result << (@sections.map { |section| "  #{section}" })
+      result << '</div>'
+      result << @options.attribution if @options.enable_attribution
+      result.join "\n"
+    end
+
+    private
+
+    def add_apage(apage)
+      unless apage
+        raise ::OutlineError, 'add_apage called with nil apage'
+        puts
+      end
+      raise ::OutlineError, 'add_apage called without first calling add_sections' unless @add_sections_called
+
+      section = section_for apage
+      section.add_child apage
+    end
+
+    def default_sort_value(sort_by)
+      case sort_by
+      when :date, :last_modified, :last_modified_at
+        Date.today
+      else
+        ''
+      end
+    end
+
+    # Obtain sort property value from APage instance, or return a default value
+    def sort_property_value(apage)
+      sort_by = @options.sort_by.to_s
+      if apage.data.key?(sort_by)
+        apage.data[sort_by] || default_sort_value(sort_by)
+      else
+        default_sort_value(sort_by)
+      end
+    end
+
+    # Only called when entries are organized into multiple sections
+    # @param apage must have a property called `order`
+    def section_for(apage)
+      return @sections.first if @sections.count == 1
+
+      last = @sections.length - 1
+      (0..last).each do |i|
+        return @sections.last if i == last
+
+        page_order = apage.order
+        this_section = @sections[i]
+        next_section = @sections[i + 1]
+        return this_section if (page_order >= this_section.order) && (page_order < next_section.order)
+      end
+      @sections.last
+      # raise OutlineError, "No Section found for APage #{apage}"
+    end
+  end
+end

data/lib/structure/section.rb

@@ -0,0 +1,38 @@
+require_relative 'a_page_enrichment'
+
+module JekyllSupport
+  class Section
+    attr_accessor :children, :title, :order
+
+    def initialize(outline_options, parameter_array)
+      @outline_options = outline_options
+      @order = parameter_array[0].to_i
+      @title = parameter_array[1]
+      @children = []
+    end
+
+    def add_child(child)
+      @children << child
+    end
+
+    def to_s
+      return '' if @children.count.zero?
+
+      unless @children.first.instance_of?(JekyllSupport::APage)
+        raise "First child of Section was a #{@children.first.class}, not an APage"
+      end
+      apages = @children
+               .map { |x| x.render_outline_apage @outline_options.pattern }
+               .join("\n      ")
+
+      <<~END_SECTION
+        <h3 class='post_title clear' id="title_#{@order}">#{@title}</h3>
+          <div id='posts_wrapper_#{@order}' class='clearfix'>
+            <div id="posts_#{@order}" class='posts'>
+              #{apages}
+            </div>
+          </div>
+      END_SECTION
+    end
+  end
+end

data/lib/structure/yaml_parser.rb

@@ -0,0 +1,58 @@
+require 'yaml'
+require_relative 'section'
+
+class OutlineError < StandardError; end
+
+module JekyllSupport
+  class YamlParser
+    attr_reader :sections
+
+    # @return array of empty Sections
+    def initialize(outline_options, content = '')
+      @logger = outline_options.logger
+      @sections = if content && !content.strip.empty?
+                    parse_sections outline_options, content
+                  else
+                    []
+                  end
+    end
+
+    # @return Array of Sections that do not contain children
+    def parse_sections(outline_options, content)
+      content = remove_leading_zeros remove_leading_spaces content
+      yaml = YAML.safe_load content
+      yaml.map { |entry| Section.new outline_options, entry }
+    rescue NoMethodError => e
+      raise OutlineError, <<~END_MSG
+        Invalid YAML within {% outline %} tag. The offending content was:
+
+        <pre>#{content}</pre>
+      END_MSG
+    rescue Psych::SyntaxError => e
+      msg = <<~END_MSG
+        Invalid YAML found within {% outline %} tag:<br>
+        <pre>#{e.message}</pre>
+      END_MSG
+      @logger.error { e.message }
+      raise OutlineError, msg
+    end
+
+    private
+
+    def remove_leading_spaces(multiline)
+      multiline
+        .strip
+        .split("\n")
+        .map { |x| x.gsub(/\A\s+/, '') }
+        .join("\n")
+    end
+
+    def remove_leading_zeros(multiline)
+      multiline
+        .strip
+        .split("\n")
+        .map { |x| x.gsub(/(?<= |\A)0+(?=\d)/, '') }
+        .join("\n")
+    end
+  end
+end

data/spec/outline_spec.rb

@@ -1,10 +1,152 @@
-require 'jekyll'
-require_relative '../lib/jekyll_outline'
+require 'jekyll_plugin_support'
+require 'rspec/match_ignoring_whitespace'
+require_relative 'spec_helper'
+require_relative '../lib/structure/outline'
 
-RSpec.describe(OutlineTag) do
-  include Jekyll
+RSpec.describe(JekyllSupport) do
+  outline_options = JekyllSupport::OutlineOptions.new(pattern: '<b> title </b> &ndash; <i> description </i>')
+  section1 = described_class::Section.new(outline_options, [0, 'Section 1'])
+  section2 = described_class::Section.new(outline_options, [3, 'Section 2'])
 
-  it 'never works first time', skip: 'Just a placeholder' do
-    expect(true).to be_truthy
+  apages = [
+    described_class.apage_from(
+      collection_name: '_posts',
+      date:            '2023-01-01',
+      description:     'This is the entry1 description.',
+      draft:           true,
+      last_modified:   '2023-01-01',
+      order:           1,
+      title:           'Entry 1',
+      url:             'https://example.com/entry1'
+    ),
+    described_class.apage_from(
+      collection_name: '_posts',
+      date:            '2023-01-02',
+      description:     'This is the entry2 description.',
+      last_modified:   '2023-01-02',
+      order:           2,
+      title:           'Entry 2',
+      url:             'https://example.com/entry2'
+    ),
+    described_class.apage_from(
+      collection_name: '_posts',
+      date:            '2023-10-03',
+      description:     'This is the entry3 description.',
+      last_modified:   '2024-10-03',
+      order:           3,
+      title:           'Entry 3',
+      url:             'https://example.com/entry3'
+    ),
+    described_class.apage_from(
+      collection_name: '_posts',
+      date:            '2023-10-04',
+      description:     'This is the entry4 description.',
+      draft:           true,
+      last_modified:   '2024-10-04',
+      order:           4,
+      title:           'Entry 4',
+      url:             'https://example.com/entry4'
+    ),
+    described_class.apage_from(
+      collection_name: '_posts',
+      date:            '2023-10-05',
+      description:     'This is the entry5 description.',
+      last_modified:   '2024-10-05',
+      order:           5,
+      title:           'Entry 5',
+      url:             'https://example.com/entry5'
+    ),
+    described_class.apage_from(
+      collection_name: '_posts',
+      date:            '2023-10-06',
+      description:     'This is the entry6 description.',
+      last_modified:   '2024-10-06',
+      order:           6,
+      title:           'Entry 6',
+      url:             'https://example.com/entry6'
+    )
+  ]
+
+  outline = described_class::Outline.new
+  outline.add_sections [section1, section2]
+  outline.add_entries apages
+
+  _attribution = <<~END_ATT
+    <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>
+  END_ATT
+
+  expected_section1 = <<~END_EXPECTED
+    <h3 class='post_title clear' id="title_0">Section 1</h3>
+    <div id='posts_wrapper_0' class='clearfix'>
+      <div id="posts_0" class='posts'>
+        <span>2023-01-01</span>
+        <span><a href='https://example.com/entry1'><b> Entry 1 </b> &ndash; <i> This is the entry1 description. </i> </a> <i class='jekyll_draft'>Draft</i></span>
+
+        <span>2023-01-02</span>
+        <span><a href='https://example.com/entry2'><b> Entry 2 </b> &ndash; <i> This is the entry2 description. </i> </a></span>
+      </div>
+    </div>
+  END_EXPECTED
+
+  expected_section2 = <<~END_EXPECTED
+    <h3 class='post_title clear' id="title_3">Section 2</h3>
+    <div id='posts_wrapper_3' class='clearfix'>
+      <div id="posts_3" class='posts'>
+        <span>2024-10-03</span>
+        <span><a href='https://example.com/entry3'><b> Entry 3 </b> &ndash; <i> This is the entry3 description. </i> </a></span>
+
+        <span>2024-10-04</span>
+        <span><a href='https://example.com/entry4'><b> Entry 4 </b> &ndash; <i> This is the entry4 description. </i> </a> <i class='jekyll_draft'>Draft</i></span>
+
+        <span>2024-10-05</span>
+        <span><a href='https://example.com/entry5'><b> Entry 5 </b> &ndash; <i> This is the entry5 description. </i> </a></span>
+
+        <span>2024-10-06</span>
+        <span><a href='https://example.com/entry6'><b> Entry 6 </b> &ndash; <i> This is the entry6 description. </i> </a></span>
+      </div>
+    </div>
+  END_EXPECTED
+
+  it 'verifies initial values' do
+    expect(outline.options.sort_by).to eq(:order)
+  end
+
+  it 'sorts by :order' do
+    expect(outline.sort(apages)).to eq(apages)
+  end
+
+  it 'checks html shape' do
+    expect(outline.sections.count).to eq(2)
+    expect(outline.sections[0].children.count).to eq(2)
+    expect(outline.sections[1].children.count).to eq(4)
+  end
+
+  it 'verifies html for first section' do
+    actual = outline.sections[0].to_s
+    expect(expected_section1).to match_ignoring_whitespace(actual)
+  end
+
+  it 'verifies html for second section' do
+    actual = outline.sections[1].to_s
+    expect(expected_section2).to match_ignoring_whitespace(actual)
+  end
+
+  it 'verifies generated html' do
+    actual = outline.to_s
+
+    expected = <<~END_EXPECTED
+      <div class='outer_posts'>
+        #{expected_section1}
+        #{expected_section2}
+      </div>
+    END_EXPECTED
+
+    expect(expected).to match_ignoring_whitespace(actual)
   end
 end

data/spec/spec_helper.rb

@@ -1,10 +1,23 @@
 require 'jekyll'
-require_relative '../lib/jekyll_outline'
 
-RSpec.configure do |config|
-  config.filter_run_when_matching focus: true
-  config.order = 'random'
+# For testing Jekyll plugins based on jekyll_plugin_support:
+require 'jekyll_plugin_logger'
+require 'jekyll_plugin_support'
 
+RSpec.configure do |config|
   # See https://relishapp.com/rspec/rspec-core/docs/command-line/only-failures
   config.example_status_persistence_file_path = 'spec/status_persistence.txt'
+
+  # See https://rspec.info/features/3-12/rspec-core/filtering/filter-run-when-matching/
+  # and https://github.com/rspec/rspec/issues/221
+  config.filter_run_when_matching :focus
+
+  # Other values: :progress, :html, :json, CustomFormatterClass
+  config.formatter = :documentation
+
+  # See https://rspec.info/features/3-12/rspec-core/command-line/order/
+  config.order = :defined
+
+  # See https://www.rubydoc.info/github/rspec/rspec-core/RSpec%2FCore%2FConfiguration:pending_failure_output
+  config.pending_failure_output = :skip
 end

data/spec/status_persistence.txt

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

data/spec/yaml_parser_spec.rb

@@ -0,0 +1,84 @@
+require 'spec_helper'
+require 'rspec/match_ignoring_whitespace'
+require_relative '../lib/structure/outline'
+require_relative '../lib/structure/yaml_parser'
+
+module JekyllSupport
+  logger = PluginMetaLogger.instance.new_logger(self, PluginMetaLogger.instance.config)
+  outline_options = OutlineOptions.new
+
+  # includes leading zeros and leading spaces, which are invalid in YAML
+  yaml_parser_big = YamlParser.new outline_options, <<~END_DATA
+      0: Production Infrastructure
+    0015000: Audio
+      20000: Video
+      30000: RME
+      40000: OBS Studio
+      50000: Pro Tools
+      55000: Ableton Live &amp; Push
+      60000: Other Music Software
+      70000: MIDI Hardware &amp; Software
+      80000: Davinci Resolve
+      100000: Computer Analysis
+      200000: Music Theory
+      300000: Business
+      400000: General
+  END_DATA
+
+  RSpec.describe(YamlParser) do
+    it 'handles no section headings' do
+      yaml_parser = described_class.new outline_options
+      sections = yaml_parser.sections
+      expect(sections.count).to equal(0)
+
+      yaml_parser = described_class.new outline_options, ''
+      sections = yaml_parser.sections
+      expect(sections.count).to equal(0)
+    end
+
+    it 'finds only 1 section heading' do
+      yaml_parser = described_class.new outline_options, '0: General'
+      sections = yaml_parser.sections
+      expect(sections.count).to equal(1)
+      # expect(sections.first)
+
+      yaml_parser = described_class.new outline_options, <<~END_DATA
+        0: General
+      END_DATA
+      sections = yaml_parser.sections
+      expect(sections.count).to equal(1)
+
+      # Handle leading space (this is invalid YAML) and the lack of an end of line character
+      yaml_parser = described_class.new outline_options, ' 0: General'
+      sections = yaml_parser.sections
+      expect(sections.count).to equal(1)
+    end
+
+    it 'finds matching sections' do
+      sections = yaml_parser_big.sections
+      expect(sections.count).to equal(14)
+
+      section1 = sections.first
+      expect(section1.order).to eq(0)
+      expect(section1.title).to eq('Production Infrastructure')
+
+      outline = Outline.new.add_sections sections
+
+      apage0 = JekyllSupport.apage_from(date: Time.now, logger: logger, order: 0)
+      actual_section = outline.send :section_for, apage0
+      expect(actual_section.order).to eq(0)
+
+      apage1000 = JekyllSupport.apage_from(date: Time.now, logger: logger, order: 1000)
+      actual_section = outline.send :section_for, apage1000
+      expect(actual_section.order).to eq(0)
+
+      apage16000 = JekyllSupport.apage_from(date: Time.now, logger: logger, order: 16_000)
+      actual_section = outline.send :section_for, apage16000
+      expect(actual_section.order).to eq(15_000)
+
+      apage25000 = JekyllSupport.apage_from(date: Time.now, logger: logger, order: 25_000)
+      actual_section = outline.send :section_for, apage25000
+      expect(actual_section.order).to eq(20_000)
+    end
+  end
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_outline
 version: !ruby/object:Gem::Version
-  version: 1.2.5
+  version: 1.3.0
 platform: ruby
 authors:
 - Mike Slinn
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-20 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -16,42 +15,42 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.5.0
+        version: 4.4.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.5.0
+        version: 4.4.0
 - !ruby/object:Gem::Dependency
   name: jekyll_draft
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.2
+        version: 3.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.0.2
+        version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: jekyll_plugin_support
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.2
+        version: 3.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.2
+        version: 3.1.0
 description: 'Jekyll tag plugin that creates a clickable table of contents.
 
   '
@@ -72,9 +71,14 @@ files:
 - lib/jekyll_outline/version.rb
 - lib/outline_js.rb
 - lib/outline_tag.rb
+- lib/structure/a_page_enrichment.rb
+- lib/structure/outline.rb
+- lib/structure/section.rb
+- lib/structure/yaml_parser.rb
 - spec/outline_spec.rb
 - spec/spec_helper.rb
 - spec/status_persistence.txt
+- spec/yaml_parser_spec.rb
 homepage: https://www.mslinn.com/jekyll_plugins/jekyll_outline.html
 licenses:
 - MIT
@@ -102,12 +106,12 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Jekyll tag plugin that creates a clickable table of contents.
 test_files:
 - spec/outline_spec.rb
 - spec/spec_helper.rb
 - spec/status_persistence.txt
+- spec/yaml_parser_spec.rb
 ...