Jekyll_pre

This Jekyll plugin provides 3 new Liquid tags that work together:

• A pre block tag that can be displayed various ways.

  {% pre [Options] [free text label] %}
  Contents of pre tag
  {% endpre %}
  

  Options are:

  • class="class1 class2" – Apply CSS classes

  • clear – Line break after floating HTML elements

  • copyButton – Generate a copy button

  • dark – Dark mode

  • label='This is a label' – Apply text above pre tag. The label parameter value can also be specified in free text. For example, the following produce the same results:

    • {% pre label="This is a label" %}
      Contents of pre tag
      {% endpre %}

    • {% pre This is a label %}
      Contents of pre tag
      {% endpre %}

  • number – Number the lines

  • shell – Equivalent to label='Shell'

  • style – Apply inline CSS styles

  The generated <pre></pre> tag has an data-lt-active="false" attribute, so LanguageTool does not check the spelling or grammar of the contents.

• A noselect tag that can renders HTML content passed to it unselectable, and generates a $ prompt if no content is provided.

  {% pre %}
  {% noselect [optional text string, defaults to $]%}Command
  {% noselect unselectable output goes here %}
  {% endpre %}
  

• An exec tag that executes shell commands and incorporates the command and its output into the content of the pre tag. Environment variables are evaluated, output data is escaped, whitespace is condensed, and wrapped in the same unselectable class as does unselectable.

  {% exec [Options] [shell command] %}
  

  Options are:

  • cd="relative/or/absolute/directory" - Change to specified directory before executing shell command. Environment variables in the directory path will be expanded.
  • no_escape – Do not HTML escape the result of running the shell command.
  • no_strip – Do not remove leading and trailing whitespace from the result.
  • die_if_nonzero – Set false to treat non-zero return codes as non-fatal. Instead of terminating Jekyll with an error message, the message will be displayed as an error by the Jekyll logger, and a red message will appear in place of the result on the web page.
  • die_if_error – Set false to treat exceptions generated by this plugin as non-fatal. Instead of terminating Jekyll with an error message, the message will be displayed as an error by the Jekyll logger.

CSS

See demo/assets/css/style.css for the CSS declarations, between /* Start of pre tag css */ and /* End of pre tag css */.

Additional Information

More information is available on my website.

Installation

Add this line to your application's Gemfile, within the jekyll_plugins group:

group :jekyll_plugins do
  gem 'jekyll_pre'
end

And then execute:

$ bundle install

Usage

The following examples are rendered on my website.

Example 1

This example does not generate a copy button and does not demonstrate noselect.

{% pre %}
Contents of pre tag
{% endpre %}

Generates:

<pre data-lt-active='false' class='maxOneScreenHigh copyContainer' id='id377433c30186'>Contents of pre tag</pre>

Which renders as:

Contents of pre tag

Example 2

This example generates a copy button and does not demonstrate noselect.

{% pre copyButton %}
Contents of pre tag
{% endpre %}

Generates:

<pre data-lt-active='false' class='maxOneScreenHigh copyContainer' id='id6a831a3e8992'><button class='copyBtn' data-clipboard-target='#id6a831a3e8992' title='Copy to clipboard'><img src='images/clippy.svg' alt='Copy to clipboard' style='width: 13px'></button>Contents of pre tag</pre>

Which renders as (note the clipboard icon at the far right):

Example 3

This example generates a copy button and does demonstrates the default usage of noselect, which renders an unselectable dollar sign followed by a space.

{% pre copyButton %}
{% noselect %}Contents of pre tag
{% endpre %}

Generates:

<pre data-lt-active='false' class='maxOneScreenHigh copyContainer' id='id1e4a8fe53480'><button class='copyBtn' data-clipboard-target='#id1e4a8fe53480' title='Copy to clipboard'><img src='/assets/images/clippy.svg' alt='Copy to clipboard' style='width: 13px'></button><span class='unselectable'>$ </span>Contents of pre tag</pre>

Which renders as:

Example 4

This example generates a copy button and does demonstrates the noselect being used twice: the first time to render an unselectable custom prompt, and the second time to render unselectable output.

{% pre copyButton %}
{% noselect >>> %}Contents of pre tag
{% noselect How now brown cow%}
{% endpre %}

Generates:

<pre data-lt-active='false' class='maxOneScreenHigh copyContainer' id='idb58a6cf1761c'><button class='copyBtn' data-clipboard-target='#idb58a6cf1761c' title='Copy to clipboard'><img src='/assets/images/clippy.svg' alt='Copy to clipboard' style='width: 13px'></button><span class='unselectable'>>>> </span>contents of pre tag
<span class='unselectable'>How now brown cow</span></pre>

Which renders as:

Example 5

A regular expression can be passed to the highlight option. This causes text that matches the regex pattern to be wrapped within a <span class="bg_yellow"></span> tag.

The CSS stylesheet used for this page contains the following:

.bg_yellow {
  background-color: yellow;
  padding: 2px;
}

This example demonstrates highlighting text that matches a regular expression. Regular expressions match against lines, which are delimited via newlines (\n).

{% pre copyButton highlight="Line 2" %}
Line 1
  Line 2
    Line 3
      Line 4
    Line 5
  Line 6
Line 7
{% endpre %}

Example 6

Regular expressions match against lines, which are delimited via newlines (\n). Thus to match an entire line that contains a phrase, specify the regex as .*phrase.*. The following matches 3 possible phrases (2, 4 or 6), then selects the entire line if matched.

{% pre copyButton highlight=".*(2|4|6).*" %}
Line 1
  Line 2
    Line 3
      Line 4
    Line 5
  Line 6
Line 7
{% endpre %}

Example 7

This example floats an image to the right. The jekyll_pre plugin’s clear option moves the generated HTML below the image.

<img src="jekyll.webp" style="float: right; width: 100px; height: auto;">
{% pre clear copyButton label='Clear example' %}
Using clear, copyButton and label parameters
{% endpre %}

Example 8

The following executes ls -alF / and displays the output.

{% pre clear copyButton label='Exec without error' %}
{% noselect %}{% exec die_if_nonzero=false ls -alF / %}
{% endpre %}

Example 9

The following changes to the home directory ($HOME), then executes pwd and displays the output.

{% pre clear copyButton label='Exec without error' %}
{% noselect %}{% exec cd="$HOME" die_if_nonzero=false pwd %}
{% endpre %}

Example 10

The following executes echo $USER and displays the output.

{% pre clear copyButton label='Exec display $USER' %}
{% noselect %}{% exec die_if_nonzero=false echo $USER %}
{% endpre %}

Comprehensive Example

The code I wrote to generate the above CSS was a good example of how the plugins work together with the from and to tags from my from_to_until plugin:

{% capture css %}{% flexible_include '_sass/mystyle.scss' %}{% endcapture %}
{% pre copyButton %}{{ css | from: '.copyBtn' | to: '^$' | strip }}

{{ css | from: '.copyContainer' | to: '^$' | strip }}

{{ css | from: '.maxOneScreenHigh' | to: '^$' | strip }}

{{ css | from: '.unselectable' | to: '^$' | strip }}
{% endpre %}

Development

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.

Test

A test website is provided in the demo directory.

1. Set breakpoints.

2. Initiate a debug session from the command line:

   $ bin/attach demo

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

Build and Install Locally

To build and install this gem onto your local machine, run:

$ bundle exec rake install

Examine the newly built gem:

$ gem info jekyll_pre

*** LOCAL GEMS ***

jekyll_pre (1.0.0)
    Author: Mike Slinn
    Homepage:
    https://github.com/mslinn/jekyll_pre
    License: MIT
    Installed at: /home/mslinn/.gems

    Generates Jekyll logger with colored output.

Build and Push to RubyGems

To release a new version,

1. Update the version number in version.rb.
2. Commit all changes to git; if you don't the next step might fail with an unexplainable error message.
3. Run the following:

   $ bundle exec rake release

   The above creates a git tag for the version, commits the created tag, and pushes the new .gem file to RubyGems.org.

Contributing

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.