Brings Pry to Liquid templates and to Jekyll-powered sites
MIT License
= 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
:
=== 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:
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
:
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.
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:
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:
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:
=== 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: