Mention the shortcodes option in "Creating Shortcodes"

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.

Start by reading the linked Creating Shortcodes and Filters pages and compare how each documents project-level customization. Update the shortcodes documentation to mention the shortcodes.lua project option and align its guidance with the filters page; done means both pages clearly describe this supported approach.