jekyll_outline 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed799d887e818fc21f0892c7c7fe550081352b98554bc4dae0fc8d6fb04b0a90
-  data.tar.gz: ae4fd7f8a48d45abcabad5207566a8f96d0fe8b14e0016b294f54c9ba576f7fc
+  metadata.gz: 3efed359f1a20b1b255dff89ae002fc464162ae11f2ffbaaf2463cfdce031cfa
+  data.tar.gz: ba1a9378d1424cc673fb75bcc0bd8a0758b6861facb66474a24dad19a568940d
 SHA512:
-  metadata.gz: ac864827baf9f274f85d9f52c84e38216bd8edd6ebd86be766b8002d966050cdc14e8f966bf905edbd7362386620bc012d7f66fd18c86c74eabafb564bdc8a04
-  data.tar.gz: cc3cfd1e248224f34b242aa501a8cdf12f8d86dd26f46b09449f22505f4a33e6840892bccd875defcf558ae8822af68085751808318a9c2cb823eee35342438f
+  metadata.gz: a1147061ffb817c16a64002a8b300380943a319eb44c0077c54f76b9d6cd2f6d4500778fd369deed65f7256357feb5140129bda26be08344b2149bce00861b06
+  data.tar.gz: d03d8db73e90f7c39aa5b6f8f379ab2cfe8d47dae740e2e0a9d6355ac486713db28e02af07145e33279cba2d9aba982ae10f07c08087c192c953851d7fd51f25

data/.rubocop.yml

@@ -25,7 +25,7 @@ Layout/LineLength:
 Metrics/BlockLength:
   Exclude:
     - jekyll_outline.gemspec
-  Max: 30
+  Max: 40
 
 Metrics/MethodLength:
   Max: 30

data/CHANGELOG.md

@@ -1,8 +1,14 @@
+## 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.0
+  * Updated to `jekyll_plugin_support` v0.5.1
 
 ## 1.0.1 / 2023-02-14
   * 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

@@ -18,6 +18,102 @@ And then execute:
     $ bundle install
 
 
+### 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 */
+```
+
+### 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>
+```
+
+If passed the `wrap_in_script_tag` parameter, it wraps the JavaScript in `<script></script>`:
+
+```html
+{% outline_js wrap_in_script_tag %}
+```
+
+
+## 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.
+```html
+{% 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"
+%}
+```
+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.
+
+
 ## Additional Information
 More information is available on
 [Mike Slinn&rsquo;s website](https://www.mslinn.com/jekyll/3000-jekyll-plugins.html#outline).

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,7 +9,10 @@ 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.files = Dir[
+    '.rubocop.yml', 'LICENSE.*', 'Rakefile', '{lib,spec}/**/*', '*.gemspec', '*.md',
+    'demo/assets/js/jekyll_outline.js'
+  ]
   spec.homepage = 'https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html#outline'
   spec.license = 'MIT'
   spec.metadata = {
@@ -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_draft', '~> 1.1.0'
   spec.add_dependency 'jekyll_plugin_support', '~> 0.5.0'
 end

data/lib/jekyll_outline/version.rb

@@ -1,3 +1,3 @@
 module JekyllOutlineVersion
-  VERSION = '1.0.1'.freeze
+  VERSION = '1.1.0'.freeze
 end

data/lib/jekyll_outline.rb

@@ -1,111 +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 './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,132 @@
+# @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)
+      @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="outer_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(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, Layout/LineEndStringConcatenationIndentation
+      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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_outline
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Mike Slinn
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-02-16 00:00:00.000000000 Z
+date: 2023-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -30,14 +30,14 @@ 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
@@ -66,9 +66,12 @@ 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