jekyll_draft 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d833da47df880dd897725f84046568f02e24e88a2dff0d14ec8b3c86e0d24265
-  data.tar.gz: 1bb026e448058d47f96f0841bd1a80bc8c217010cc00bfa628ff708bd34d2a8d
+  metadata.gz: 86ee1458ee28aab9d7f99d46deeff46e98a795cb6d3737a84b2e0e9f17f68632
+  data.tar.gz: a1abc81b94ccfdc3ee46ec312324d0d086567bbabcaa40784fca3d8d1c8415e4
 SHA512:
-  metadata.gz: b5bf1572f2ac67123110e0c8cfd536c2b19d8c8f796468a0c0b18a39f5603909b70a29af4a126390980f631d61d7e32ea63566ec92603efaaa95e73306b6a180
-  data.tar.gz: b07fdb3abdba168e1a207a80382f6192ae142b23358f3a73d6dccfd95a24384e25932f4daa9f794942da4c1891d73ca91e5bb0c684aa5a2d81043019d5b1d4f5
+  metadata.gz: a70c60fa72cfb2dc9a8842e5b54ec9f0dec2746976edd90ed174990dcf24a14aadf801246258c257ac375c68fd72a518c9e9bc55bbbf975498c43d09a5a94774
+  data.tar.gz: 030ef794350d158b43395d957ce6f080c8497dde0db7005dacc96dd2900cacbc712c353addf1cb2443f8261e2e2fee471d9e1f39c7f7c9a758776f23a7ca56d5

data/.rubocop.yml

@@ -55,7 +55,7 @@ Metrics/BlockLength:
 Metrics/ClassLength:
   Exclude:
     - spec/**/*
-  Max: 50
+  Max: 60
 
 Metrics/CyclomaticComplexity:
   Max: 20
@@ -73,6 +73,9 @@ Naming/FileName:
 RSpec/ExampleLength:
   Max: 20
 
+RSpec/IndexedLet:
+  Enabled: false
+
 RSpec/MultipleExpectations:
   Max: 15
 

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Change Log
 
+## 2.1.0 / 2025-02-07
+
+* Added ability to return a page in any collection, or those not in a collection,
+  whose path uniquely contains a string is a draft or not.
+* Uses the binary search added in `jekyll_all_collections` v0.4.0 to find `APage`s whose `href` matches a suffix.
+* Added the `bin/release_port` script that kills hung processes being debugged
+
+
+## 2.0.2 / 2024-07-24
+
+* Compatible with `jekyll_plugin_support` v1.0.0
+
+
+## 2.0.1 / 2024-02-07
+
+* Added Jekyll inline tag: `unless_draft_only`.
+* Added method `draft_only?` to API module `Jekyll::Draft`.
+
+
 ## 2.0.1 / 2023-11-30
 
 * Jekyll block tags: `if_draft` and `unless_draft`.

data/README.md

@@ -1,24 +1,39 @@
 # jekyll_draft [![Gem Version](https://badge.fury.io/rb/jekyll_draft.svg)](https://badge.fury.io/rb/jekyll_draft)
 
-This Jekyll plugin provides the following:
-
-* Jekyll block tags: `if_draft` and `unless_draft`.
-* Jekyll inline tags: `else_if_not_draft` and `else_if_draft`.
-  These are meant for use within `if_draft` and `unless_draft`, respectively.
-  Both of them are identical; they are both provided so usage seems natural.
-* Jekyll inline tag `draft_html`, which generates HTML that indicates if the document it is embedded within is a draft.
+Jekyll has various ways of specifying that a page or document will be
+visible when the website is published in `production` mode.
+The Jekyll documentation is scattered and incomplete regarding detecting draft pages and documents.
+This plugin provides standard ways for detecting draft pages and documents.
+
+`Jekyll_draft` provides the following:
+
+* Jekyll block tags: `if_draft`, `if_page_draft`, `unless_draft`, and `unless_page_draft`.
+* Jekyll inline tags: `else_if_draft`, `else_if_page_draft`,
+  `else_unless_draft` and `else_unless_page_draft`.
+  These are meant for use within the above block tags.
+  They are all identical; they are provided so usage seems natural.
+* Jekyll inline tag `draft_html`, which generates HTML that indicates if
+  the enclosing document or a specified is a draft.
 * Liquid filters:
   * `is_draft` returns a boolean indicating if the document passed to it is a draft.
+  * `page_match_is_draft` is like `is_draft`, but works on other pages.
   * `draft_html` returns the same string the `draft_html` tag returns,
-    indicating if the document passed to it is a draft.
+    indicating if the <code>Jekyll::Page</code> passed to the filter is a draft.
+  * `page_match_draft_html` is like `draft_html` but works on other pages.
+    It accepts a string that will be matched against
+    [`APage.href`](https://github.com/mslinn/jekyll_all_collections?tab=readme-ov-file#the-apage-class)
+    values in <code>site.everything</code>.
 * Module `Jekyll::Draft` defines an API that your plugin can call.
   It has the following methods:
-  * `draft?` returns a boolean indicating if the document passed to it is a draft.
-  * `draft_html` returns the same string that `draft_html` tag returns;
-    the response indicates if the document passed to it is a draft.
+  * `draft?` returns a boolean indicating if the object passed to it is a draft.
+    It handles `AllCollectionsHooks::APage` instances, `Jekyll::Page` instances,
+    and `Jekyll::Document` instances.
+  * `draft_html` accepts the same parameter types as `draft?`,
+    and returns the same string that `draft_html` tag returns.
+    The response indicates if the document passed to it is a draft.
+  * `page_match` returns the `APage` whose `href` uniquely ends with the string passed to it.
   * `root` returns the path to the root of the collection that the document passed to it is a member of.
-    This method is not functionally related to Jekyll draft documents;
-    it should be packaged separately ... maybe one day...
+    This method is not functionally related to Jekyll draft documents.
 
 The difference between the tag called `draft_html` and the filter of the same name
 is that the tag only works on the document that it is embedded in,
@@ -28,11 +43,27 @@ Both the tag and the filter call the same API methods defined in the `Jekyll::Dr
 More information is available on [Mike Slinn&rsquo;s website](https://www.mslinn.com/jekyll_plugins/jekyll_draft.html).
 
 
+## Front Matter
+
+To mark a blog as a draft, put it in the `_drafts` directory.
+
+To mark any other article as a draft, add the following to its front matter:
+
+```text
+---
+published: false
+---
+```
+
+
 ## Demo
 
-The [demo](demo) subdirectory has working examples of this Jekyll plugin's functionality
+The [demo/](demo) subdirectory has working examples of this Jekyll plugin's functionality
 in a demonstration website.
-To run the demo, type:
+It can be used to debug the plugin or it can run freely.
+Please examine the <code>HTML</code> files in the demo to see how the plugin works.
+
+To run the demo freely from the command line, type:
 
 ```console
 $ demo/_bin/debug -r
@@ -56,50 +87,109 @@ so you can learn how to write Jekyll pages that include this functionality.
 
 ### For Use In A Jekyll Website
 
-Add the CSS found in [`demo/assets/css/jekyll_draft.css`](demo/assets/css/jekyll_draft.css) to your Jekyll layout(s).
+1. Add the CSS found in [`demo/assets/css/jekyll_draft.css`](demo/assets/css/jekyll_draft.css) to your Jekyll layout(s).
 
-Add the following to your Jekyll website's `Gemfile`, within the `jekyll_plugins` group:
+2. Add the following to your Jekyll website's `Gemfile`, within the `jekyll_plugins` group:
 
-```ruby
-group :jekyll_plugins do
-  gem 'jekyll_draft', '>2.0.0' # v2.0.0 was a dud, do not use it
-end
-```
+   ```ruby
+   group :jekyll_plugins do
+     gem 'jekyll_all_collections', '>= 0.3.8'
+     gem 'jekyll_draft', '>=2.1.0'
+   end
+   ```
 
-And then type:
+3. Type:
 
-```shell
-$ bundle
-```
+   ```shell
+   $ bundle
+   ```
+
+4. Restart Jekyll.
 
 
 ### For Use In a Gem
 
-Add the following to your gem&rsquo;s `.gemspec`:
+1. Add the following to your gem&rsquo;s `.gemspec`:
 
-```ruby
-spec.add_dependency 'jekyll_draft', '>2.0.0' # v2.0.0 was a dud, do not use it
-```
+   ```ruby
+   spec.add_dependency 'jekyll_all_collections', '>= 0.3.8'
+   spec.add_dependency 'jekyll_draft', '>=2.1.0'
+   ```
 
-And then type:
+2. Type:
 
-```shell
-$ bundle
+   ```shell
+   $ bundle
+   ```
+
+
+## Configuration
+
+### _config.yml
+
+The default settings run more quickly than id `verify_unique_match` is enabled,
+which guarantee that no broken internal links exist.
+If a Jekyll web page has hundreds or thousands of pages,
+site generation can take many minutes if `verify_unique_match` is enabled.
+
+The following settings are the default values for `_config.yml`.
+They apply to all tags defined by this plugin
+(`if_draft`, `unless_draft`, `if_page_draft`, `unless_page_draft`)
+except `draft_html` tag, which does not reference these settings:
+
+```yaml
+if_draft:
+  error_if_no_match: true
+  verify_unique_match: false
 ```
 
+### Environment Variables
+
+Environment variables override `_config.yml` settings.
+
+* `if_draft_error_if_no_match` overrides `if_draft.error_if_no_match`
+* `if_draft_verify_unique_match` overrides `if_draft.verify_unique_match`
+
+
+## Usage in a Web Page
+
+This section documents the usage of the inline and block tags described [above](#top).
+
+The `if_draft` and `if_page_draft` block tags act as `if-then` or `if-then-else` programming constructs.
+Draft documents only exist in development mode.
+In production mode, there is no way to programmatically detect if a draft document exists in development mode.
+
+Thus, `if_draft` and `if_page_draft` actually mean "if in development mode and the document is a draft".
+
+Furthermore, `unless_draft` and `unless_page_draft` actually mean "if in production mode or the document is not a draft".
+These block tags act as Ruby
+[`unless-then`](https://rubystyle.guide/#unless-for-negatives) and
+[`unless-then-else`](https://rubystyle.guide/#no-else-with-unless) programming constructs.
+
+The `draft_html` inline tag generates HTML that indicates if a page is a draft or not.
 
-## Usage
 
 ### `if_draft` and `unless_draft` Block Tags
 
-The `if_draft` block tag acts as an `if-then` or an `if-then-else` programming construct.
+These tags consider the status of the document that the tag is embedded in.
+
+The <code>if_draft</code> block tag acts as an <code>if-then</code> or an <code>if-then-else</code> programming construct.
+
+The following generates `<p>This is a draft document!</p>`
+if the document it is embedded in is a draft,
+and the Jekyll website generation was performed in development mode:
 
 ```html
 {% if_draft %}
-  <p>This is a draft document!</p>
+  <p>This is a draft document.</p>
 {% endif_draft %}
 ```
 
+The following enhances the previous example by generating `<p>This is not a draft document!</p>`
+if the document this code is embedded in is not a draft.
+The message for the else clause is generated for documents that are not drafts,
+regardless of whether Jekyll is in `production` or `development` mode.
+
 ```html
 {% if_draft %}
   <p>This is a draft document!</p>
@@ -108,8 +198,9 @@ The `if_draft` block tag acts as an `if-then` or an `if-then-else` programming c
 {% endif_draft %}
 ```
 
-The `unless_draft` block tag acts as a Ruby [unless-then](https://rubystyle.guide/#unless-for-negatives) or
-an [unless-then-else](https://rubystyle.guide/#no-else-with-unless) programming construct.
+The `unless_draft` block tag switches the then and else clauses of the `if_draft` block tag.
+It acts as a Ruby [<code>unless-then</code>](https://rubystyle.guide/#unless-for-negatives) or
+[<code>unless-then-else</code>](https://rubystyle.guide/#no-else-with-unless) programming construct.
 
 ```html
 {% unless_draft %}
@@ -120,68 +211,161 @@ an [unless-then-else](https://rubystyle.guide/#no-else-with-unless) programming
 ```html
 {% unless_draft %}
   <p>This is not a draft document!</p>
-{% else_if_draft %}
+{% else_unless_draft %}
   <p>This is a draft document!</p>
 {% endunless_draft %}
 ```
 
-You can use the keywords `else_if_draft` and `else_if_not_draft` interchangeably.
-They are actually made by registering the same code twice with different subclass names.
+
+### `if_page_draft` and `unless_page_draft` Block Tags
+
+These tags consider the status of the document whose url uniquely includes the specified string.
+
+An error is raised in `development` mode if no page exists whose URL contains the matching string.
+
+The following generates `<p><code>/directory/blah_blah.html</code> is a draft document!</p>`
+if the rendered page with a url that ends with the string `blah.html` in is a draft,
+and the Jekyll website generation was performed in development mode,
+and the only page with a matching URL is <code>/directory/blah_blah.html</code>:
+
+```html
+{% if_page_draft blah.html %}
+  <p><code>{{matched_page.url}}</code> is a draft document.</p>
+{% endif_page_draft %}
+```
+
+Notice the reference to a Jekyll variable called `matched_page` in the above example.
+It is set to the Jekyll `Page` whose `url` uniquely matched the string following the `if_page_draft` tag.
+This variable is only defined for `development` mode within the `then` clause of the `if_page_draft` tag,
+and for the `else` clause of the `unless_page_draft` block tag.
+
+You can specify any `Page` attribute with `matched_page`, for example {{matched_page.title}}.
+
+The following generates `<p><code>/directory/blah_blah.html</code> is not a draft document!</p>`
+if the `/directory/blah_blah.html` in is a draft document,
+and the Jekyll website generation was performed in development mode:
+
+```html
+{% unless_page_draft blah.html %}
+  <p><code>{{matched_page.url}}</code> is not a draft document!</p>
+{% endunless_draft %}
+```
+
+The following shows how to specify `else` clauses for `if_page_draft` and `unless_page_draft`.
+Note that the `if_draft` else clause activates in `production` mode regardless of whether a page matches or not,
+so you should not reference `matched_page` in an else clause without testing
+[`jekyll.environment`](https://jekyllrb.com/docs/configuration/environments/).
+Instead, you can reference the match string with `{{path_portion}}`:
+
+```html
+{% if_page_draft blah.html %}
+  <p><code>{{matched_page.url}}</code> is a draft document!</p>
+{% else_if_page_draft %}
+  {% if jekyll.environment == 'development' %}
+    <p><code>{{matched_page.url}}</code> is not a draft document!</p>
+  {% else %}
+    <p>Production mode cannot detect if <code>{{path_portion}}</code> matches a draft document or not.</p>
+  {% endif %}
+{% endif_page_draft %}
+```
+
+Similarly, the `unless_draft` then clause activates in `production` mode regardless of whether a page matches or not,
+so you should not reference `matched_page` in a then clause without testing
+[`jekyll.environment`](https://jekyllrb.com/docs/configuration/environments/).
+
+```html
+{% unless_page_draft blah.html %}
+  {% if jekyll.environment == 'development' %}
+    <p>The page whose URL contains <code>{{path_portion}}</code> is not a draft document!</p>
+  {% else %}
+    <p>Production mode cannot detect if <code>{{path_portion}}</code> matches a draft document or not.</p>
+  {% endif %}
+{% else_unless_page_draft %}
+  <p><code>{{matched_page.url}}</code> is a draft document!</p>
+{% endunless_page_draft %}
+```
+
+As with the `if_page_draft` and `unless_page_draft` examples, the above example
+references scoped Jekyll variables called `matched_page` and `path_portion`.
+These variables are only defined within the body of `if_page_draft` and `unless_page_draft` blocks.
+
+
+### Else Clauses
+
+You can use the keywords
+`else_if_draft`, `else_if_page_draft`, `else_unless_draft`, and `else_unless_page_draft` interchangeably.
+They are actually made by registering the same code multiple times with different subclass names.
 Use the keyword that makes the most sense to you.
 
 
 ### `draft_html` Inline Tag
 
+#### Default Behavior
+
+The `draft_html` inline tag can return the status of the page it is embedded in, or any other page that exists.
+Recall that draft pages do not exist in `production` mode.
+
 Here is an example of embedding the `draft_html` inline tag into an HTML document:
 
 ```html
   <p>Is this a draft document? Look here to see: {% draft_html %}</p>
 ```
 
-By default, `draft_html` emits ` <i class='jekyll_draft>Draft</i>` if the document is a draft,
+By default, if the document is a draft, and the Jekyll website generation was performed in development mode,
+`draft_html` emits ` <i class='jekyll_draft>Draft</i>`,
 otherwise it does not emit anything.
 
-You can change this behavior several ways:
-
-* Add the `published_output` parameter to specify the HTML that should be emitted if the document is not a draft.
-The default message will continue to be output for draft documents when the `published_output` parameter is used.
-
-  ```html
-  {% draft_html published_output="<p>Not a draft</p>" %}
-  ```
+<p>You can change this behavior in several ways:</p>
 
-* Add the `draft_output` parameter to specify the HTML that should be emitted if the document is a draft:
+* Add the <code>draft_output</code> parameter to specify the HTML that should be
+  emitted if the document is a draft,
+  and the Jekyll website generation was performed in development mode:
 
-  ```html
+  ```text
   {% draft_html
     draft_output="<p>Is a draft</p>"
   %}
+
   {% draft_html
     draft_output="<p>Is a draft</p>"
     published_output="<p>Not a draft</p>"
   %}
   ```
 
-* Add the `draft_class` parameter to specify the CSS class that should be added
-  to the emitted HTML if the document is a draft:
+* Add the <code>published_output</code> parameter to specify the HTML that
+  should be emitted if the document is not a draft.
+  The default message will continue to be output for draft documents when the
+  <code>published_output</code> parameter is used.
 
-  ```html
+  ```text
+  {% draft_html published_output="<p>Not a draft</p>" %}
+  ```
+
+* Add the <code>draft_class</code> parameter to specify the CSS class that should be added
+  to the emitted HTML if the document is a draft,
+  and the Jekyll website generation was performed in development mode:
+
+  ```text
   {% draft_html draft_class="my_draft_class" %}
+
   {% draft_html
     draft_class="my_draft_class"
     published_output="<p>Not a draft</p>"
   %}
   ```
 
-* Add the `draft_style` parameter to specify the CSS class that should be added
-  to the emitted HTML if the document is a draft:
+* Add the <code>draft_style</code> parameter to specify the CSS class that should be added
+  to the emitted HTML if the document is a draft,
+  and the Jekyll website generation was performed in development mode:
 
-  ```html
+  ```text
   {% draft_html draft_style="font-size: 24pt;" %}
+
   {% draft_html
     draft_class="my_draft_class"
     draft_style="font-size: 24pt;"
   %}
+
   {% draft_html
     draft_class="my_draft_class"
     draft_style="font-size: 24pt;"
@@ -190,31 +374,149 @@ The default message will continue to be output for draft documents when the `pub
   ```
 
 
-### Filters
+#### Testing Another Page
 
-#### `is_draft`
+The `path_portion` option enables the `draft_html` tag to report on the draft status
+of other pages when Jekyll is in `development` mode.
+By default, an empty string is always returned when in `production` mode.
 
-This filter detects if a page is invisible when published in `production` mode,
-and either returns `true` or `false`.
+```html
+<p>
+  Is <code>/directory/blah_blah.html</code> a draft document?
+  Look here to see: {% draft_html path_portion='blah.html' %}
+</p>
+```
+
+It might be desirable to enclose the above in a test for Jekyll mode as follows:
 
 ```html
-{{ page | is_draft }} => true
+{% if jekyll.environment == "development" %}
+  <p>
+    Is <code>/directory/blah_blah.html</code> a draft document?
+    Look here to see: {% draft_html path_portion='blah.html' %}
+  </p>
+{% endif %}
 ```
 
 
+#### Additional Options
+
+In addition to the `path_portion` option, the following can be also be specified:
+
+* Add the `published_output` parameter to specify the HTML that should be emitted if the document is not a draft,
+and the Jekyll website generation was performed in development mode.
+The default message will continue to be output for draft documents when the `published_output` parameter is used.
+
+  ```html
+  {% draft_html published_output="<p>Not a draft</p>" %}
+  ```
+
+* Add the `draft_output` parameter to specify the HTML that should be emitted if the document is a draft,
+and the Jekyll website generation was performed in development mode:
+
+  ```html
+  {% draft_html
+       draft_output="<p>Is a draft</p>"
+  %}
+  {% draft_html
+       draft_output="<p>Is a draft</p>"
+       published_output="<p>Not a draft</p>"
+  %}
+  ```
+
+* Add the `draft_class` parameter to specify the CSS class that should be added
+  to the emitted HTML if the document is a draft
+  and the Jekyll website generation was performed in development mode:
+
+  ```html
+  {% draft_html draft_class="my_draft_class" %}
+  {% draft_html
+       draft_class="my_draft_class"
+       published_output="<p>Not a draft</p>"
+  %}
+  ```
+
+* Add the `draft_style` parameter to specify the CSS class that should be added
+  to the emitted HTML if the document is a draft,
+  and the Jekyll website generation was performed in development mode:
+
+  ```html
+  {% draft_html draft_style="font-size: 24pt;" %}
+  {% draft_html
+       draft_class="my_draft_class"
+       draft_style="font-size: 24pt;"
+  %}
+  {% draft_html
+       draft_class="my_draft_class"
+       draft_style="font-size: 24pt;"
+       published_output="<p>Not a draft</p>"
+  %}
+  ```
+
+
+### Liquid Filters
+
 #### `draft_html`
 
-This filter generates HTML to display if a page is invisible when published in `production` mode.
-If the page is not a draft then the empty string is returned.
-The generated HTML for draft pages is:<br>
+By default, the draft_html Liquid filter generates HTML if a page is invisible when published in `production` mode.
+If the page is not a draft, then the empty string is returned.
+
+The optional parameters for the `draft_html` inline tag are not available for
+use with the `draft_html` filter.
+
+The default generated HTML for draft pages is:<br>
 `" <i class='jekyll_draft'>Draft</i>"`
 
+Invoke the filter like the following; the output depends on whether the document is a draft:
+
 ```html
 {{ page | draft_html }} => " <i class='jekyll_draft'>Draft</i>"
 ```
 
-The optional parameters for the `draft_html` inline tag are not available for
-use with the `draft_html` filter.
+Here is a code snippet that shows the <code>draft_html</code> filter in use:
+
+```html
+{% assign docs = site.myCollection | sort: "order" %}
+<ol id="titles">
+{% for doc in docs %}
+  <li>
+    <a href="{{doc.url}}" class="title">{{doc.title}}</a>{{ doc | draft_html }}
+  </li>
+{% endfor %}
+</ol>
+```
+
+
+#### `page_match_draft_html`
+
+This filter detects if the page whose URL uniquely contains a string is
+invisible when published in `production` mode,
+and returns the same strings that `draft_html` returns.
+
+```html
+{{ "unpublished.html" | page_match_draft_html }}
+```
+
+
+#### `is_draft`
+
+This filter detects if a page is invisible when published in `production` mode,
+and returns `true` or `false`.
+
+```html
+{{ page | is_draft }} <!-- true for draft documents in development mode -->
+```
+
+
+#### `page_match_is_draft`
+
+This filter detects if the page whose URL uniquely contains a string is
+invisible when published in `production` mode,
+and returns `true` or `false`.
+
+```html
+{{ "unpublished.html" | page_match_is_draft }}
+```
 
 
 ### Invoking From Another Jekyll Plugin
@@ -222,12 +524,38 @@ use with the `draft_html` filter.
 ```ruby
 require 'jekyll_draft'
 
-puts 'Found a draft' if Jekyll::Draft.is_draft post
+puts 'Found a draft' if Jekyll::Draft.draft? post
 
 draft = Jekyll::Draft.draft_html post
 ```
 
 
+### Usage in a Plugin
+
+The methods in `lib/draft_html.rb` can be invoked by qualifying them with `Jekyll::Draft`.
+Here is a complete example of a Jekyll Support plugin that displays an indication of whether the page is a draft or not:
+
+```ruby
+require 'jekyll_plugin_support'
+
+module MyPluginTag
+  MyPluginError = JekyllSupport.define_error
+  PLUGIN_NAME = 'my_plugin'.freeze
+  VERSION = '0.1.0'.freeze
+
+  class MyPluginTag < JekyllSupport::JekyllTag
+    def render_impl
+      <<~HEREDOC
+        Draft or not? #{Jekyll::Draft.draft_html(@page)}
+      HEREDOC
+    end
+  end
+end
+
+Liquid::Template.register_tag(MyPluginTag::PLUGIN_NAME, MyPluginTag::MyPluginTag)
+PluginMetaLogger.instance.info { "Loaded #{MyPluginTag::PLUGIN_NAME} v#{MyPluginTag::VERSION} plugin." }
+```
+
 
 ## Development
 

data/jekyll_draft.gemspec

@@ -3,15 +3,15 @@ require_relative 'lib/jekyll_draft/version'
 Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   github = 'https://github.com/mslinn/jekyll_draft'
 
-  spec.authors = ['Mike Slinn']
-  spec.bindir = 'exe'
+  spec.authors     = ['Mike Slinn']
+  spec.bindir      = 'exe'
   spec.description = <<~END_OF_DESC
     This Jekyll filter detects draft documents.
   END_OF_DESC
-  spec.email = ['mslinn@mslinn.com']
-  spec.files = Dir['.rubocop.yml', 'LICENSE.*', 'Rakefile', '{lib,spec}/**/*', '*.gemspec', '*.md']
+  spec.email    = ['mslinn@mslinn.com']
+  spec.files    = Dir['.rubocop.yml', 'LICENSE.*', 'Rakefile', '{lib,spec}/**/*', '*.gemspec', '*.md']
   spec.homepage = 'https://www.mslinn.com/jekyll_plugins/jekyll_draft.html'
-  spec.license = 'MIT'
+  spec.license  = 'MIT'
   spec.metadata = {
     'allowed_push_host' => 'https://rubygems.org',
     'bug_tracker_uri'   => "#{github}/issues",
@@ -19,18 +19,19 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
     'homepage_uri'      => spec.homepage,
     'source_code_uri'   => github,
   }
-  spec.name = 'jekyll_draft'
+  spec.name                 = 'jekyll_draft'
+  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 = 'This Jekyll filter detects draft documents.'
-  spec.test_files = spec.files.grep(%r{^(test|spec|features)/})
-  spec.version = DraftVersion::VERSION
+  spec.summary               = 'This Jekyll filter detects draft documents.'
+  spec.test_files            = spec.files.grep(%r{^(test|spec|features)/})
+  spec.version               = DraftVersion::VERSION
 
   spec.add_dependency 'jekyll', '>= 3.5.0'
-  spec.add_dependency 'jekyll_plugin_support'
+  spec.add_dependency 'jekyll_plugin_support', '>=1.1.0'
 end

data/lib/{draft_html.rb → jekyll_draft/common/draft_html.rb}

@@ -1,11 +1,12 @@
-require 'jekyll_plugin_support'
-
 class DraftHtml < JekyllSupport::JekyllTag
   VERSION = '0.1.0'.freeze
   DRAFT_HTML = 'draft_html'.freeze unless defined? Else::VERSION
 
   def render_impl
-    is_draft = Jekyll::Draft.draft?(@page)
+    path_portion = @helper.parameter_specified? 'path_portion'
+    page = path_portion ? page_match(path_portion) : @page
+
+    is_draft = Jekyll::Draft.draft? page
 
     published_output = @helper.parameter_specified? 'published_output'
     return published_output if !is_draft && published_output
@@ -23,5 +24,5 @@ class DraftHtml < JekyllSupport::JekyllTag
     " <i class='jekyll_draft#{dc}'#{ds}>Draft</i>"
   end
 
-  JekyllPluginHelper.register(self, DRAFT_HTML)
+  ::JekyllSupport::JekyllPluginHelper.register(self, DRAFT_HTML)
 end

data/lib/jekyll_draft/common/else.rb

@@ -0,0 +1,35 @@
+require 'jekyll_plugin_support'
+
+class ElseBase < JekyllSupport::JekyllTag
+  VERSION = '0.1.0'.freeze
+
+  ELSE_DRAFT              = 'else_if_draft'.freeze
+  ELSE_IF_NOT_DRAFT       = 'else_if_not_draft'.freeze
+  ELSE_IF_PAGE_DRAFT      = 'else_if_page_draft'.freeze
+  ELSE_UNLESS_DRAFT       = 'else_unless_draft'.freeze
+  ELSE_UNLESS_PAGE_DRAFT  = 'else_unless_page_draft'.freeze
+
+  def render_impl
+    RECORD_SEPARATOR
+  end
+end
+
+class ElseDraft < ElseBase
+  ::JekyllSupport::JekyllPluginHelper.register(self, ELSE_DRAFT, quiet: true)
+end
+
+class ElseNotDraft < ElseBase
+  ::JekyllSupport::JekyllPluginHelper.register(self, ELSE_IF_NOT_DRAFT, quiet: true)
+end
+
+class ElsePageDraft < ElseBase
+  ::JekyllSupport::JekyllPluginHelper.register(self, ELSE_IF_PAGE_DRAFT, quiet: true)
+end
+
+class ElseUnlessDraft < ElseBase
+  ::JekyllSupport::JekyllPluginHelper.register(self, ELSE_UNLESS_DRAFT, quiet: true)
+end
+
+class ElseUnlessPageDraft < ElseBase
+  ::JekyllSupport::JekyllPluginHelper.register(self, ELSE_UNLESS_PAGE_DRAFT, quiet: true)
+end

data/lib/{filters.rb → jekyll_draft/common/filters.rb}

@@ -1,9 +1,6 @@
-require 'jekyll_plugin_logger'
-require 'yaml'
-
-# Jekyll filters that detect draft documents
+# Jekyll filters that detects if the containing page is a draft document
 module Jekyll
-  module DraftFilter
+  module ContainingPageFilters
     def is_draft(doc) # rubocop:disable Naming/PredicateName
       Draft.draft? doc
     end
@@ -17,5 +14,5 @@ module Jekyll
     end
   end
 
-  Liquid::Template.register_filter(DraftFilter)
+  Liquid::Template.register_filter(ContainingPageFilters)
 end

data/lib/jekyll_draft/common/module_functions.rb

@@ -0,0 +1,90 @@
+# Define these methods outside of the JekyllDraft class so they can be invoked externally and tested more easily
+module Jekyll
+  module Draft
+    class << self
+      attr_accessor :logger
+    end
+    Draft.logger = PluginMetaLogger.instance.new_logger(self, PluginMetaLogger.instance.config)
+
+    # @parameter doc [AllCollectionsHooks::APage|Jekyll::Page|Jekyll::Document]
+    # @return true by checking in this order:
+    #   - document is in _drafts directory, detectable by doc['draft']==true
+    #   - document front matter contains 'published: false'
+    def draft?(doc)
+      if doc.respond_to?(:data) && doc.data.respond_to?(:key?)
+        return !doc.data['published'] if doc.data.key? 'published'
+        return doc.data['draft']      if doc.data.key? 'draft'
+      end
+      if doc.respond_to?(:key?)
+        return !doc['published'] if doc.key? 'published'
+        return  doc['draft']     if doc.key? 'draft'
+      end
+
+      return doc.draft if doc.respond_to? :draft
+
+      false
+    rescue StandardError => e
+      Draft.logger.error { e.full_message }
+      false
+    end
+
+    # @param doc [Jekyll::Drops::DocumentDrop]
+    # @return HTML that indicates if a doc is a draft or not
+    def draft_html(doc)
+      return '' unless draft? doc
+
+      " <i class='jekyll_draft'>Draft</i>"
+    rescue StandardError => e
+      Draft.logger.error { e.full_message }
+      ''
+    end
+
+    # This is a computationally intense method, and really slows down site generation.
+    # TODO: implement cache in front of sorted objects containing paths and page reference
+    # This cache is also needed by compute_link_and_text in jekyll_href
+    # @return APage whose href uniquely contains path_portion,
+    #         or `path_portion` as a String for non-local URLs.
+    def page_match(path_portion, error_if_no_match: true, verify_unique_match: false)
+      return :non_local_url if path_portion.start_with? 'http:', 'https:', 'mailto'
+
+      matching_pages = if verify_unique_match
+                         ::AllCollectionsHooks.sorted_lru_files.select path_portion
+                       else
+                         match = ::AllCollectionsHooks.sorted_lru_files.find path_portion
+                         match.nil? ? [] : [match]
+                       end
+      case matching_pages.length
+      when 0
+        return '' unless error_if_no_match
+
+        Draft.logger.error do
+          "No page or asset path has a href that includes the string '#{path_portion}'"
+        end
+        exit! 1 if @error_if_no_match
+      when 1
+        matching_pages.first
+      else
+        Draft.logger.error do # :\n  #{matching_pages.map(&:href).join("\n  ")}
+          "More than one page or asset path has a href that includes the string '#{path_portion}'"
+        end
+        exit! 2 # The user should fix this problem before allowing the website to generate
+      end
+    rescue StandardError => e
+      puts e.full_message
+    end
+
+    # @return path to root of the collection that doc is a member of
+    def root(doc, site)
+      return '/index.html' unless doc.respond_to?(:collection)
+
+      collection_name = doc.collection
+      docs = site.key?(collection_name) ? site[collection_name] : site.collections[collection_name].docs
+      index = docs.find { |d| d.href.end_with? 'index.html' }
+      return index.href if index
+
+      docs.min.href
+    end
+
+    module_function :draft?, :draft_html, :page_match, :root
+  end
+end

data/lib/{if_draft.rb → jekyll_draft/containing_page/if_draft.rb}

@@ -1,5 +1,3 @@
-require 'jekyll_plugin_support'
-
 # Jekyll block tags that detect draft documents
 class DraftBase < JekyllSupport::JekyllBlock
   IF_DRAFT     = 'if_draft'.freeze
@@ -8,20 +6,20 @@ class DraftBase < JekyllSupport::JekyllBlock
 
   def render_impl(content)
     true_value, false_value, extra = content.split(RECORD_SEPARATOR)
-    raise DraftError, "Warning: More than one else clause detected" if extra
+    raise DraftError, 'Warning: More than one else clause detected' if extra
 
     if @tag_name == IF_DRAFT
-      return Jekyll::Draft.draft?(@page) ? true_value : false_value
+      return ::Jekyll::Draft.draft?(@page) ? true_value : false_value
     end
 
-    Jekyll::Draft.draft?(@page) ? false_value : true_value
+    ::Jekyll::Draft.draft?(@page) ? false_value : true_value
   end
 end
 
 class IfDraft < DraftBase
-  JekyllPluginHelper.register(self, IF_DRAFT)
+  ::JekyllSupport::JekyllPluginHelper.register(self, IF_DRAFT)
 end
 
 class UnlessDraft < DraftBase
-  JekyllPluginHelper.register(self, UNLESS_DRAFT)
+  ::JekyllSupport::JekyllPluginHelper.register(self, UNLESS_DRAFT, quiet: true)
 end

data/lib/jekyll_draft/other_page/filters.rb

@@ -0,0 +1,14 @@
+# Jekyll filters that detect if the page that uniquely contains a string is a draft document
+module Jekyll
+  module OtherPageFilters
+    def page_match_is_draft(path_portion)
+      Draft.draft? Draft.page_match path_portion
+    end
+
+    def page_match_draft_html(path_portion)
+      Draft.draft_html Draft.page_match path_portion
+    end
+  end
+
+  Liquid::Template.register_filter(OtherPageFilters)
+end

data/lib/jekyll_draft/other_page/if_draft.rb

@@ -0,0 +1,95 @@
+# Jekyll block tags that detect draft documents
+class DraftPageBase < JekyllSupport::JekyllBlock
+  IF_DRAFT     = 'if_page_draft'.freeze
+  UNLESS_DRAFT = 'unless_page_draft'.freeze
+  VERSION      = DraftVersion::VERSION.freeze
+
+  # Content has a true clause, and optionally might have an else clause
+  # Clauses can reference two variables: path_portion and matched_page
+  #   path_portion is specified as the sole argument to this block tag
+  #   matched_path is the APage with an href that uniquely includes path_portion,
+  #                or nil if no matching APage was found
+  def render_impl(content)
+    true_content, false_content, extra_content = content.split(RECORD_SEPARATOR)
+    raise DraftError, 'Warning: More than one else clause detected' if extra_content
+
+    @path_portion = @argument_string.strip
+    raise DraftError, 'Error: path_portion was not specified' unless @path_portion
+
+    configure
+
+    @matched_page = if @path_portion.start_with?('#')
+                      @page
+                    else
+                      Jekyll::Draft.page_match(@path_portion, error_if_no_match:   @error_if_no_match,
+                                                              verify_unique_match: @verify_unique_match)
+                    end
+    raise DraftError, "Error: path_portion='#{@path_portion}' does not specify a local page." if @matched_page == :non_local_url
+
+    is_draft = Jekyll::Draft.draft? @matched_page
+    clause_value = if @tag_name == IF_DRAFT
+                     is_draft ? true_content : false_content
+                   else # UNLESS_DRAFT
+                     is_draft ? false_content : true_content
+                   end
+    process_variables clause_value
+  rescue StandardError => e
+    puts e.full_message
+    exit!
+  end
+
+  private
+
+  def configure
+    tag_config = @config['if_draft']
+    if tag_config
+      @error_if_no_match = tag_config['error_if_no_match'] # defaults true
+      @error_if_no_match = @error_if_no_match ? @error_if_no_match == true : true
+
+      @verify_unique_match     = tag_config['verify_unique_match'] == true # defaults false
+    else
+      @logger.warn { "There is no entry for #{@tag_name} in _config.yml; default values were applied." }
+    end
+
+    env_var = ENV.fetch('if_draft_error_if_no_match', nil) # Environment variable overrides _config.yml setting
+    @error_if_no_match = env_var != 'false' if env_var
+
+    env_var = ENV.fetch('if_draft_verify_unique_match', nil) # Environment variable overrides _config.yml setting
+    @verify_unique_match = env_var != 'false' if env_var
+  end
+
+  def process_variables(markup)
+    return '' unless markup
+
+    path_portion = @path_portion # add this to the binding
+    matched_page = @matched_page # add this to the binding
+    _ = path_portion == matched_page # Just to keep the lint checker happy
+    markup.gsub!(/(<<([^<>]*)>>)/) do
+      token = Regexp.last_match[1] # gsub replaces token with the return value of this block
+      expression = Regexp.last_match[2]
+      if expression == 'matched_page' && matched_page.class != String
+        @logger.warn do
+          expression = 'matched_page.href'
+          <<~END_MSG
+            The expression #{token} should either specify a property, for example <<matched_page.href>>,
+            or a hash value, for example <<matched_page['title']>>.
+            The expression was modified to <<matched_page.href>> for you.
+          END_MSG
+        end
+      end
+      result = eval expression, binding # rubocop:disable Security/Eval
+      result.to_s
+    end
+    markup
+  rescue StandardError => e
+    @logger.error { e.full_message }
+  end
+end
+
+class IfPageDraft < DraftPageBase
+  JekyllSupport::JekyllPluginHelper.register(self, IF_DRAFT, quiet: true)
+end
+
+class UnlessPageDraft < DraftPageBase
+  JekyllSupport::JekyllPluginHelper.register(self, UNLESS_DRAFT, quiet: true)
+end

data/lib/jekyll_draft/version.rb

@@ -1,3 +1,3 @@
 module DraftVersion
-  VERSION = '2.0.1'.freeze
+  VERSION = '2.1.0'.freeze
 end

data/lib/jekyll_draft.rb

@@ -9,8 +9,15 @@ RECORD_SEPARATOR = "\u{241E}".freeze
 
 DraftError = JekyllSupport.define_error
 
-require_relative 'draft'
-require_relative 'if_draft'
-require_relative 'else'
-require_relative 'draft_html'
-require_relative 'filters'
+# Common code
+require_relative 'jekyll_draft/common/draft_html'
+require_relative 'jekyll_draft/common/else'
+require_relative 'jekyll_draft/common/filters'
+require_relative 'jekyll_draft/common/module_functions'
+
+# Code related to processing other pages
+require_relative 'jekyll_draft/other_page/filters'
+require_relative 'jekyll_draft/other_page/if_draft'
+
+# Code related to processing the containing page
+require_relative 'jekyll_draft/containing_page/if_draft'

data/spec/jekyll/mocks.rb

@@ -31,6 +31,7 @@ class TestLiquidContext < Liquid::Context
       "description" => "Jekyll draft demo",
       "dir"         => "/",
       "excerpt"     => nil,
+      "href"        => "/index.html",
       "layout"      => "default",
       "name"        => "index.html",
       "path"        => "index.html",

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_draft
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Mike Slinn
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-12-01 00:00:00.000000000 Z
+date: 2025-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -30,14 +29,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.1.0
 description: 'This Jekyll filter detects draft documents.
 
   '
@@ -53,12 +52,14 @@ files:
 - README.md
 - Rakefile
 - jekyll_draft.gemspec
-- lib/draft.rb
-- lib/draft_html.rb
-- lib/else.rb
-- lib/filters.rb
-- lib/if_draft.rb
 - lib/jekyll_draft.rb
+- lib/jekyll_draft/common/draft_html.rb
+- lib/jekyll_draft/common/else.rb
+- lib/jekyll_draft/common/filters.rb
+- lib/jekyll_draft/common/module_functions.rb
+- lib/jekyll_draft/containing_page/if_draft.rb
+- lib/jekyll_draft/other_page/filters.rb
+- lib/jekyll_draft/other_page/if_draft.rb
 - lib/jekyll_draft/version.rb
 - spec/draft_spec.rb
 - spec/jekyll/draft_spec.rb
@@ -92,8 +93,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key:
+rubygems_version: 3.6.3
 specification_version: 4
 summary: This Jekyll filter detects draft documents.
 test_files:

data/lib/draft.rb

@@ -1,54 +0,0 @@
-require 'jekyll_plugin_logger'
-
-# Define these methods outside of the JekyllDraft class so they can be invoked externally and tested more easily
-module Jekyll
-  module Draft
-    @logger = PluginMetaLogger.instance.new_logger(self, PluginMetaLogger.instance.config)
-
-    # @return true by checking in this order:
-    #   - document is in _drafts directory, detectable by doc['draft']==true
-    #   - document front matter contains 'published: false'
-    def draft?(doc)
-      if doc.respond_to? :data
-        return !doc.data['published'] if doc.data.key? 'published'
-        return  doc.data['draft']     if doc.data.key? 'draft'
-      end
-      if doc.respond_to? :[]
-        return !doc['published'] if doc.key? 'published'
-        return  doc['draft']     if doc.key? 'draft'
-      end
-
-      return doc.draft if doc.respond_to? :draft
-
-      false
-    rescue StandardError => e
-      @logger.error { e }
-      false
-    end
-
-    # @param doc [Jekyll::Drops::DocumentDrop]
-    # @return HTML that indicates if a doc is a draft or not
-    def draft_html(doc)
-      return '' unless draft? doc
-
-      " <i class='jekyll_draft'>Draft</i>"
-    rescue StandardError => e
-      @logger.error { e.full_message }
-      ''
-    end
-
-    # @return path to root of the collection that doc is a member of
-    def root(doc, site)
-      return '/index.html' unless doc.respond_to?(:collection)
-
-      collection_name = doc.collection
-      docs = site.key?(collection_name) ? site[collection_name] : site.collections[collection_name].docs
-      index = docs.find { |d| d.url.end_with? 'index.html' }
-      return index.url if index
-
-      docs.min.url
-    end
-
-    module_function :draft?, :draft_html, :root
-  end
-end

data/lib/else.rb

@@ -1,19 +0,0 @@
-require 'jekyll_plugin_support'
-
-class ElseBase < JekyllSupport::JekyllTag
-  VERSION = '0.1.0'.freeze
-  ELSE_DRAFT = 'else_if_draft'.freeze
-  ELSE_NOT_DRAFT = 'else_if_not_draft'.freeze
-
-  def render_impl
-    RECORD_SEPARATOR
-  end
-end
-
-class ElseDraft < ElseBase
-  JekyllPluginHelper.register(self, ELSE_DRAFT)
-end
-
-class ElseNotDraft < ElseBase
-  JekyllPluginHelper.register(self, ELSE_NOT_DRAFT)
-end