shortcodes vs macros

[bobbwal]

These seem to provide fairly similar functionality, is there any situation where shortcodes would be more suited than a macro and vice versa?

Thanks

[pdehaan]

Assuming you're talking about the Nunjucks {% macro %} tag (since I don't think LiquidJS has a macro tag, per https://liquidjs.com/tags/overview.html), I believe they're a pretty similar concept.

Take this with the world's largest grain of salt, but my limited expertise tells me that they're pretty close, with a macro being defined in Nunjucks syntax, whereas an Eleventy shortcode is defined in JavaScript. The other difference is that the macro is pretty Nunjucks-specific, but a shortcode could be shared by different engines (unless you used .addNunjucksShortcode(..)).

Here was my rough attempt at a Nunjucks macro (stolen from their documentation) versus trying to rewrite it as a shortcode:

---
# src/index.njk
---

{% macro fieldMacro(name, value="", type="text") %}
  <div class="field">
    <input type="{{ type }}" name="{{ name }}" value="{{ value | escape }}" />
  </div>
{% endmacro %}

<h2>Macro</h2>
{{ fieldMacro("macroUser") }}
{{ fieldMacro("macroPass", type="password") }}

<h2>Shortcode</h2>
{% fieldShortcode "shortcodeUser" %}
{% fieldShortcode "shortcodePass", type="password", value=("qwerty@?:&123" | escape) %}

// .eleventy.js
module.exports = function (eleventyConfig) {
  eleventyConfig.addShortcode("fieldShortcode", function (name, kwargs = {}) {
    const defaultArgs = {
      value: "",
      type: "text",
    };
    const { value, type } = Object.assign({}, defaultArgs, kwargs);
    return `
      <div class="field">
        <input type="${type}" name="${name}" value="${value}" />
      </div>
    `;
  });

  return {
    dir: {
      input: "src",
      output: "www",
    },
  };
};

The shortcode was a bit trickier than I expected, because I had to refactor some things to support the shortcode named argument syntax (Nunjucks-only).

The other trick is that the macro used {{ value | escape }} which is the Nunjucks escape filter:

Convert the characters &, <, >, ‘, and ” in strings to HTML-safe sequences. Use this if you need to display text that might contain such characters in HTML. Marks return value as markup string

Easy enough in a macro, but in the shortcode version you'd either need to write that filter in JavaScript yourself (the better option), or be lazy and pre-escape it from the Nunjucks side before passing it to the shortcode (which I did, because lazy).

I vaguely recall a few issues and discussions around macro usage, but not a lot.

---

UPDATE: Pushed the example code to GitHub at https://github.com/pdehaan/11ty-nunjucks-macro-test

[bobbwal]

Thanks, I appreciate your reply. Yes, I was referring to Nunjucks, this is my first Eleventy project and I forget there are other engines available.

So I guess it's fairly safe to say it doesn't matter too much and could be considered personal preference, so long as you don't intend to switch engines. I find the macro approach a little easier to deal with but have also experimented with shortcodes. I guess ideally it would be cleaner to pick one and stick with it rather than a mix of the two approaches.

[edwardhorsford]

I think if you were possibly going to use multiple templating languages, then shortcode makes the better choice. If you’re just using Nunjucks, then it's up to you which you pick.

FWIW I just use regular macros - I was already heavily invested in them before moving to Eleventy, and I didn't get the point of shortcodes (like you!) as I only use this one templating language.

[zachleat]

Good question! Some good discussion on this on Twitter this week via @jeromecoupe https://twitter.com/jeromecoupe/status/1419726991994068994

[Ryuno-Ki]

Do you mind to summarise the thread here, Jérôme?
Would be a bummer if it would get lost in a cleanup action by Twitter.

[jeromecoupe]

No problem. Here are my 2 cents … so far.

Context: Eleventy workshop for students and trying to give them some pointers about what to use when (njk includes, njk macros, 11ty shortcodes)

Nunjucks includes: use when the included file does not need parameters passed to it, other than those available in the global inheritance context. Use case: partials like header / footer / etc.

Nunjucks macros: use when you need scoped parameters / props (macros are locally scoped / not affected by the global inheritance context). Use cases: components like a card with props like CSS classes, image or not, etc

Eleventy shortcodes: same use cases as macros but when you also need JS / Node logic and processing, NPM packages, async data, components that work across templating languages, etc.