From b5505d22afa1c356dd10c225520a52bd700f6a28 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Fri, 23 Aug 2024 07:04:17 -0700 Subject: [PATCH] Clarify template lookup order for shortcodes --- content/en/templates/shortcode.md | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/content/en/templates/shortcode.md b/content/en/templates/shortcode.md index 6d9234f71..5587c7479 100644 --- a/content/en/templates/shortcode.md +++ b/content/en/templates/shortcode.md @@ -37,12 +37,29 @@ You can organize your shortcodes in subdirectories, e.g. in `layouts/shortcodes/ Note the forward slash. -### Shortcode template lookup order +### Template lookup order -Shortcode templates have a simple [lookup order]: +Hugo selects shortcode templates based on the shortcode name, the current output format, and the current language. The examples below are sorted by specificity in descending order. The least specific path is at the bottom of the list. -1. `/layouts/shortcodes/.html` -2. `/themes//layouts/shortcodes/.html` +Shortcode name|Output format|Language|Template path +:--|:--|:--|:-- +foo|html|en|layouts/shortcodes/foo.en.html +foo|html|en|layouts/shortcodes/foo.html.html +foo|html|en|layouts/shortcodes/foo.html +foo|html|en|layouts/shortcodes/foo.html.en.html + +Shortcode name|Output format|Language|Template path +:--|:--|:--|:-- +foo|rss|en|layouts/shortcodes/foo.en.xml +foo|rss|en|layouts/shortcodes/foo.rss.xml +foo|rss|en|layouts/shortcodes/foo.en.html +foo|rss|en|layouts/shortcodes/foo.rss.en.xml +foo|rss|en|layouts/shortcodes/foo.xml +foo|rss|en|layouts/shortcodes/foo.html.en.html +foo|rss|en|layouts/shortcodes/foo.html.html +foo|rss|en|layouts/shortcodes/foo.html + +Note that templates provided by a theme or module always take precedence. ### Positional vs. named arguments