Docs suggestion: explain what shortcodes are and what's like them

feature
1

I’d put something like the following right after the introductory paragraph in https://gohugo.io/templates/shortcode-templates/#creating-custom-shortcodes:

Shortcodes are a way to have template functionality in your content files with an easy, memorable way to pass text from your content files into a template that is expanded inside of your content. If you’d like to be able to easily pass information from a template into another template, have a look at dict.

1 Like
2

@adiabatic I agree that a definition of a shortcode in the first paragraph is a useful addition.

/cc @rdwatters

3

@adiabatic

Thanks for all the feedback. I appreciate it!

A few items

Shortcodes are already defined in the content management section:

That said, I repeated some of the content in the templating section per your suggestion:

Here it is live, along with a few other weird language issues I found during a quick review of the page:

As for the suggestion to add a reference to dict, this doesn’t seem like the right location. I think it’s better to describe shortcodes as the intermediary between templates and content and draw the comparison to partials (i.e., what I already had included in the above “What is a Shortcode” page section).

That said, you got me thinking about the value of providing more examples of the relationship between dict and partials:

I will likely have this updated/closed tonight, so stay tuned.

Note: I have two usage examples of partial and dict together already on dict's function page:

…in addition to the high-level description of said function, which descriptions are now included in every function via the new Functions quick reference.