From 6b35ed0a9658ca1cbe215af6880d40de848d68e2 Mon Sep 17 00:00:00 2001 From: John Emhoff Date: Mon, 5 Jun 2023 18:05:07 -0400 Subject: [PATCH] Shortcode documentation update (#2227) * Details about using shortcodes Explain how shortcodes differ from Tera template function calls * Add path search order to image processing docs I understand this is somewhat of an implementation detail, but it's required knowledge when you're trying to figure out why zola can't find your image. * Update shortcodes.md Drive home that shortcodes are completely unrelated to Tera * Update shortcodes.md Good grammar speak --- .../documentation/content/image-processing/index.md | 7 ++++++- docs/content/documentation/content/shortcodes.md | 10 ++++++++++ 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/docs/content/documentation/content/image-processing/index.md b/docs/content/documentation/content/image-processing/index.md index ac394ce4df..4acffe7615 100644 --- a/docs/content/documentation/content/image-processing/index.md +++ b/docs/content/documentation/content/image-processing/index.md @@ -14,7 +14,12 @@ resize_image(path, width, height, op, format, quality) ### Arguments -- `path`: The path to the source image relative to the `content` directory in the [directory structure](@/documentation/getting-started/directory-structure.md). +- `path`: The path to the source image. The following directories will be searched, in this order: + - `/` (the root of the project; that is, the directory with your `config.toml`) + - `/static` + - `/content` + - `/public` + - `/themes/current-theme/static` - `width` and `height`: The dimensions in pixels of the resized image. Usage depends on the `op` argument. - `op` (_optional_): Resize operation. This can be one of: - `"scale"` diff --git a/docs/content/documentation/content/shortcodes.md b/docs/content/documentation/content/shortcodes.md index fdadfb86de..55fbbc34c2 100644 --- a/docs/content/documentation/content/shortcodes.md +++ b/docs/content/documentation/content/shortcodes.md @@ -72,6 +72,16 @@ There are two kinds of shortcodes: In both cases, the arguments must be named and they will all be passed to the template. Parentheses are mandatory even if there are no arguments. +Note that while shortcodes look like normal Tera expressions, they are not Tera at all -- they can +pretty much just shuttle arguments to their template. Several limitions of note are: + +- All arguments are required +- The shortcode cannot reference Tera variables +- Concatenation and other operators are unavailable + +If the shortcode is invalid, it will not be interpreted by the markdown parser and will instead +get rendered directly into the final HTML. + Lastly, a shortcode name (and thus the corresponding `.html` file) as well as the argument names can only contain numbers, letters and underscores, or in Regex terms `[0-9A-Za-z_]`. Although theoretically an argument name could be a number, it will not be possible to use such an argument in the template.