jekyll_outline 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3efed359f1a20b1b255dff89ae002fc464162ae11f2ffbaaf2463cfdce031cfa
-  data.tar.gz: ba1a9378d1424cc673fb75bcc0bd8a0758b6861facb66474a24dad19a568940d
+  metadata.gz: f19cd3e8a114d272e1a25858375c4f9cae27be24c8c7df0794340efc43311cf4
+  data.tar.gz: 2c9502f7e10ed8bcdf992b4f7761a597c16d154c4f7889b130ee72d4197ee9ab
 SHA512:
-  metadata.gz: a1147061ffb817c16a64002a8b300380943a319eb44c0077c54f76b9d6cd2f6d4500778fd369deed65f7256357feb5140129bda26be08344b2149bce00861b06
-  data.tar.gz: d03d8db73e90f7c39aa5b6f8f379ab2cfe8d47dae740e2e0a9d6355ac486713db28e02af07145e33279cba2d9aba982ae10f07c08087c192c953851d7fd51f25
+  metadata.gz: cd40905342095e621420f8255ab6b59e935559d2b7c744ac6c474dd47c993eaf3a4cd79ac3c0a2983977690485b5feb108aff6b2f222ac6a9ad26523cde88790
+  data.tar.gz: 4dde939dffacc17793cb972adec4bf4efaf17fff24251592e517efcb6f8f68823322ade76df90dd55aa29e50d15fa673afc9e13e623a2adf088181d6d263c32b

data/.rubocop.yml

@@ -1,6 +1,8 @@
 require:
- - rubocop-rspec
+ - rubocop-md
+ - rubocop-performance
  - rubocop-rake
+ - rubocop-rspec
 
 AllCops:
   Exclude:
@@ -17,19 +19,29 @@ Gemspec/RequireMFA:
   Enabled: false
 
 Layout/HashAlignment:
-  Enabled: false
+  EnforcedColonStyle: table
+  EnforcedHashRocketStyle: table
 
 Layout/LineLength:
   Max: 150
 
+Metrics/AbcSize:
+  Max: 30
+
 Metrics/BlockLength:
   Exclude:
     - jekyll_outline.gemspec
   Max: 40
 
+Metrics/CyclomaticComplexity:
+  Max: 20
+
 Metrics/MethodLength:
   Max: 30
 
+Metrics/PerceivedComplexity:
+  Max: 20
+
 Naming/FileName:
   Exclude:
     - Rakefile

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 1.2.0 / 2023-04-23
+  - Added optional `field` parameter.
+
+## 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.

data/README.md

@@ -6,30 +6,62 @@
 
 
 ## 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:
 
-    $ bundle install
+    $ bundle
+
+
+## Fields
+By default, each displayed entry consists of a document title,
+wrapped within an <a href> 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:
+`draft`, `categories`, `description`, `date`, `last_modified` or `last_modified_at`, `layout`, `order`, `title`, `slug`, `ext`, `tags`, and `excerpt`.
+
+Specify the fields like this:
+
+```
+{% outline fields="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.
+
+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.
+Tokens are separated by white space.
 
 
 ### 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:
+See the sections of [`demo/assets/css/styles.css`](/mslinn/jekyll_outline/blob/master/demo/assets/css/style.css#L252-L315) as shown:
 
 ```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
-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:
+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:
 
 ```html
 <script>
@@ -37,7 +69,8 @@ This project's `outline_js` tag returns the Javascript necessary to position ima
 </script>
 ```
 
-If passed the `wrap_in_script_tag` parameter, it wraps the JavaScript in `<script></script>`:
+If passed the `wrap_in_script_tag` parameter, it wraps the JavaScript in `<script></script>`.
+Use the tag this way:
 
 ```html
 {% outline_js wrap_in_script_tag %}
@@ -45,7 +78,6 @@ If passed the `wrap_in_script_tag` parameter, it wraps the JavaScript in `<scrip
 
 
 ## Explanation
-
 Given an outline that looks like this:
 ```html
 {% outline stuff %}
@@ -57,9 +89,9 @@ Given an outline that looks like this:
 
 ...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**
+ - `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
@@ -80,12 +112,17 @@ Then links to the pages in the `stuff` collection's pages are interleaved into t
 </div>
 ```
 
-The JavaScript searches for images in the current page that were created by the [`img`](https://github.com/mslinn/jekyll_img) tag plugin,
+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.
+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.
+
+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.
 ```html
+<div style="display: none;">
 {% img align="right"
   id="outline_0"
   size="quartersize"
@@ -107,6 +144,7 @@ Note that leading zeros in the first column above are not present in the `id`s b
   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.
@@ -114,21 +152,23 @@ The images can be located anywhere on the page; they will be relocated appropria
 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.
 
-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.
-
-Install development dependencies like this:
-```
-$ BUNDLE_WITH="development" bundle install
-```
+Then you can run `bin/console` for an interactive prompt that will allow you to experiment using `irb`.
 
+### Build and Install Locally
 To build and install this gem onto your local machine, run:
 ```shell
 $ bundle exec rake install
@@ -150,16 +190,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)
 
@@ -178,10 +230,13 @@ To release a new version,
 
 
 ## Contributing
-
 Bug reports and pull requests are welcome on GitHub at https://github.com/mslinn/jekyll_outline.
 
+1. Fork the project
+2. Create a descriptively named feature branch
+3. Add your feature
+4. Submit a pull request
 
-## License
 
+## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/jekyll_outline.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |spec|
     '.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.homepage = 'https://www.mslinn.com/jekyll_plugins/jekyll_outline.html'
   spec.license = 'MIT'
   spec.metadata = {
     'allowed_push_host' => 'https://rubygems.org',
@@ -36,5 +36,5 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency 'jekyll', '>= 3.5.0'
   spec.add_dependency 'jekyll_draft', '~> 1.1.0'
-  spec.add_dependency 'jekyll_plugin_support', '~> 0.5.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.1.0'.freeze
+  VERSION = '1.2.0'.freeze
 end

data/lib/outline_tag.rb

@@ -20,25 +20,32 @@ module OutlineTag
     end
 
     def to_s
-      "  <h3 class='post_title clear' id=\"title_#{order}\">#{title}</h3>"
+      "  <h3 class='post_title clear' id=\"title_#{@order}\">#{@title}</h3>"
     end
   end
 
-  class OutlineTag < JekyllSupport::JekyllBlock
+  class OutlineTag < JekyllSupport::JekyllBlock # rubocop:disable Metrics/ClassLength
     include JekyllOutlineVersion
 
     FIXNUM_MAX = (2**((0.size * 8) - 2)) - 1
 
     def render_impl(text)
-      @collection_name = argument_string.strip
+      headers = make_headers(super) # Process the block content.
+
+      @helper.gem_file __FILE__
+      @fields = @helper.parameter_specified?('fields')&.split(' ') || ['title']
+      @logger.info { "@fields are: #{@fields}" }
+      @collection_name = @helper.remaining_markup
       abort 'OutlineTag: collection_name was not specified' unless @collection_name
 
-      headers = make_headers(super) # Process the block content.
-      collection = headers + obtain_docs(@collection_name)
+      @docs = obtain_docs(@collection_name)
+      collection = headers + @docs
+
       <<~HEREDOC
         <div class="outer_posts">
-        #{make_entries(collection).join("\n")}
+        #{make_entries collection}
         </div>
+        #{@helper.attribute if @helper.attribution}
       HEREDOC
     end
 
@@ -56,35 +63,67 @@ module OutlineTag
     # @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
+    def make_entries(collection)
       sorted = collection.sort_by(&obtain_order)
-      pruned = remove_empty_headers(sorted)
+      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"
+        handle entry
+      end
+      result << "    </div>\n  </div>" if @section_state == :in_body
+      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 = "<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)
+        visible_line = handle_entry entry
+        result = "    <span>#{date}</span> <span><a href='#{entry.url}'>#{visible_line.strip}</a>#{draft}</span>"
+        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
-          @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
+        else
+          result += "#{field} "
         end
       end
-      result << "    </div>\n  </div>" if @section_state == :in_body
       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

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.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Mike Slinn
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-03-15 00:00:00.000000000 Z
+date: 2023-05-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.5.0
+        version: 0.6.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.5.0
+        version: 0.6.0
 description: 'Jekyll tag plugin that creates a clickable table of contents.
 
   '
@@ -74,14 +74,15 @@ files:
 - 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_plugins/jekyll_outline.html
 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_plugins/jekyll_outline.html
   source_code_uri: https://github.com/mslinn/jekyll_outline
 post_install_message: |2+
 
@@ -108,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
 ...