Mention the shortcodes option in "Creating Shortcodes"

[memeplex]

What would you like to do?

Report an issue on quarto.org

Description

Currently https://quarto.org/docs/extensions/shortcodes.html suggests that the only way to create a custom shortcode is by creating a new extension. This is a bit cumbersome for personal usage, e.g. I keep a repo of utilities as a subrepo/submodule of each of my different projects, for me a flat structure is more convenient in this case. Also for very basic shortcodes intended for a single project, creating an extension seems too much.

But shortcodes can be added to a project with minimal boilerplate, namely:

shortcodes:
  - shortcodes.lua

in the same way than custom filters. Unfortunately the documentation doesn't mention this for shortcodes. Moreover it does mention the analogue feature for filters in https://quarto.org/docs/extensions/filters.html, thus reinforcing the impression that it's not supported for shortcodes.

Please align both documents so that they make more obvious that this handy feature exists.

[memeplex]

I realized that this situation is similar for templates/formats, e.g. https://quarto.org/docs/output-formats/typst-custom.html.

Once you realize that all an extension does is to contribute features for options already available at the top level (filters, shortcodes, template, template-partials) all this is pretty clear. But the guide barely mentions this alternative and the reference just lists the options alongside a ton of other options for each output format (which is fine for a reference).