jekyll_outline 1.2.4 → 1.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 296c5201e11daec7ec2e91ae703662ba44cfb7ca592da27adf61c23943a3c100
-  data.tar.gz: 246e14ecb99ecf5a7510e7bcbd40eb5cfa58eb8e3cd740f33a726bc7b42cda78
+  metadata.gz: 789f862a50e91feb22e61715574c1358dfac651dd0029617333032d89bd3920a
+  data.tar.gz: 327437833f654e62df9e71540be12985eb98e518d4c87edd5f632aa4f5b9028a
 SHA512:
-  metadata.gz: a3667c2afb14fb58fb6192149d51265ea54cbb745968ce0a04ba208bbf7a1cf807994a2f2057d38a57759d5679a89ac2a69cd52f829b1e61034c7daea158d02f
-  data.tar.gz: 04e34bcdd95b84affb8b9a73e7a638c9013bc978ba393d11591772a132e4191237c168374fc6d203ce51525945a76350c2f79e6b31f140723f988296678c2585
+  metadata.gz: ac54e627cf7a5e839dff378e2d85c2c1d89ae6cad12fcdd1fa728591b0d3ed597d93c0af78787ef27ca15a4a4212b6f02156897b988f98c27587d9d73f297c1b
+  data.tar.gz: 4d6725aae2d9c428f9dcfbc2128918ca2bf43c626a26d235af7d183cb04d17252b8f1333ad125202e3c2fe8ef1a5880594bf68e1e52dfd3122e7d014116efc8b

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Change Log
 
+## 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
+* Updated to jekyll_plugin_support v1.0.2
+* Defined `outline_error` CSS class in `demo/assets/css/jekyll_outline.css`.
+
+
 ## 1.2.4 / 2024-07-23
 
 * Updated dependencies to rely on current `jekyll_draft`.

data/README.md

@@ -3,11 +3,190 @@
 `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
+```
+
+### [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 %}
@@ -53,7 +232,7 @@ 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`.
+`ext`, and `tags`.
 
 Specify the fields like this:
 
@@ -65,7 +244,7 @@ Specify the fields like this:
 {% endoutline %}
 ```
 
-Words that are not a known field are transcribed into the output.
+Words in the `fields` 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 +254,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 +325,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.0'
+  spec.add_dependency 'jekyll_plugin_support', '>= 1.0.2'
 end

data/lib/jekyll_outline/version.rb

@@ -1,3 +1,3 @@
 module JekyllOutlineVersion
-  VERSION = '1.2.4'.freeze
+  VERSION = '1.2.6'.freeze
 end

data/lib/outline_tag.rb

@@ -62,6 +62,10 @@ module JekyllSupport
       headers = make_headers(super) # Process the block content.
 
       @helper.gem_file __FILE__
+
+      @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
@@ -70,6 +74,12 @@ module JekyllSupport
       @docs = obtain_docs(@collection_name)
       collection = headers + @docs
       render_outline collection
+    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
+      exit! 1 if @die_on_outline_error
+
+      e.html_message
     end
 
     # Overload this for a subclass
@@ -95,11 +105,18 @@ module JekyllSupport
       yaml = YAML.safe_load content
       yaml.map { |entry| Header.new entry }
     rescue NoMethodError => e
-      raise OutlineError, "Invalid YAML within {% outline %} tag;<br>\nNoMethodError #{e.message}"
+      raise OutlineError, <<~END_MSG
+        Invalid YAML within {% outline %} tag. The offending content was:
+
+        <pre>#{content}</pre>
+      END_MSG
     rescue Psych::SyntaxError => e
-      raise OutlineError, "Invalid YAML within {% outline %} tag;<br>\nPsych::SyntaxError #{e.message}"
-    rescue StandardError => e
-      raise OutlineError, e.message
+      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
@@ -169,16 +186,18 @@ module JekyllSupport
       @site
         .collections[@collection_name]
         .docs
-        .find { |doc| doc.path.end_with? "#{doc_name}.html" }
+        .reject { |doc| doc.data['exclude_from_outline'] }
+        .find { |doc| doc.url.match(/#{doc_name}(.\w*)?$/) }
     end
 
-    # Ignores files called index.html
+    # Ignores files whose name starts with `index`, and those with the following in their front matter:
+    # exclude_from_outline: true
     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' }
+        .reject { |doc| doc.url.match(/index(.\w*)?$/) || doc.data['exclude_from_outline'] }
     end
 
     # Sort entries within the outline tag which do not have the property specified by @sort_by at the end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_outline
 version: !ruby/object:Gem::Version
-  version: 1.2.4
+  version: 1.2.6
 platform: ruby
 authors:
 - Mike Slinn
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-07-27 00:00:00.000000000 Z
+date: 2025-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -44,14 +43,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: 1.0.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: 1.0.2
 description: 'Jekyll tag plugin that creates a clickable table of contents.
 
   '
@@ -102,8 +101,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 3.6.3
 specification_version: 4
 summary: Jekyll tag plugin that creates a clickable table of contents.
 test_files: