jekyll_outline 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 464b66396b0abd3369669875ca6b2be97b51e7823e31d5fa163b4248afc0dc50
-  data.tar.gz: 1253ef8b8218d0c4f76cb66d5f79ef0bc4fef48cec8d057ef33b0af0411e352f
+  metadata.gz: f19cd3e8a114d272e1a25858375c4f9cae27be24c8c7df0794340efc43311cf4
+  data.tar.gz: 2c9502f7e10ed8bcdf992b4f7761a597c16d154c4f7889b130ee72d4197ee9ab
 SHA512:
-  metadata.gz: 96bf42bd9e24050bf05fc9c5d1a2094383f2dd3853c301da97ce5e8276969de31ddc98cc5102f3288e46cb84ae9032a2e8c40813993445d837a5a60ffd4b0559
-  data.tar.gz: 56facfe2c9305b0945ad1d315018b078f1a0402b1c91655ea01a2741f9f39d2975bce5de31eb84490126f4b19700e98a617a84d61a17fbc27a225cc750b941ba
+  metadata.gz: cd40905342095e621420f8255ab6b59e935559d2b7c744ac6c474dd47c993eaf3a4cd79ac3c0a2983977690485b5feb108aff6b2f222ac6a9ad26523cde88790
+  data.tar.gz: 4dde939dffacc17793cb972adec4bf4efaf17fff24251592e517efcb6f8f68823322ade76df90dd55aa29e50d15fa673afc9e13e623a2adf088181d6d263c32b

data/.rubocop.yml

@@ -25,14 +25,23 @@ Layout/HashAlignment:
 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,6 @@
+## 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).
 

data/README.md

@@ -16,21 +16,52 @@ 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>
@@ -38,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 %}
@@ -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,13 +112,15 @@ 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.
 
-The images are wrapped within an invisible `div` so the web page does not jump around as the images are loaded.
+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"
@@ -118,6 +152,8 @@ 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)
 
@@ -129,8 +165,10 @@ More information is available on
 
 ## 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`.
 
+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
@@ -194,6 +232,11 @@ 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
 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/jekyll/3000-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',

data/lib/jekyll_outline/version.rb

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

data/lib/outline_tag.rb

@@ -24,7 +24,7 @@ module OutlineTag
     end
   end
 
-  class OutlineTag < JekyllSupport::JekyllBlock
+  class OutlineTag < JekyllSupport::JekyllBlock # rubocop:disable Metrics/ClassLength
     include JekyllOutlineVersion
 
     FIXNUM_MAX = (2**((0.size * 8) - 2)) - 1
@@ -33,13 +33,17 @@ module OutlineTag
       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
 
-      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
@@ -59,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
+    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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_outline
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Mike Slinn
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-04-06 00:00:00.000000000 Z
+date: 2023-05-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -75,14 +75,14 @@ files:
 - spec/outline_spec.rb
 - spec/spec_helper.rb
 - spec/status_persistence.txt
-homepage: https://www.mslinn.com/jekyll/3000-jekyll-plugins.html#outline
+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/jekyll/3000-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+