Shortcodes

Shortcodes are reusable template snippets you can use in Markdown content.

Using Shortcodes

Two syntax patterns work in content files:

{%raw%}{{ shortcode_name(arg1="value", arg2="value") }}{%endraw%}

Or explicitly:

{%raw%}{{ shortcode("shortcode_name", arg1="value") }}{%endraw%}

Creating Shortcodes

Shortcode templates live in templates/shortcodes/.

Example: Alert Box

Create templates/shortcodes/alert.html:

{% if type and message %}
<div class="alert alert-{{ type }}">
  {{ message | safe }}
</div>
{% endif %}

Use in content:

{%raw%}{{ alert(type="warning", message="This is important!") }}{%endraw%}

Output:

<div class="alert alert-warning">
  This is important!
</div>

Example: YouTube Embed

Create templates/shortcodes/youtube.html:

{% if id %}
<div class="video-container">
  <iframe 
    src="https://www.youtube.com/embed/{{ id }}"
    frameborder="0"
    allowfullscreen>
  </iframe>
</div>
{% endif %}

Use in content:

{%raw%}{{ youtube(id="dQw4w9WgXcQ") }}{%endraw%}

Example: Figure with Caption

Create templates/shortcodes/figure.html:

<figure>
  <img src="{{ src }}" alt="{{ alt | default(value='') }}">
  {% if caption %}
  <figcaption>{{ caption }}</figcaption>
  {% endif %}
</figure>

Use in content:

{%raw%}{{ figure(src="/images/photo.jpg", alt="A photo", caption="My caption") }}{%endraw%}

You can create a gallery that automatically lists images found in the same directory as the page (Page Bundle).

Create templates/shortcodes/gallery.html:

<div class="gallery">
{% for asset in page.assets -%}
  {%- if asset is matching("[.](jpg|png)$") -%}
    {% set image = resize_image(path=asset, width=240, height=180) %}
    <a href="{{ get_url(path=asset) }}" target="_blank">
      <img src="{{ image.url }}" alt="{{ asset }}" />
    </a>
  {%- endif %}
{%- endfor %}
</div>

Use in content (inside a Page Bundle directory):

{%raw%}{{ gallery() }}{%endraw%}

This will render a grid of all JPG and PNG images found alongside the Markdown file.

Argument Syntax

Arguments support multiple quote styles:

{%raw%}{{ alert(type="warning", message="Double quotes") }}
{{ alert(type='info', message='Single quotes') }}
{{ alert(type=danger, message=No quotes for simple values) }}{%endraw%}

Built-in Variables

Shortcodes have access to:

{# In shortcode template #}
<a href="{{ site.base_url }}/{{ url }}">{{ text }}</a>

Tips

Validate Arguments

Always check for required arguments:

{% if not url %}
<p class="error">Missing url parameter</p>
{% else %}
<a href="{{ url }}">{{ text | default(value="Link") }}</a>
{% endif %}

Use Safe Filter for HTML

When passing HTML content:

{{ content | safe }}

Organize Shortcodes

Group related shortcodes:

templates/shortcodes/
├── alert.html
├── youtube.html
├── figure.html
├── code/
│   ├── tabs.html
│   └── snippet.html
└── social/
    ├── twitter.html
    └── github.html