Shortcodes Guide

Shortcodes are a powerful feature in Marmite that allow you to insert dynamic content into your posts and pages using simple markers. They work similar to macros in other static site generators.

What are Shortcodes?

Shortcodes are reusable snippets of HTML or Markdown that can be inserted into your content using a special syntax. They help you:

• Add complex HTML structures without writing HTML in your markdown
• Reuse common content patterns across multiple pages
• Keep your markdown files clean and readable
• Create dynamic content that adapts based on your site data

Using Shortcodes

To use a shortcode in your content, use this syntax:

<!-- .shortcode_name parameter1=value1 parameter2=value2 -->

The shortcode will be replaced with the rendered output when your site is generated.

Built-in Shortcodes

Marmite comes with several built-in shortcodes that are always available, even if you don't have a shortcodes directory in your site:

Table of Contents (toc)

Displays the table of contents for the current page:

<!-- .toc -->

YouTube Videos (youtube)

Embed YouTube videos with optional custom dimensions:

<!-- .youtube id=VIDEO_ID -->
<!-- .youtube id=VIDEO_ID width=800 height=600 -->

You can provide either just the video ID or the full YouTube URL.

Authors List (authors)

Display a list of all authors on your site:

<!-- .authors -->

Streams List (streams)

Display a list of content streams with optional sorting and limiting:

<!-- .streams -->
<!-- .streams ord=desc items=5 -->

Parameters:

• ord: Sort order (asc or desc, default: asc)
• items: Maximum number of items to display (default: all)

Series List (series)

Display a list of all content series:

<!-- .series -->
<!-- .series ord=desc items=5 -->

Parameters:

• ord: Sort order (asc or desc, default: asc)
• items: Maximum number of items to display (default: all)

Posts List (posts)

Display a list of posts:

<!-- .posts -->
<!-- .posts ord=asc items=5 -->

Parameters:

• ord: Sort order (asc or desc, default: desc)
• items: Maximum number of items to display (default: 10)

Pages List (pages)

Display a list of pages:

<!-- .pages -->
<!-- .pages ord=desc items=5 -->

Parameters:

• ord: Sort order (asc or desc, default: asc)
• items: Maximum number of items to display (default: all)

Tags List (tags)

Display a list of all tags with post counts:

<!-- .tags -->
<!-- .tags ord=desc items=10 -->

Parameters:

• ord: Sort order (asc or desc, default: asc)
• items: Maximum number of items to display (default: all)

Creating Custom Shortcodes

You can create your own shortcodes by adding files to the shortcodes directory in your input folder. Custom shortcodes will override built-in shortcodes with the same name.

Adding Descriptions to Shortcodes

You can add descriptions to your shortcodes by including a Tera comment as the first line of the file:

{# Display a custom alert box #}
{% macro alert(type="info", message="") %}
...
{% endmacro alert %}

These descriptions will be shown when you run marmite --shortcodes.

HTML Shortcodes

Create .html files with Tera macros:

{# shortcodes/alert.html #}
{# Display a custom alert box #}
{% macro alert(type="info", message="") %}
<div class="alert alert-{{type}}">
  {{message}}
</div>
{% endmacro alert %}

Usage:

<!-- .alert type=warning message="This is a warning!" -->

Markdown Shortcodes

Create .md files that will be processed as Markdown:

{# shortcodes/feature.md #}
{# Display a feature highlight box #}
## Feature: {{ title }}

{{ description }}

{% if link %}
[Learn more]({{ link }})
{% endif %}

Usage:

<!-- .feature title="Awesome Feature" description="This feature is amazing!" link="/features" -->

Configuration

Shortcodes are enabled by default. You can disable them or customize the pattern in your marmite.yaml:

# Enable/disable shortcodes
enable_shortcodes: true

# Custom shortcode pattern (regex)
# Default: <!-- \.(\w+)(?:\s+([^-][\s\S]*?))?\s*-->
shortcode_pattern: null  # Uses default HTML comment pattern

Custom Shortcode Patterns

You can customize the shortcode pattern to match your preferred syntax. Here are some popular alternatives:

Hugo-style Shortcodes

If you're migrating from Hugo or prefer its syntax:

# Hugo-style: {{< shortcode param="value" >}}
shortcode_pattern: "\\{\\{<\\s*(\\w+)([^>]*)\\s*>\\}\\}"

With this pattern, you would use:

{{< youtube id="dQw4w9WgXcQ" >}}
{{< toc >}}

Jekyll/Liquid-style Shortcodes

For Jekyll or Liquid-style syntax:

# Jekyll-style: {% shortcode param="value" %}
shortcode_pattern: "\\{%\\s*(\\w+)([^%]*)\\s*%\\}"

With this pattern, you would use:

{% youtube id="dQw4w9WgXcQ" %}
{% toc %}

Double-bracket Style

For a wiki-like syntax:

# Wiki-style: [[shortcode param="value"]]
shortcode_pattern: "\\[\\[(\\w+)\\s*([^\\]]+)?\\]\\]"

With this pattern, you would use:

[[youtube id="dQw4w9WgXcQ"]]
[[toc]]

CLI Override

You can also override the shortcode settings via command-line flags:

# Disable shortcodes for a single build
marmite myblog output/ --enable-shortcodes false

# Use a custom pattern for a single build
marmite myblog output/ --shortcode-pattern '\\{\\{<\\s*(\\w+)([^>]*)\\s*>\\}\\}'

Listing Available Shortcodes

To see all available shortcodes in your project:

marmite --shortcodes

This command will display:

• Whether shortcodes are enabled or disabled
• The current shortcode pattern being used
• Examples based on your configuration
• A list of all available shortcodes (both built-in and custom)

You can combine this with CLI overrides to test different patterns:

# See how shortcodes would work with Hugo-style pattern
marmite --shortcodes --shortcode-pattern '\\{\\{<\\s*(\\w+)([^>]*)\\s*>\\}\\}'

Migration from Other Static Site Generators

If you're migrating from another static site generator, you can configure Marmite to use familiar shortcode syntax:

From Hugo

Set your marmite.yaml:

shortcode_pattern: "\\{\\{<\\s*(\\w+)([^>]*)\\s*>\\}\\}"

Then your existing Hugo shortcodes like {{< figure src="image.jpg" >}} will work (though you'll need to reimplement the shortcode logic in Tera templates).

From Jekyll

Set your marmite.yaml:

shortcode_pattern: "\\{%\\s*(\\w+)([^%]*)\\s*%\\}"

Your Jekyll-style tags like {% include figure.html %} syntax will be recognized (you'll need to create corresponding Tera macros).

Important Notes for Migration

1. Syntax only: The pattern changes only the syntax recognition. You still need to implement the shortcode logic using Tera templates.
2. Parameter parsing: Marmite expects key=value pairs for parameters, which may differ from your previous generator.
3. Test thoroughly: Always test your migrated shortcodes with marmite --shortcodes to ensure they're recognized correctly.

Best Practices

1. Name shortcodes clearly: Use descriptive names that indicate what the shortcode does
2. Document parameters: Include comments in your shortcode files explaining required and optional parameters
3. Use defaults: Provide sensible default values for optional parameters
4. Keep it simple: Shortcodes should do one thing well
5. Test thoroughly: Check that your shortcodes work correctly with different parameters
6. Choose patterns wisely: Stick with the default pattern unless you have a specific need (like migration) to change it

Examples

Custom Gallery Shortcode

Create shortcodes/gallery.html:

{% macro gallery(folder, columns="3") %}
<div class="gallery cols-{{columns}}">
  {% for image in site_data.site.extra.galleries[folder] %}
  <img src="{{image.url}}" alt="{{image.alt}}">
  {% endfor %}
</div>
{% endmacro gallery %}

Usage:

<!-- .gallery folder=vacation columns=4 -->

Custom Quote Shortcode

Create shortcodes/quote.md:

> {{ text }}
> 
> — _{{ author }}{% if source %}, {{ source }}{% endif %}_

Usage:

<!-- .quote text="The only way to do great work is to love what you do." author="Steve Jobs" source="Stanford Commencement Address" -->

Troubleshooting

• Shortcode not rendering: Check that the shortcode file exists and has the correct extension
• Invalid parameters: Ensure parameter values are properly quoted if they contain spaces
• HTML shortcodes: Must contain at least one {% macro %} definition
• Context variables: All template context variables (like site_data, content, etc.) are available in shortcodes

With shortcodes, you can extend Marmite's functionality and create rich, dynamic content while keeping your markdown files clean and maintainable!

Please consider giving a ☆ on Marmite Github repository, that helps a lot!