jekyll_draft

Published 2020-10-03. Last modified 2023-12-02.
Time to read: 4 minutes.

This page is part of the jekyll_plugins collection.

jekyll_draft

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.

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. 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.
Liquid filters:
- is_draft returns a boolean indicating if the document passed to it is a draft.
- 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_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...

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, while the filter works on any document passed to it. Both the tag and the filter call the same API methods defined in the Jekyll::Draft module.

Demo

The demo/ subdirectory has working examples of this Jekyll plugin's functionality in a demonstration website. It can be used to debug the plugin or it can run freely. Please examine the HTML files in the demo to see how the plugin works.

To run the demo freely from the command line, type:
Shell
```
$ demo/_bin/debug -r
```
View the generated website at localhost:4444.

When the demonstration is running, any time you modify the .html files, the demo website will regenerate. Each time you make a change, the website instantly regenerates. This helps the learning experience.

Please play with the contents of the .html files, so you can learn how to write Jekyll pages that include this functionality.

Installation

For Use In A Jekyll Website

Add the CSS found in demo/assets/css/jekyll_draft.css to your Jekyll layout(s).

Add the following to Gemfile:

Gemfile

group :jekyll_plugins do
  gem 'jekyll_draft', '>=2.0.2'
end

From your Jekyll site's top-level directory, type:
Shell
```
$ bundle
```
Restart Jekyll.

For Use In a Gem

Add the following to your gem’s `.gemspec`:
my_project.gemspec
```
spec.add_dependency 'jekyll_draft', '>=2.0.2'
```
Type:
Shell
```
$ bundle
```

Tags

if_draft and unless_draft

The if_draft block tag acts as an if-then or an if-then-else programming construct.

The following generates This is a draft document! if the document it is embedded in is a draft, and the Jekyll website generation was performed in development mode:

HTML or markdown

{% if_draft %}
  <p>This is a draft document!</p>
{% endif_draft %}

The following generates This is a draft document! if the document it is embedded in is a draft, otherwise it generates This is not a draft document!:

HTML or markdown

{% if_draft %}
  <p>This is a draft document!</p>
{% else_if_not_draft %}
  <p>This is not a draft document!</p>
{% endif_draft %}

The unless_draft block tag acts as a Ruby unless-then or an unless-then-else programming construct.

HTML or markdown

{% unless_draft %}
  <p>This is not a draft document!</p>
{% endunless_draft %}

This is how you can specify an else clause for unless_draft:

HTML or markdown

{% unless_draft %}
  <p>This is not a draft document!</p>
{% else_if_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. Use the keyword that makes the most sense to you.

`draft_html`

Here is an example of embedding the draft_html inline tag into an HTML document:

HTML or markdwon

<p>Is this a draft document? Look here to see: {% draft_html %}</p>

By default, draft_html emits Draft if the document is a draft, and the Jekyll website generation was performed in development mode, 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 or markdown
```
{% draft_html published_output="Not a draft" %}
```
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 or markdown
```
{% draft_html
 draft_output="Is a draft"
%}
{% draft_html
 draft_output="Is a draft"
 published_output="Not a draft"
%}
```
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 or markdown
```
{% draft_html draft_class="my_draft_class" %}
 {% draft_html
 draft_class="my_draft_class"
 published_output="Not a draft"
 %}
```

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 or markdown

{% 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

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 generated HTML for draft pages is:
" Draft"

Invoke the filter like this:

HTML or markdown

{{ page | draft_html }}

Here is a code snippet that shows the draft_html filter in use:

HTML or markdown

{% assign docs = site.myCollection | sort: "order" %}
<ol id="titles">
{% for doc in docs %}
  <li>
    <a href="{{doc.url}}" class="title">{{doc.title}}{{ doc | draft_html }}
  </li>
{% endfor %}
</ol>

is_draft

This filter detects if a page is invisible when published in production mode, and either returns true or false.

HTML or markdown

{{ page | is_draft }} <!-- true for draft documents in development mode -->

Invoking From Another Jekyll Plugin

Ruby

require 'jekyll_draft'

puts 'Found a draft' if Jekyll::Draft.is_draft post

puts "draft_html is #{Jekyll::Draft.draft_html post}"

Mainframe image; Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 License by PekoeBlaze

© Copyright 1994-2024 Michael Slinn. All rights reserved.
For requests to use this copyright-protected work in any manner, email mslinn@mslinn.com.

This website was made using Jekyll and Mike Slinn’s Jekyll Plugins.