jekyll_draft 2.0.1 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d833da47df880dd897725f84046568f02e24e88a2dff0d14ec8b3c86e0d24265
-  data.tar.gz: 1bb026e448058d47f96f0841bd1a80bc8c217010cc00bfa628ff708bd34d2a8d
+  metadata.gz: b8b48bd7048b0c4eb3836226b81c8da703f6573e5a564bf5c9ef22733be35167
+  data.tar.gz: 0ebe1a2cbbea83bb3f47fb3e512203a6aebfde0248cff99266e74a66536c99d7
 SHA512:
-  metadata.gz: b5bf1572f2ac67123110e0c8cfd536c2b19d8c8f796468a0c0b18a39f5603909b70a29af4a126390980f631d61d7e32ea63566ec92603efaaa95e73306b6a180
-  data.tar.gz: b07fdb3abdba168e1a207a80382f6192ae142b23358f3a73d6dccfd95a24384e25932f4daa9f794942da4c1891d73ca91e5bb0c684aa5a2d81043019d5b1d4f5
+  metadata.gz: 4383047a610783981f175d29ccc86212c9b76a571ef587d06d29b487c3895e3e73737559ceeea25f4d849fe3a1fd5c64994b035378095ad355948f0bffe032b5
+  data.tar.gz: d2b9ec0decefb9c1b238c498c5a36735b1033362ff327c3d06760c9d0ce6a4e26bd2f657758403664f0b8a04914e8ad9396bdf6f383cac031849a2534d4e89dd

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Change Log
 
+## 2.0.2 / 2024-07-24
+
+* Compatible with `jekyll_plugin_support` v1.0.0
+
+
+## 2.0.1 / 2024-02-07
+
+* Added Jekyll block tags `if_secret` and `unless_secret`.
+* Added Jekyll inline tags: `unless_draft_only`, `else_if_secret` and `else_if_not_secret`.
+* Added Liquid filter: `is_secret`.
+* Added method `draft_only?` and `secret?` 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,37 @@
 # 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 has various ways of specifying that a page or document is
+visible when the website is published in `production` mode.
+The Jekyll documentation is scattered and incomplete regarding this topic.
+This plugin’s filters provide a simple means for marking draft pages in `development` mode.
+
+A secret document is a special form of a draft document.
+Secrets are always drafts, but not the converse.
+
+`Jekyll_draft` 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.
+* Jekyll block tags: `if_secret` and `unless_secret`.
+* Jekyll inline tags: `else_if_not_draft`, `else_if_draft`, `else_if_not_secret` and `else_if_secret`.
+  These are meant for use within `if_draft`, `unless_draft`, `if_secret` and `unless_secret`, 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 inline tag `draft_html`, which generates HTML that indicates if the document
+  it is embedded within is a draft or a secret.
 * Liquid filters:
   * `is_draft` returns a boolean indicating if the document passed to it is a draft.
+  * `is_secret` returns a boolean indicating if the document passed to it is a secret.
   * `draft_html` returns the same string the `draft_html` tag returns,
     indicating if the document passed to it is a draft.
 * 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?` returns a boolean indicating if the document passed to it is a draft or a secret.
+  * `draft_only?` returns a boolean indicating if the document passed to it is a draft and not a secret.
   * `draft_html` returns the same string that `draft_html` tag returns;
     the response indicates if the document passed to it is a draft.
   * `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...
+  * `secret?` returns a boolean indicating if the document passed to it is a draft.
 
 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 +41,38 @@ Both the tag and the filter call the same API methods defined in the `Jekyll::Dr
 More information is available on [Mike Slinn’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
+```
+
+To mark any article (including blog posts) as a secret, add the following to its front matter:
+
+```text
+secret: true
+```
+
+Secret documents are a type of draft document, so the above implies:
+
+```text
+published: false
+secret: true
+```
+
+
 ## Demo
 
 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,64 +96,113 @@ 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_draft', '>2.0.0' # v2.0.0 was a dud, do not use it
+   end
+   ```
 
-And then type:
+3. Type:
 
-```shell
-$ bundle
-```
+   ```shell
+   $ bundle
+   ```
 
 
 ### 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_draft', '>2.0.0' # v2.0.0 was a dud, do not use it
+   ```
 
-And then type:
+2. Type:
 
-```shell
-$ bundle
-```
+   ```shell
+   $ bundle
+   ```
 
 
-## Usage
+## Usage in a Web Page
 
-### `if_draft` and `unless_draft` Block Tags
+### `if_draft`, `unless_draft`, `if_secret` and `unless_secret` Block Tags
 
-The `if_draft` block tag acts as an `if-then` or an `if-then-else` programming construct.
+The `if_draft` and `if_secret` block tags acts as `if-then` or `if-then-else` programming constructs.
+
+The following generates `<p>This is a draft or a secret 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 or a secret document!</p>
+{% endif_draft %}
+```
+
+The following generates `<p>This is a draft document!</p>`
+if the document it is embedded in is a draft and not a secret, and the Jekyll website generation was performed in development mode:
+
+```html
+{% if_draft_only %}
   <p>This is a draft document!</p>
 {% endif_draft %}
 ```
 
+The following generates `<p>This is a secret document!</p>`
+if the document it is embedded in is a secret, and the Jekyll website generation was performed in development mode:
+
+```html
+{% if_secret %}
+  <p>This is a secret document!</p>
+{% endif_draft %}
+```
+
+The following enhances the previous example by also generating `<p>This is not a draft or a secret document!</p>`
+when in production mode:
+
 ```html
 {% if_draft %}
-  <p>This is a draft document!</p>
+  <p>This is a draft or a secret document!</p>
+{% else_if_not_secret %}
+  <p>This is not a secret document, but might be a draft!</p>
 {% else_if_not_draft %}
-  <p>This is not a draft document!</p>
+  <p>This is not a draft or a secret document!</p>
 {% 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`, `unless_draft_only` and `unless_secret` block tags acts as Ruby
+[unless-then](https://rubystyle.guide/#unless-for-negatives) or
+an [unless-then-else](https://rubystyle.guide/#no-else-with-unless) programming constructs.
+
+```html
+{% unless_draft %}
+  <p>This is not a draft or a secret document!</p>
+{% endunless_draft %}
+```
+
+```html
+{% unless_draft_only %}
+  <p>This is not a draft document, but might be a secret!</p>
+{% endunless_draft %}
+```
+
+```html
+{% unless_secret %}
+  <p>This is not a secret document, but might be a draft!</p>
+{% endunless_draft %}
+```
+
+This is how you can specify an `else` clause for `unless_draft`:
 
 ```html
 {% unless_draft %}
   <p>This is not a draft document!</p>
+{% else_if_draft %}
+  <p>This is a draft document!</p>
 {% endunless_draft %}
 ```
 
@@ -121,7 +210,11 @@ an [unless-then-else](https://rubystyle.guide/#no-else-with-unless) programming
 {% unless_draft %}
   <p>This is not a draft document!</p>
 {% else_if_draft %}
+  <p>This is a draft or a secret document!</p>
+{% else_if_draft_only %}
   <p>This is a draft document!</p>
+{% else_if_secret %}
+  <p>This is a secret document!</p>
 {% endunless_draft %}
 ```
 
@@ -138,19 +231,23 @@ Here is an example of embedding the `draft_html` inline tag into an HTML documen
   <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 or a secret, and the Jekyll website generation was performed in development mode,
+`draft_html` emits ` <i class='jekyll_draft>Draft</i>` or ` <i class='jekyll_secret>Secret</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.
+* Add the `published_output` parameter to specify the HTML that should be emitted if the document is not a draft or a secret,
+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>" %}
+  {% draft_html published_output="<p>Not a draft or a secret</p>" %}
   ```
 
-* Add the `draft_output` parameter to specify the HTML that should be emitted if the document is a draft:
+* Add the `draft_output` parameter to specify the HTML that should be emitted if the document is a draft,
+the `secret_output` parameter to specify the HTML that should be emitted if the document is a secret,
+and the Jekyll website generation was performed in development mode:
 
   ```html
   {% draft_html
@@ -160,37 +257,95 @@ The default message will continue to be output for draft documents when the `pub
     draft_output="<p>Is a draft</p>"
     published_output="<p>Not a draft</p>"
   %}
+  {% draft_html
+    secret_output="<p>Is a secret</p>"
+  %}
+  {% draft_html
+    draft_output="<p>Is a draft</p>"
+    published_output="<p>Not a draft or a secret</p>"
+    secret_output="<p>Is a secret</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:
+  to the emitted HTML if the document is a draft,
+  add the `secret_class` parameter to specify the CSS class that should be added
+  to the emitted HTML if the document is a secret,
+  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>"
+    published_output="<p>Not a draft or a secret</p>"
+  %}
+  {% draft_html draft_class="my_draft_class" secret_class="my_secret_class" %}
+  {% draft_html
+    draft_class="my_draft_class"
+    published_output="<p>Not a draft or a secret</p>"
+    secret_class="my_secret_class"
   %}
   ```
 
 * Add the `draft_style` parameter to specify the CSS class that should be added
-  to the emitted HTML if the document is a draft:
+  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 secret_style="font-size: 24pt; color: red;" %}
   {% draft_html
     draft_class="my_draft_class"
     draft_style="font-size: 24pt;"
+    secret_class="my_secret_class"
+    secret_style="font-size: 24pt; color: red;"
   %}
   {% draft_html
     draft_class="my_draft_class"
     draft_style="font-size: 24pt;"
-    published_output="<p>Not a draft</p>"
+    published_output="<p>Not a draft or a secret</p>"
+    secret_class="my_secret_class"
+    secret_style="font-size: 24pt; color: red;"
   %}
   ```
 
 
-### Filters
+### Liquid Filters
+
+#### `draft_html`
+
+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>"`
+
+The default generated HTML for secret pages is:<br>
+`" <i class='jekyll_secret'>Secret</i>"`
+
+Invoke the filter like the following; the output depends on whether the document is a draft or a secret:
+
+```html
+{{ page | draft_html }} => " <i class='jekyll_draft'>Draft</i>"
+{{ page | draft_html }} => " <i class='jekyll_secret'>Secret</i>"
+```
+
+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>
+```
+
 
 #### `is_draft`
 
@@ -198,23 +353,28 @@ This filter detects if a page is invisible when published in `production` mode,
 and either returns `true` or `false`.
 
 ```html
-{{ page | is_draft }} => true
+{{ page | is_draft }} <!-- true for draft and secret documents in development mode -->
 ```
 
 
-#### `draft_html`
+#### `is_draft_only`
 
-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>
-`" <i class='jekyll_draft'>Draft</i>"`
+This filter detects if a page is invisible when published in `production` mode,
+and either returns `true` or `false`.
 
 ```html
-{{ page | draft_html }} => " <i class='jekyll_draft'>Draft</i>"
+{{ page | is_draft_only }} <!-- true for draft documents in development mode, but not secret documents -->
 ```
 
-The optional parameters for the `draft_html` inline tag are not available for
-use with the `draft_html` filter.
+
+#### `is_secret`
+
+This filter detects if a page is invisible when published in `production` mode,
+and either returns `true` or `false`.
+
+```html
+{{ page | is_secret }} <!-- true for secret documents in development mode, but not draft documents -->
+```
 
 
 ### Invoking From Another Jekyll Plugin
@@ -222,12 +382,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 or a secret' if Jekyll::Draft.is_draft post
 
-draft = Jekyll::Draft.draft_html post
+draft_or_secret = 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

@@ -32,5 +32,5 @@ Gem::Specification.new do |spec| # rubocop:disable Metrics/BlockLength
   spec.version = DraftVersion::VERSION
 
   spec.add_dependency 'jekyll', '>= 3.5.0'
-  spec.add_dependency 'jekyll_plugin_support'
+  spec.add_dependency 'jekyll_plugin_support', '>=1.0.0'
 end

data/lib/draft_html.rb

@@ -23,5 +23,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/else.rb

@@ -11,9 +11,9 @@ class ElseBase < JekyllSupport::JekyllTag
 end
 
 class ElseDraft < ElseBase
-  JekyllPluginHelper.register(self, ELSE_DRAFT)
+  ::JekyllSupport::JekyllPluginHelper.register(self, ELSE_DRAFT)
 end
 
 class ElseNotDraft < ElseBase
-  JekyllPluginHelper.register(self, ELSE_NOT_DRAFT)
+  ::JekyllSupport::JekyllPluginHelper.register(self, ELSE_NOT_DRAFT)
 end

data/lib/if_draft.rb

@@ -11,17 +11,17 @@ class DraftBase < JekyllSupport::JekyllBlock
     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)
 end

data/lib/jekyll_draft/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll_draft
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.0.2
 platform: ruby
 authors:
 - Mike Slinn
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-12-01 00:00:00.000000000 Z
+date: 2024-07-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.0.0
 description: 'This Jekyll filter detects draft documents.
 
   '
@@ -92,7 +92,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: This Jekyll filter detects draft documents.