Why do shortcodes exist? Are there reasons why it would not be simpler to implement calling of partials (instead of shortcodes) from inside markdown? What can shortcodes do that an equivalent partial could not do?
I currently have several ‘shortcodes’ that do nothing besides calling a partial with the same name, because it is not idiomatic or supported to call the partial directly in markdown md files
Am I doing it wrong?
How would you do that?
As a mere user of the platform, I am not familiar with the underlying implementation involved in why and how shortcodes can be called from inside markdown, but partials cannot.
I have partials that are sometimes called in layout templates, and sometimes called ‘directly’ from markdown via pseudo-shortcodes.
Assuming there are reasons why separate shortcodes must be involved, would it not be possible to introduce another kind of syntax hook (like “{{@” or something) that lets a partial be called like a shortcode?
I’m doing pretty simple stuff like this, but the ‘real’ image partial does more things, like calling a responsive image partial in turn. The image.html partial itself can also be called by other partials (or shortcodes):
The ‘shortcode’:
{{- $src := .Get “src” }}
{{- $alt := .Get “alt” | default “” }}
{{- $caption := .Get “caption” | default “” }}
{{- $sizes := .Get “sizes” }}
{{- partial “image.html” (dict “page” .Page “src” $src “alt” $alt “caption” $caption “sizes” $sizes) }}
And that works. So I am curious why I actually need the shortcode, and there isn’t an under-the-hood way that Hugo knows how to pass those args directly to an instance of the partial
Isn’t that just a … different shortcode syntax. Your original question implied that using partials directly should somehow be simpler, but we need a way to separate Markdown from Go template syntax, which is why we came up with the shortcode delimiters.
Note that shortcodes can be inlined (see Shortcodes) which allows you to call partials directly.
Besides technical differences, from a user’s point of view both concepts may seem identical but from a security perspective they are not.
You don’t want your writer be able to call any arbitrary template doing “something”. Shortcodes limit what a writer can do to a limited set of actions.
It is nothing wrong with your approach to directly call a partial from your shortcode, doing all the work. That’s how I implement all my shortcodes, too. This also has the advantage, you can “call your shortcode” from inside any other template, by calling the shortcode template directly.
To bring in another perspective: Currently I am thinking about also adding the ability to call shortcodes using Markdown codefences and Hugo’s Markdown attributes, but still not sure, if this is a good idea.
You are right, a partial could do more than a shortcode (without looking at how to implement it). But you are wrong. It’s a site generator and as such it has a design part and a author part. The author could “just” use some AI and copy paste something into their partials that breaks things or makes the system insecure. That’s why we have shortcodes. They are limited and sanitized. It allows the designer of the system to hand over controlled access to more than just markdown text.
In my own systems, I am both designer and author. I have partials that “do things” and shortcodes that clean up input and add defaults and then call those partials to do things. Content files call shortcodes, theme files call partials. This way I only fix some issues in the partial and everyone using that feature is happy.
The security/interface layer makes sense now, thanks all for answering
Documentation could further emphasize this crucial point about protecting the partials layer from ‘content creator’ roles that could include unmonitored or even malicious input
But it’s ok (and role safe) to use ‘interface shortcodes’ merely to provide controlled access to certain partials? Or is that wrong too?
If you look at the markdown source:
with shortcode you have a reusable component extending the possibilities of markdown. Also usable across the site.
The Markdown still looks like markdown and is much more readable.
If the shortcode has a good name and proper named arguments anyone without templating language can still read that markdown and get an impression what that does.
have a look at the Details shortcode and it’s referenced source code I for sure don’t want that definition inside my “Text” document.
converting the markdown to another source format (or renderer) is much easier