Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/geolexica/liquid-pry

Brings Pry to Liquid templates and to Jekyll-powered sites
https://github.com/geolexica/liquid-pry

jekyll jekyll-plugin pry

Last synced: 3 months ago
JSON representation

Brings Pry to Liquid templates and to Jekyll-powered sites

Awesome Lists containing this project

README 

        
= Liquid::Pry



:jekyll: https://jekyllrb.com/

:jekyll_plugin_install: https://jekyllrb.com/docs/plugins/installation/

:pry: https://pry.github.io/

:ribose: https://www.ribose.com



ifdef::env-github[]

image:https://img.shields.io/gem/v/liquid-pry?style=for-the-badge[

  Latest Version, link="https://rubygems.org/gems/liquid-pry"]

image:https://img.shields.io/github/workflow/status/geolexica/liquid-pry/Tests/master?style=for-the-badge[

  Build Status, link="https://github.com/geolexica/liquid-pry/actions?workflow=tests"]

endif::[]



ifndef::env-github[]

[quote, Pry home page]

Pry is a runtime developer console with powerful introspection capabilities.

endif::[]

ifdef::env-github[]

“Pry is a runtime developer console with powerful introspection capabilities.”

-- Pry home page

endif::[]



Liquid::Pry brings {pry}[Pry] to Liquid templates and to Jekyll-powered sites.



== Installation



=== Without Jekyll



Add following to the `Gemfile`:



----

gem "liquid-pry"

----



=== With Jekyll



If you want to integrate Liquid::Pry with Jekyll, it's probably the easiest

to add following to the `Gemfile`, so that Jekyll will automatically load and

enable Liquid::Pry:



----

group :jekyll_plugins do

  gem "liquid-pry"

end

----



For other options, read {jekyll_plugin_install}[Jekyll documentation].



== Usage



This gem provides a Liquid filter and a Liquid tag.



=== Filter



The `pry` filter hooks Pry into filter chain in a Liquid template, helping user

to debug Jekyll's front matter or any other data available in given template.

For example following could be used to debug `page.title`:



----

You are on page {{ page.title | pry }}.

----



When Liquid renderer encounters `pry` filter, then Pry console is launched.

A convenience local variable named `input` is defined, which contains filter

input (value of `page.title` in above example), allowing site developer to

inspect or alter that value.  Another local variable `context` provides access

to rendering context.



The filter returns its input, hence it does not affect rendered page.  Also, it

can be placed anywhere in the filter chain, not necessarily at the end.

For example, in a following example `pry` filter is placed before `upcase`,

allowing user to inspect `page.title` value before the `upcase` filter is

applied.



----

You are on page {{ page.title | pry | upcase }}.

----



However, if user modify the value of `input` variable, then modified version is

returned.  This may be used for experimenting.



The `pry` filter is typically more useful than the `pry` tag, especially for

novice users.



=== Tag



The `pry` tag interrupts Liquid rendering, allowing user to inspect or modify

the rendering context.  For example:



----

{% pry %}

----



When Liquid renderer encounters `pry` tag, then Pry console is launched

and rendering context is available via `context` local variable.



==== Using with `once` option



If `pry` tag is supplied with `once` option, then Pry console is launched only

for the first time that tag is encountered on given page.  In following example:



----

{% for product in collection.products %}

  {% pry once %}

  {{ product.title }}

{% endfor %}

----



Pry will be launched only once, no matter if `collection.products` contains one

item or a hundred.



Still, in following example Pry will be launched twice, because `pry` tag is

placed that many times in the template:



----

{% pry once %}

{% pry once %}

----



=== Using Pry console



See {pry}[Pry documentation].



== Credits



This gem is developed, maintained and funded by {ribose}[Ribose Inc.]



== License



The gem is available as open source under the terms of the

https://opensource.org/licenses/MIT[MIT License].



== See also



This gem is tiny but quite comprehensive.  However, there are some other ones

you may want to try:



- https://github.com/gemfarmer/jekyll-debug[jekyll-debug]

- https://github.com/zhongxiang117/jekyll-liquid-debug[jekyll-liquid-debug]

  (a very different approach)

- https://github.com/octopress/debugger[octopress-debugger]

  (seems unmaintained as of Jan 2021)