jekyll_outline 1.0.2 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a9d31ca01b4964fe4a2f449ae0af3e9c62778378dbcfd2e093aea52bf5bd4cc5
-  data.tar.gz: 0c9eefb3062c192bbc31c9dc972e363c3c62ff9ad1bbe92479337cf46f0f1a75
+  metadata.gz: 464b66396b0abd3369669875ca6b2be97b51e7823e31d5fa163b4248afc0dc50
+  data.tar.gz: 1253ef8b8218d0c4f76cb66d5f79ef0bc4fef48cec8d057ef33b0af0411e352f
 SHA512:
-  metadata.gz: d60b91075f29d828182822dea631af65b31e436a2301ff505fb29febdf1554b8b8e0a85879c472f30a309daaa204b8869d8dcf4be38771088cf644c2399832bf
-  data.tar.gz: a0dfba650a90e1c34ba3bffaaf95cf31552a0f7a4589086f4debba869fed0fcc819438057ab201f2b78913f0feb0fb5bce965b8686d6aa2da5555ea8610609b4
+  metadata.gz: 96bf42bd9e24050bf05fc9c5d1a2094383f2dd3853c301da97ce5e8276969de31ddc98cc5102f3288e46cb84ae9032a2e8c40813993445d837a5a60ffd4b0559
+  data.tar.gz: 56facfe2c9305b0945ad1d315018b078f1a0402b1c91655ea01a2741f9f39d2975bce5de31eb84490126f4b19700e98a617a84d61a17fbc27a225cc750b941ba

data/.rubocop.yml

@@ -1,6 +1,8 @@
 require:
- - rubocop-rspec
+ - rubocop-md
+ - rubocop-performance
  - rubocop-rake
+ - rubocop-rspec
 
 AllCops:
   Exclude:
@@ -17,7 +19,8 @@ Gemspec/RequireMFA:
   Enabled: false
 
 Layout/HashAlignment:
-  Enabled: false
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
 
 Layout/LineLength:
   Max: 150
@@ -25,7 +28,7 @@ Layout/LineLength:
 Metrics/BlockLength:
   Exclude:
     - jekyll_outline.gemspec
-  Max: 30
+  Max: 40
 
 Metrics/MethodLength:
   Max: 30

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 1.1.1 / 2023-04-02
+  * 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.
+
 ## 1.0.2 / 2023-02-16
   * Updated to `jekyll_plugin_support` v0.5.1
 
@@ -5,4 +14,4 @@
   * Now dependent upon `jekyll_plugin_support`
 
 ## 1.0.0 / 2022-04-02
-  * Initial version
+  * Initial version, this Jekyll plugin defines a block tag called `outline`.

data/README.md

@@ -6,11 +6,12 @@
 
 
 ## Installation
-
-Add this line to your application's Gemfile:
+Add the following line to your Jekyll project's Gemfile, within the `jekyll_plugins` group:
 
 ```ruby
-gem 'jekyll_outline'
+group :jekyll_plugins do
+  gem 'jekyll_outline'
+end
 ```
 
 And then execute:
@@ -18,21 +19,118 @@ And then execute:
     $ bundle install
 
 
-## Additional Information
-More information is available on
-[Mike Slinn’s website](https://www.mslinn.com/jekyll/3000-jekyll-plugins.html#outline).
+### CSS
+The CSS used for the demo website should be copied to your project.
+See the section of `demo/assets/css/styles.css` as shown:
 
+```css
+/* Start of jekyll_outline css */
+  ... copy this portion ...
+/* End of jekyll_outline css */
+```
 
-## Development
+### 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:
+
+```html
+<script>
+  {%= outline_js %}
+</script>
+```
 
-After checking out the repo, run `bin/setup` to install dependencies.
-You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+If passed the `wrap_in_script_tag` parameter, it wraps the JavaScript in `<script></script>`:
 
-Install development dependencies like this:
+```html
+{% outline_js wrap_in_script_tag %}
 ```
-$ BUNDLE_WITH="development" bundle install
+
+
+## Explanation
+Given an outline that looks like this:
+```html
+{% outline stuff %}
+000: Topic 0..19
+020: Topic 20..39
+040: Topic 40..
+{% endoutline %}
+```
+
+...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**
+
+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>
+  <div id='posts_wrapper_0' class='clearfix'>
+    <div id='posts_0' class='posts'>
+      <span>2022-04-01</span> <span><a href='/stuff/010-published.html'>Published Stuff Post 010</a></span>
+      <span>2022-04-17</span> <span><a href='/stuff/020-unpublished.html'>Unpublished Post 020</a> <i class='jekyll_draft'>Draft</i></span>
+    </div>
+  </div>
+  <h3 class='post_title clear' id="title_20">Topic 20..39</h3>
+  <div id='posts_wrapper_20' class='clearfix'>
+    <div id='posts_20' class='posts'>
+      <span>2022-04-17</span> <span><a href='/stuff/030-unpublished.html'>Unpublished Post 030</a> <i class='jekyll_draft'>Draft</i></span>
+    </div>
+  </div>
+</div>
 ```
 
+The JavaScript searches for images in the current page that were created by the [`img`](https://github.com/mslinn/jekyll_img) tag plugin,
+and have `id`s that correspond to outline sections.
+
+Each of following image's `id`s have a `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.
+
+The images are wrapped 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"
+  id="outline_0"
+  size="quartersize"
+  src="/assets/images/porcelain_washbasin.webp"
+  style="margin-top: 0"
+  wrapper_class="clear"
+%}
+{% img align="right"
+  id="outline_20"
+  size="quartersize"
+  src="/assets/images/pipes.webp"
+  style="margin-top: 0"
+  wrapper_class="clear"
+%}
+{% img align="right"
+  id="outline_40"
+  size="quartersize"
+  src="/assets/images/libgit2.webp"
+  style="margin-top: 0"
+  wrapper_class="clear"
+%}
+</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 with `irb`.
+
 To build and install this gem onto your local machine, run:
 ```shell
 $ bundle exec rake install
@@ -54,16 +152,28 @@ jekyll_outline (0.1.0)
 ```
 
 
-## Test
-A test website is provided in the `demo` directory.
- 1. Set breakpoints.
+## 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)
+
+### Plugin Debugging
+ 1. Set breakpoints in Visual Studio Code.
 
  2. Initiate a debug session from the command line:
     ```shell
-    $ bin/attach demo
+    $ demo/_bin/debug
     ```
 
-  3. Once the `Fast Debugger` signon appears, launch the Visual Studio Code launch configuration called `Attach rdebug-ide`.
+  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)
 
@@ -82,10 +192,8 @@ To release a new version,
 
 
 ## Contributing
-
 Bug reports and pull requests are welcome on GitHub at https://github.com/mslinn/jekyll_outline.
 
 
 ## License
-
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/demo/assets/js/jekyll_outline.js

@@ -0,0 +1,31 @@
+// jekyll_img generates picture tags wrapped within divs
+// We move the entire div, not just the picture tag
+// If an image does not correspond to a heading, delete it
+function position_outline_image(picture, before_id) {
+  var img = picture.parentElement;
+  var before_element = document.getElementById(before_id);
+  if (before_element) {
+    var parent = before_element.parentElement;
+    parent.insertBefore(img, before_element);
+  } else {
+    img.remove();
+  }
+}
+
+function getElementsByIdPrefix(selectorTag, prefix) {
+  var items = [];
+  var myPosts = document.getElementsByTagName(selectorTag);
+  for (var i = 0; i < myPosts.length; i++) {
+    //omitting undefined null check for brevity
+    if (myPosts[i].id.lastIndexOf(prefix, 0) === 0)
+      items.push(myPosts[i]);
+  }
+  return items;
+}
+
+window.onload = (event) => {
+  getElementsByIdPrefix("picture", "outline_").forEach(picture => {
+    num = picture.id.substring("outline_".length)
+    position_outline_image(picture, `posts_wrapper_${num}`)
+  });
+}

data/jekyll_outline.gemspec

@@ -9,8 +9,11 @@ Gem::Specification.new do |spec|
     Jekyll tag plugin that creates a clickable table of contents.
   END_OF_DESC
   spec.email = ['mslinn@mslinn.com']
-  spec.files = Dir['.rubocop.yml', 'LICENSE.*', 'Rakefile', '{lib,spec}/**/*', '*.gemspec', '*.md']
-  spec.homepage = 'https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html#outline'
+  spec.files = Dir[
+    '.rubocop.yml', 'LICENSE.*', 'Rakefile', '{lib,spec}/**/*', '*.gemspec', '*.md',
+    'demo/assets/js/jekyll_outline.js'
+  ]
+  spec.homepage = 'https://www.mslinn.com/jekyll/3000-jekyll-plugins.html#outline'
   spec.license = 'MIT'
   spec.metadata = {
     'allowed_push_host' => 'https://rubygems.org',
@@ -32,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.1'
-  spec.add_dependency 'jekyll_plugin_support', '~> 0.5.1'
+  spec.add_dependency 'jekyll_draft', '~> 1.1.0'
+  spec.add_dependency 'jekyll_plugin_support', '~> 0.6.0'
 end

data/lib/jekyll_outline/version.rb

@@ -1,3 +1,3 @@
 module JekyllOutlineVersion
-  VERSION = '1.0.2'.freeze
+  VERSION = '1.1.1'.freeze
 end

data/lib/jekyll_outline.rb

@@ -1,112 +1,7 @@
-# @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 './outline_js'
+require_relative './outline_tag'
 
 module Outline
-  PLUGIN_NAME = 'outline'.freeze
-
-  # Interleaves with docs
-  class Header
-    attr_accessor :order, :title
-
-    def initialize(yaml)
-      @order = yaml[0]
-      @published = true
-      @title = yaml[1]
-    end
-
-    def to_s
-      <<~END_STR
-        <h3 id="title_#{order}">#{title}</h3>
-      END_STR
-    end
-  end
-
-  class OutlineTag < JekyllSupport::JekyllBlock
-    include JekyllOutlineVersion
-
-    FIXNUM_MAX = (2**((0.size * 8) - 2)) - 1
-
-    def render_impl(text)
-      @collection_name = argument_string.strip
-      abort 'OutlineTag: collection_name was not specified' unless @collection_name
-
-      headers = make_headers(super) # Process the block content.
-      collection = headers + obtain_docs(@collection_name)
-      <<~HEREDOC
-        <div class="posts">
-          #{make_entries(collection).join("\n")}
-        </div>
-      HEREDOC
-    end
-
-    private
-
-    def header?(variable)
-      variable.instance_of?(Header)
-    end
-
-    def make_headers(content)
-      yaml = YAML.safe_load content
-      yaml.map { |entry| Header.new entry }
-    end
-
-    def make_entries(collection)
-      sorted = collection.sort_by(&obtain_order)
-      pruned = remove_empty_headers(sorted)
-      pruned.map do |entry|
-        if entry.instance_of? Header
-          <<~END_ENTRY
-            <span></span> <span>#{entry}</span>
-          END_ENTRY
-        else
-          date = entry.data['last_modified_at'] # "%Y-%m-%d"
-          draft = Jekyll::Draft.draft_html(entry)
-          <<~END_ENTRY
-            <span>#{date}</span> <span><a href="#{entry.url}">#{entry.data['title']}</a>#{draft}</span>
-          END_ENTRY
-        end
-      end
-    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 without 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
-        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
-
-    JekyllPluginHelper.register(self, PLUGIN_NAME)
-  end
+  include OutlineTag
+  include OutlineJsTag
 end

data/lib/outline_js.rb

@@ -0,0 +1,40 @@
+require 'jekyll_plugin_support'
+require_relative 'jekyll_outline/version'
+
+module OutlineJsTag
+  PLUGIN_JS_NAME = 'outline_js'.freeze
+
+  class OutlineJsTag < JekyllSupport::JekyllTag
+    include JekyllOutlineVersion
+
+    def render_impl
+      wrap_in_script_tag = @helper.parameter_specified?('wrap_in_script_tag')
+
+      gem_path = Gem::Specification.find_by_name('jekyll_outline').full_gem_path
+      js_path = File.join(gem_path, 'demo/assets/js/jekyll_outline.js')
+      js = File.read(js_path)
+
+      if wrap_in_script_tag
+        <<~END_JS
+          <script>
+            #{indent(js)}
+          </script>
+        END_JS
+      else
+        js
+      end
+    end
+
+    private
+
+    def indent(multiline)
+      multiline
+        .strip
+        .split("\n")
+        .map { |x| "  #{x}" }
+        .join("\n")
+    end
+
+    JekyllPluginHelper.register(self, PLUGIN_JS_NAME)
+  end
+end

data/lib/outline_tag.rb

@@ -0,0 +1,135 @@
+# @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'
+
+module OutlineTag
+  PLUGIN_NAME = 'outline'.freeze
+
+  # Interleaves with docs
+  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
+
+  class OutlineTag < JekyllSupport::JekyllBlock
+    include JekyllOutlineVersion
+
+    FIXNUM_MAX = (2**((0.size * 8) - 2)) - 1
+
+    def render_impl(text)
+      headers = make_headers(super) # Process the block content.
+
+      @helper.gem_file __FILE__
+      @collection_name = @helper.remaining_markup
+      abort 'OutlineTag: collection_name was not specified' unless @collection_name
+
+      collection = headers + obtain_docs(@collection_name)
+      <<~HEREDOC
+        <div class="outer_posts">
+        #{make_entries(collection)&.join("\n")}
+        </div>
+        #{@helper.attribute if @helper.attribution}
+      HEREDOC
+    end
+
+    private
+
+    def header?(variable)
+      variable.instance_of?(Header)
+    end
+
+    def make_headers(content)
+      yaml = YAML.safe_load(remove_leading_zeros(content))
+      yaml.map { |entry| Header.new entry }
+    end
+
+    # @section_state can have values: :head, :in_body
+    # @param collection Array of Jekyll::Document and Outline::Header
+    # @return Array of String
+    def make_entries(collection) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      sorted = collection.sort_by(&obtain_order)
+      pruned = remove_empty_headers(sorted)
+      @section_state = :head
+      @section_id = 0
+      result = pruned.map do |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 = "<div id='posts_wrapper_#{@header_order}' class='clearfix'>\n    " \
+                            "<div id='posts_#{@header_order}' class='posts'>\n"
+          end
+          @section_state = :in_body
+          date = entry.data['last_modified_at'] # "%Y-%m-%d"
+          draft = Jekyll::Draft.draft_html(entry)
+          result = "    <span>#{date}</span> <span><a href='#{entry.url}'>#{entry.data['title']}</a>#{draft}</span>"
+          result = section_start + result if section_start
+          result
+        end
+      end
+      result << "    </div>\n  </div>" if @section_state == :in_body
+      result
+    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 without 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
+        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_zeros(multiline)
+      multiline
+        .strip
+        .split("\n")
+        .map { |x| x.gsub(/(?<= |\A)0+(?=\d)/, '') }
+        .join("\n")
+    end
+
+    JekyllPluginHelper.register(self, PLUGIN_NAME)
+  end
+end

data/spec/status_persistence.txt

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_outline
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.1
 platform: ruby
 authors:
 - Mike Slinn
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-02-17 00:00:00.000000000 Z
+date: 2023-04-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -30,28 +30,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.1
+        version: 1.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.1
+        version: 1.1.0
 - !ruby/object:Gem::Dependency
   name: jekyll_plugin_support
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.5.1
+        version: 0.6.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.5.1
+        version: 0.6.0
 description: 'Jekyll tag plugin that creates a clickable table of contents.
 
   '
@@ -66,19 +66,23 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- demo/assets/js/jekyll_outline.js
 - jekyll_outline.gemspec
 - lib/jekyll_outline.rb
 - lib/jekyll_outline/version.rb
+- lib/outline_js.rb
+- lib/outline_tag.rb
 - spec/outline_spec.rb
 - spec/spec_helper.rb
-homepage: https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html#outline
+- spec/status_persistence.txt
+homepage: https://www.mslinn.com/jekyll/3000-jekyll-plugins.html#outline
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
   bug_tracker_uri: https://github.com/mslinn/jekyll_outline/issues
   changelog_uri: https://github.com/mslinn/jekyll_outline/CHANGELOG.md
-  homepage_uri: https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html#outline
+  homepage_uri: https://www.mslinn.com/jekyll/3000-jekyll-plugins.html#outline
   source_code_uri: https://github.com/mslinn/jekyll_outline
 post_install_message: |2+
 
@@ -105,4 +109,5 @@ 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
 ...