Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Shortcode documentation update #2227

Merged
merged 4 commits into from
Jun 5, 2023
Merged

Shortcode documentation update #2227

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
22286d6
Details about using shortcodes
JohnEmhoff Jun 5, 2023
4397f8b
Add path search order to image processing docs
JohnEmhoff Jun 5, 2023
69d5f2f
Update shortcodes.md
JohnEmhoff Jun 5, 2023
b5897ef
Update shortcodes.md
JohnEmhoff Jun 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion docs/content/documentation/content/image-processing/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"`
Expand Down
9 changes: 9 additions & 0 deletions docs/content/documentation/content/shortcodes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,15 @@ 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 a shortcode looks like a normal Tera template call, it is limited in several ways:
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might be better to say that it is not actually Tera at all

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good -- I pushed some changes that clarify this a bit.


- 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.
Expand Down