jekyll_outline 1.2.5 → 1.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a31ba9e3b1f1b0962f5ac28695f41b2594acde555195fdcbbf0460fa220be66e
-  data.tar.gz: bdd1e6536607a24271019aa3cc24e5de35e71b1ac4c61b925f286bb41dd5521c
+  metadata.gz: 789f862a50e91feb22e61715574c1358dfac651dd0029617333032d89bd3920a
+  data.tar.gz: 327437833f654e62df9e71540be12985eb98e518d4c87edd5f632aa4f5b9028a
 SHA512:
-  metadata.gz: e815455631865429afb66cfffce54187e4696e0ecb7e3571050ab98fa6991bd679791a212cdc9915b4e9a9d0c199bf6af0ca9d77a09babe89d7d5fa83a88fa4d
-  data.tar.gz: bcc3910b01ca8d3c99ed101764350f17c95826f3b375733215f35659a6027605452881b528197709d1143b576c7c52cf2b51aad3971c1781b03b97c414f8d1dc
+  metadata.gz: ac54e627cf7a5e839dff378e2d85c2c1d89ae6cad12fcdd1fa728591b0d3ed597d93c0af78787ef27ca15a4a4212b6f02156897b988f98c27587d9d73f297c1b
+  data.tar.gz: 4d6725aae2d9c428f9dcfbc2128918ca2bf43c626a26d235af7d183cb04d17252b8f1333ad125202e3c2fe8ef1a5880594bf68e1e52dfd3122e7d014116efc8b

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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

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,17 +22,18 @@ 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'

data/lib/jekyll_outline/version.rb

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

data/lib/outline_tag.rb

@@ -186,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.5
+  version: 1.2.6
 platform: ruby
 authors:
 - Mike Slinn
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-20 00:00:00.000000000 Z
+date: 2025-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -102,8 +101,7 @@ 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.3
 specification_version: 4
 summary: Jekyll tag plugin that creates a clickable table of contents.
 test_files: