Custom reusable ‘_includes’ - Alternatives to Plugins

This Jekyll Template uses a few ‘plugins’. We have one plugin to allow markdown snippets to be included in HTML pages, and another for external links.

While plugins like those let you use custom Liquid tags in your markup, I have a few issues with them. It took a lot of parsing to separate values you want to pass. The custom parsing also made it harder to extend those plugins, and lastly, you had to remember a lot more syntax when utilizing the tags

That all lead me to think, “there has to be a better way”. I wanted to be able to pass data using mutiple variables and it turns out you can do just that.

We learn by Googling and Experimenting.

My first Widget

I’m not sure what to call this sort of reusable _include, but “widgets” works well enough. I needed to call them something to keep the includes directory tidy.

In Googling the use of variables within ‘liquid’ tags, I cam across this StackOverflow post on how to include a caption on a photo. I wanted to do was similar: creating way to put inline photo’s within my markdown in a way that I could easily not only include caption and ‘alt’ fields, but also adjust the width of a photo.

It turned out to be a very straightforward thing to do that really makes it easier to have more media within a post.

How to use variables with includes

It’s simple.

Here is a standard _include that you might use to insert your site title and slogan partial named ‘title-group.html’

  {% include title-group.html %}

You could pass that ‘title-group.htm’ a variable to customize that slogan.

  {% include title-group.html custom-slogan="whatever you say dude" %}

Now, before moving to how that works lets consider the limitations of basic markdown images.

Here is how you can use the most basic markdown image tag:

  ![alt text](https://github.com/adam-p/markdown-here/raw/master/src/common/images/icon48.png "Logo Title Text 1")

But, what if you want to change it’s width or add a caption? And, without a class, you’d have a hard time styling those inline images.

Here’s the solution I came up with.

Directions for inserting Inline images in your blog posts

Cut and paste the code below and substitute and delete as desired:

{% include image-inline.html url="/images/subfolder-in-images/filename.png" width="33%" alt=page.post-title caption="whatever you want here(or nothing)" class="optional-further-styling-class" %}

• url is the path to the image

• width is a string with a number and the ‘%’ symbol (“100%” will span the full text collumn, “33%”” will have blog text wrap around the third it takes up)

• url is what screen readers see as well as having important SEO ramifications. You can set it with front matter like I did or include custom text like “whatever words give me the best Google score”

• caption is a bold lable text directly beneath the photo. Like with “alt” you could use front matter instead.

• class another optional, field, this would help you style different types of inserts(maybe you wanted all table images have a border?).

If you just want to use this feature you don’t need to read the rest of this: follow the instructions in the section immediately above.

HTML: Here is the markup that the using the “image-inline.html” include ‘widget’ will generate:

<span class="tn-image-inline {{include.class}}" style="width:{{include.width}}">
  <img src="{{ include.url }}" alt="{{ include.alt }}" title="{{include.caption}}" width="100%">
  <label class="tn-image-inline-caption">{{ include.caption }}</label>
</span>

CSS:

.tn-image-inline{
    position: relative;
    display: inline-block;
    float: left;
    padding: 0px 20px 0px 0px;
    text-align: center; 
}

I’m really glad I can use Jekyll create these reusable widgets. They do walk a line towards expanding the liquid domain specific language but short of a GUI on a CMS, it’s a very simple way to go.

In another post I show how to use the same concept to create togglable page sections