Support named parameters for applicable shortcodes

[agriyakhetarpal]

Description

This PR allows named parameters in the figure, button, and image shortcodes and is an attempt to unify the base Hugo figure shortcode at https://github.com/gohugoio/hugo/blob/@a1cb15e/tpl/tplimpl/embedded/templates/_shortcodes/figure.html with the theme's shortcode, and so on for other applicable shortcodes.

The change here allows the shortcodes to be written in this manner: {{< figure src="image.jpg" alt="description" >}}.

Based on https://gohugo.io/content-management/shortcodes/, the arguments inside the opening tag are all using double-quoted strings, and I found that using single-quoted strings can cause errors that are a little difficult to debug based on Hugo's error messages, so I changed all instances to use double-quoted strings where applicable to be on the safer side.

We updated all the examples in the docs right above the shortcodes with the updated syntax. Also, the link to the image of the cute puppies was broken, so I added another one from Unsplash for our floofy friends :)

Additional context

@goanpeca mentioned as a part of the work on https://github.com/scientific-python-translations/ that this would be nice to support, as Crowdin, as a part of the automations set up for the projects' websites, only understands the named-parameters syntax for the figure shortcode.

After the discussions (see below), we decided to expand the scope of this PR to all shortcodes and to not preserve backwards compatibility in favour of keeping just one syntax for the changed shortcodes, where we can put together PRs that update to the new syntax everywhere.

[netlify]

❌ Deploy Preview for scientific-python-hugo-theme failed.

Built without sensitive environment variables

Name	Link
🔨 Latest commit	bb0d090
🔍 Latest deploy log	https://app.netlify.com/sites/scientific-python-hugo-theme/deploys/68242ed0bbc76000083e74c5

[agriyakhetarpal]

The proposed change, i.e.

{{< figure
    src = "https://images.unsplash.com/photo-1546238232-20216dec9f72"
    alt = "Cute puppies"
    attribution = "Figure Credits: Cute puppies image from unsplash.com"
    attributionlink = "https://images.unsplash.com/photo-1546238232-20216dec9f72"
    align = "right"
    height = 150
    width = 150
    caption = "A figure with right alignment."
>}}

{{< /figure >}}

is working well on https://deploy-preview-674--scientific-python-hugo-theme.netlify.app/shortcodes/#figure 🐶

[stefanv]

This change looks good to me.

We could also only support named parameters, we'd just need to fix up numpy.org, scipy.org, and all the SP websites. But, this is fine for now.

[stefanv]

One last comment: I don't think we need the closing figure tags?

[goanpeca]

Hi @stefanv, I think @agriyakhetarpal tried to work on that too but there were some issues.

[agriyakhetarpal]

This change looks good to me.

We could also only support named parameters, we'd just need to fix up numpy.org, scipy.org, and all the SP websites. But, this is fine for now.

Hi @stefanv, thank you for the review! Yes, I considered supporting only named parameters, but opted not to to preserve backwards compatibility.

One last comment: I don't think we need the closing figure tags?

Hi @stefanv, I think @agriyakhetarpal tried to work on that too but there were some issues.

Yes – I tried to make it work without closing figure tags, but I had an issue with the HTML character entities not being converted to their symbol counterparts (such as &#34 for " and /&gt for >, and so on), as they were being rendered literally and breaking the shortcode, so I thought of leaving it so for now. I would be happy to explore this as a follow-up.

In the meantime, I've changed some more previously broken links for the cute puppies. I've confirmed that the image I used is free to use under the Unsplash license. :)

[stefanv]

Yes – I tried to make it work without closing figure tags, but I had an issue with the HTML character entities not being converted to their symbol counterparts (such as &#34 for " and /&gt for >, and so on), as they were being rendered literally and breaking the shortcode, so I thought of leaving it so for now. I would be happy to explore this as a follow-up.

If we are going to introduce a new syntax, it would be nice to have it "done and dusted" in one go. Do you think it would take long to explore whether we could use {{< figure param=... /> }}?

In the meantime, I've changed some more previously broken links for the cute puppies. I've confirmed that the image I used is free to use under the Unsplash license. :)

I happened to check that too earlier today ;)

[agriyakhetarpal]

If we are going to introduce a new syntax, it would be nice to have it "done and dusted" in one go. Do you think it would take long to explore whether we could use {{< figure param=... /> }}?

Yes, this is what's broken. I'll take a look, though!

[stefanv]

I wonder if the closing tag is required because we access .Inner? Or is .Inner only available when there is a closing tag? (That's be a bit odd.)

I think if that is the issue (using .Inner) then we should opt for the new version only.

[agriyakhetarpal]

Yes, that's indeed the case (@goanpeca and I were discussing this yesterday). I'm trying to see if we can make it work without it!

[agriyakhetarpal]

Okay, yeah, I don't think this is going to work, based on what I understand from https://discourse.gohugo.io/t/what-is-meant-by-closed-or-self-closed/44785 and https://gohugo.io/templates/shortcode/#inner. .Inner is available only with a closing tag, and its length is 0 with a self-closing tag.

I think we could:

• create a figure-single.html to handle the self-closing syntax specifically that would simply collect parameters and pass them to the regular figure shortcode as a partial, but that would be a new shortcode and I think it would confuse users.
  • maybe, we could rename the current figure.html to figure-base.html (and not document the figure-base shortcode), go ahead with this solution, and name that figure.html? It could work as nothing would be exposed to the user, but I think it confuses maintainers down the line.
• The other way is to use Hugo's own figure shortcode and adapt it to include the extra parameters we have as the self-closing syntax works there – but that breaks compatibility.

I would probably opt for none of these at the moment, at least for this PR :)

[stefanv]

Having two syntaxes is confusing. Let's just move over to the newly proposed tag, make sure the change is mentioned in the release notes, and port the other websites that depend on it (there aren't that many).

[stefanv]

(If, that is, I understood correctly that removing .Inner will fix the problem.)

[agriyakhetarpal]

Having two syntaxes is confusing. Let's just move over to the newly proposed tag, make sure the change is mentioned in the release notes, and port the other websites that depend on it (there aren't that many).

(If, that is, I understood correctly that removing .Inner will fix the problem.)

Yes, I get this, but I think it would also be odd to have just the {{< figure >}} shortcode with the new named parameters syntax + dropping .Inner to support self-closing tags for it, and not any of the other shortcodes that are also using .Inner? Should I aim to port the rest of them, too? If we do, then it breaks a lot more content downstream (which I have no issues fixing, though!).

Edit: oh yes, it doesn't break things immediately though, as I think most websites use the theme as a submodule. It'd happen when they update to the new release where this is included.

[stefanv]

I suspect you're going to run into issues with some of the other shortcodes, such as cards.

But, I think you are right that we should be consistent.

Can we use the same pattern as here to make inline/in-body usage possible for those?

[agriyakhetarpal]

Yes, I think it should be possible. I think we can also keep it as is for shortcodes that are tricky to port or where it doesn't make sense to change. For example, the admonition shortcode:

{{< admonition hint >}}
This is an hint admonition.
{{< /admonition >}}

seems perfectly fine to me, as {{< admonition hint "This is an hint admonition." />}} looks a little off, and would not work for complex uses where someone may want a mixture of multiline strings + images + tables, and whatnot within the admonition... This is an example where the current one works well.

Here's a list of the shortcodes that I think can be ported:

1. button:

It would go from

{{< button success >}}
label: Success
link: http://example.com/
{{< /button >}}

to

{{< button success label = "Success" link = "http://example.com/" />}}

Similarly,

2. Dropdown (edit: removed this on 14/05/2025)
3. Image

---

The ones I think are fine as is:

1. Admonition
2. Card
3. Dropdown (as it's possible to use multiline strings + images + complex Markdown)
4. Details
5. Field List (uses TOML tables)
6. Grid (same as Field List)
7. Sidebar (as it supports nested shortcodes based on the provided example)
8. Tabs

---

The ones below don't use .Inner at all currently and are thus fine as is:

1. include-code
2. include-html
3. include-md
4. include-raw
5. include
6. toctree

---

I can port the button, dropdown, and the image shortcodes, unless you suggest otherwise! Another option is to just port figure and image for now, as both of them are closely related in terms of functionality.

[stefanv]

Yes, I think the rule would be: anything that calls for parameters in the body, we can port. With the exception of cards, because those parameters are actually content 🙄 😬

[agriyakhetarpal]

I'll finish up later today, thanks!

[goanpeca]

Having two syntaxes is confusing. Let's just move over to the newly proposed tag, make sure the change is mentioned in the release notes

Indeed it might be better to have just one. Thanks for the commentary and suggestions @stefanv!

I wanted to ask if we could limit the scope of the PR to what @agriyakhetarpal initially worked on and in a subsequent PR make all the additional changes.

We (quansight) are finishing the work for the scientific python translations grant and it would help of we can deploy numpy.org soonish which is currently blocked due to some issues with crowdin (the translations platform) not understanding the current shortcode syntax for figures and stripping all the content away.

I have already migrated the numpy figures over at numpy/numpy.org#859

I can help migrating other sites as well.

[jarrodmillman]

I would prefer to keep all the sites in sync as we have been doing. And sticking with official releases. Is there a reason this changes needs to be pushed out so fast?

[goanpeca]

We wanted to enable numpy sync which is currently broken due to crowdin not supporting the syntax.

I can work on the migration of the other shortcodes and we can go from there.

What are the sites currently using the theme so I can also prepare PRs to update the new syntax?

[goanpeca]

Hi @stefanv, I will continue working on this migration. Just to double check, we want to only support the new syntax with no closing tags for the shortcodes:

• figure
• button
• image
• dropdown

?

[goanpeca]

Hello team, thanks @agriyakhetarpal for the initial work.

I updated the shortcodes for

• figure
• button
• image
• dropdown

To make them work inline only with no closing tag.

I ran make doc-serve to check everything works out, but since tests seem to be running scipy.org, they are failing.

---

For the case of buttons it would become something like:

{{< button
    style="info"
    label="Info"
    link="http://example.com/" >}}

Since we cannot mix positional arguments and named ones.

[goanpeca]

[agriyakhetarpal]

Okay, the site is building and working well locally 🎉 but as the tests in CI run the SciPy website, they will show up as failed because it hasn't been updated for the new syntax yet.

@goanpeca and I have discussed this today, and I've sent out a list of all the websites that need to be ported with the new syntax once this PR gets merged and makes it to a release, and when the new release is used for those websites. The change for the figure shortcode in specific was tested out in numpy/numpy.org#859, and it worked well. Many thanks for finishing the rest of the shortcodes!

The list is as follows (please let me know if I missed any!)

Note

This list has been updated as per @goanpeca's comment below: #674 (comment)

Scientific Python core websites

• scientific-python.org
• learn.scientific-python.org no changes needed
• tools.scientific-python.org
• blog.scientific-python.org no changes needed
• devstats.scientific-python.org no changes needed
• specs.scientific-python.org

Downstream users of the theme

• numpy.org
• scipy.org
• pybamm.org
• https://pysathq.github.io/ will not be updated as they're using a release from three years ago, and there have been too many updates here (both functional and in terms of looks).

---

Also, post the porting of the shortcodes I managed to figure out the problem where the closing tags (>}}) for the shortcodes were being displayed as blockquotes – I realised that this happened only on the shortcodes page, and the single source of truth for what's being modified was in the render_shortcode_docs.py script. I've put out a fix in cd16575.

Overall, we now have the "figure", "image", "dropdown", and "button" shortcodes supporting named parameters, so this PR is ready for review/merging. Thank you!

[agriyakhetarpal]

Hi @goanpeca, I think we should forego the changes to the "dropdown" shortcode; I think we made an oversight. In another PR that I was working on just now (#675), I noticed that dropdowns can have content in the body parameter, which doesn't make sense to inline as inline parameters are not processed – which means that if one were to add something like a code block or a complex multiline string, it wouldn't work well.

Originally, in #674 (comment), I made the mistake where I added the "dropdown" shortcode to both headings – in the "ones to modify" and "those to keep as-is", when we should have kept it only in the as-is heading 😅 I've updated that comment, as I think it was the cause of some confusion! Similar to Stefan's comment in #674 (comment) about cards, one of the parameters to the dropdown(s) is actually content, too.

I converted the PR to a draft again so that I can undo these changes specifically, so that we support inline parameters for only the image, figure, and button shortcodes, and I will update the PR description, etc., again.

[goanpeca]

Hello team, I created PRs with the updated syntax in preparation for these changes.

• scipy: Update shortcodes scipy/scipy.org#648
• numpy: Update the use of inline shortcodes (figure, image, button) numpy/numpy.org#859
• pybann: Update figure shortcodes to new syntax pybamm-team/pybamm.org#283
• learn.scientific-python.org: no changes needed.
• scientific-python.org: Update shortcodes scientific-python.org#768
• tools.scientific-python.org: Update shortcodes tools.scientific-python.org#72
• blog.scientific-python.org: no changes needed.
• devstats.scientific-python.org: no changes needed.
• specs.scientific-python.org: Update shortcodes specs#394

[agriyakhetarpal]

Thanks for all of the downstream PRs, @goanpeca! I went through all of them, and all of them work as advertised (with the updated theme, of course). We should now be in a good position to update all the websites with minimal turnaround, and I assume we can also update the theme submodule in those PRs themselves as soon as this PR is merged into a new v0.22 release.

@stefanv, this should be ready for another look; whenever it is convenient for you to do so. Thank you! :)