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

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"`

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.