Octopress Wrap Tag

A Liquid block tag which makes it easy to wrap an include, render or yield tag with html.

Installation

Add this line to your application's Gemfile:

gem 'octopress-wrap-tag'

And then execute:

$ bundle

Or install it yourself as:

$ gem install octopress-wrap-tag

Next add it to your gems list in Jekyll's _config.yml

gems:
  - octopress-wrap-tag

Usage

Basic usage

The wrap tag is basically just wrapping Octopress's include, return, render and yield tags with HTML in a liquid block tag. This means that the wrap tag,supports conditional output, filters and all the other features these tags offer. This also means that wrap yield and wrap return won't output anything if there isn't any content.

{% wrap include post.html %}
  <article>{{ yield }}</article>
{% endwrap %}

{% wrap render ../LICENCE.md %}
  <div class="licence-text">{{ yield }}</div>
{% endwrap %}

{% wrap yield post_footer %}
  <div class="post-footer">{{ yield }}</div>
{% endwrap %}

{% wrap return site.author %}
  Post by {{ yield }}
{% endrwap %}

Wrap Yield

A great use case for wrap yield is to add content sections to a template which can be easily and optionally filled from a post or page by using the content_for tag. Here's an example.

<aside class="sidebar">
  {% wrap yield sidebar_before %}
    <section>{{ yield }}</section>
  {% endwrap %}

  // Regular sidebar content goes here //

  {% wrap yield sidebar_after %}
    <section>{{ yield }}</section>
  {% endwrap %}
</aside>

Now in any post or page you can add custom content to the sidebar with a content_for tag.

{% content_for sidebar_before %}
  <h4>About this post</h4>
  ...
{% endcontent_for %}

This content will appear at the top of the sidebar, wrapped in a section element. The sidebar_after section won't be rendered since it wasn't set in this post.

Advanced features

The examples below only demonstrate wrapping the include tag for brevity, but as stated earlier, the wrap tag supports all the features of the include, render, return and yield tags.

---
sidebar: post_sidebar.html
---

{% wrap include page.sidebar %}
  <aside>{{ yield }}</aside>
{% endwrap %}

Include partials conditionally, using if, unless and ternary logic.

{% wrap include page.sidebar if page.sidebar %}
  <aside>{{ yield }}</aside>
{% endwrap %}

{% wrap include comments.html unless page.comments == false %}
  <div class="post-comments">{{ yield }}</div>
{% endwrap %}

{% wrap include (post ? post_sidebar : page_sidebar) %}
  <aside>{{ yield }}</aside>
{% endwrap %}

Filter included partials.

{% wrap include greeting.html %} yo, {{ yield }}{% endwrap %}           //=> yo, what's up?
{% wrap include greeting.html %} yo, {{ yield | upcase }}{% endwrap %}  //=> yo, WHAT'S UP?
{% wrap include greeting.html | upcase %} Yo, {{ yield }}{% endwrap %}  //=> YO, WHAT'S UP?

Include partials with an Octopress Ink plugin.

It's easy to include a partial from an Ink theme or plugin.

Here's the syntax

{% wrap include [plugin-slug]:[partial-name] %}
{{ yield }}
{% endwrap %}

Some examples:

{% wrap include theme:sidebar.html %}   // Include the sidebar from a theme plugin
  <aside>{{ yield }}</aside>
{% endwrap %}

{% wrap include twitter:feed.html %}    // Include the feed from a twitter plugin
  <div class="twitter-feed">{{ yield }}</div>
{% endwrap %}

Contributing

1. Fork it ( https://github.com/octopress/wrap-tag/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request